py-gpt ships five installers and pins every dependency to one version

Five install routes, and one of them asks per feature

The installation section is the longest part of the documentation and it is entirely about packaging.

There is a prebuilt route: an installer package on Windows, and an archive on Linux with an explicit requirement that the C library be at version 2.35 or newer. That floor is a real constraint, because it decides which Linux distributions can use the binary at all. macOS is pointed at the package index or a source install instead.

There is a store listing on Windows, and an AppImage on Linux, which you make executable before the first run and can update incrementally with a separate tool if you want. And there is a Snap package, installed and refreshed with elevated privileges.

sudo snap install pygpt

and to update an existing one:

sudo snap refresh pygpt

Camera and microphone are separate connections:

sudo snap connect pygpt:camera

The Snap route has the detail worth knowing. Optional interfaces are requested only for the features that need them, so camera access and microphone access are separate connections rather than permissions granted to the whole application. That is confinement done properly, and it is the one packaging route where the documentation explains the security model rather than just the mechanics.

macOS bundles are configured in the tree and never documented

The root listing contains configuration files for platforms the installation section does not cover.

Two files are macOS application bundle property lists, one named for macOS and one for Windows by convention. Those are the descriptor files that give a bundle its icon, version and identifier, so their presence means a macOS application bundle is built by this repository.

There is also a desktop entry file for Linux, a Windows version resource script that compiles version metadata into the executable, and build specification files for two platforms, which is how the prebuilt binaries are produced. A separate configuration file builds the AppImage.

So five packaging formats, a desktop entry, and a Windows resource script. Yet the installation section offers macOS two routes only, both of which are source-based. A macOS user who wants a double-clickable bundle is reading the tree, not the documentation.

That gap is worth naming because the rest of the packaging story is thorough. Someone clearly worked out how to build for every platform; the README just stopped short of describing one of them.

Dependencies are pinned to exact versions, with one exception

The build manifest lists roughly twenty direct dependencies and almost every one is pinned to a single version with no range at all.

Pinned exactly are the model provider client, a cloud SDK, an HTML parser, two AWS packages that must move together, a vector store, a cron parser, the Docker client, a document text extractor, a search client, an ebook library, a Google Keep client, two Google API clients, a gRPC package, two HTTP clients including one with SOCKS support, and the model hub client with an extras flag.

There is exactly one entry with a range, and it is written as an exclusion rather than a floor, allowing anything from a given version except one specific release.

The consequence is predictable. For an application that ships as a binary and talks to a dozen paid APIs, pinning the whole stack means the tested configuration is the only configuration, which is genuinely valuable when a provider changes a response format. The cost is that an upstream security fix in any of those twenty packages requires editing the manifest and cutting a release, and the release history shows releases cut several times a week, so that cost is evidently being paid.

The lock file carries interpreter shims for a four version span

The declared support window is Python 3.10 up to but not including 3.14, and the dependency lock encodes that span rather than assuming it.

Every line in the lock carries environment markers. Some packages are restricted to interpreters at or below one version. Some are conditioned on the full version string being below a specific patch release, which is the kind of detail you only add after hitting a bug on one patch level. One package is marked for macOS only. One is marked for exactly one interpreter version, and it is a backport of a module that was removed from the standard library, present so the application keeps working on the newest interpreter it claims to support.

So the four-version support claim is not aspirational. Somebody traced the breakage points and encoded the workarounds.

One gap sits alongside it. The package metadata classifies support only as Python 3 in general, with no specific minor versions listed, even though the manifest requires a specific range. Tools that read classifiers to decide installability will see a much wider range than the project actually supports.

The extension surface is nine named seams

The examples directory is organised by extension point rather than by feature, which tells you what the maintainers consider stable.

There is one worked example for each seam: an agent, audio input, audio output, a data loader, a language model, a plugin, a tool, a vector store, and web search. Plus a custom launcher example and a directory for add-ons.

Nine seams is a lot of surface, and having an example per seam is how you can tell a seam is meant to be public rather than incidental. Each example is a single file, so the contract for each extension point is demonstrated in something short enough to read.

The protocol connector story is separate and broader. Beyond the general protocol support, there is a manager for connectors with a browsable catalogue, and it can import configuration from a list of other tools and editors, or from generic configuration files in three formats. So the design assumes your agents are already configured somewhere else and tries to read that configuration rather than making you re-enter it.

A separate add-ons repository exists for anything that did not fit as a seam.

The runtime is privileged, and the documentation does not pretend otherwise

The feature list describes a tool that acts on your machine, not one that talks to you.

It will execute Python and notebook code and system commands in real time. It will control the desktop or the browser when enabled. It carries a task scheduler. It does file input and output. It captures from the camera and draws on a canvas with browser integration. It can run scheduled tasks and expose your own scripts as tools.

The authentication model is stated in one sentence and it is the right one: cloud providers use your own credentials, and models served from a local runtime need no external key at all, with the caveat that particular providers and integrations may need their own.

Read together, that is a clear trust boundary. Nothing is proxied through the project; the application talks to providers directly with keys you supply. And in exchange for not being a service, it asks for the ability to run code as you.

If you are evaluating this, the question is not whether the features are powerful. They plainly are, and the list runs to around forty-five entries. The question is whether a tool that can execute commands and drive your browser belongs on a machine holding credentials you would mind losing.

Windows and Unix launchers are maintained in pairs

The root listing shows a pattern that is easy to miss and expensive to ignore.

Every launcher exists twice. There is an install script for Windows and one for Unix, a run script for each, and a desktop shortcut script for each. Two build specification files produce the prebuilt binaries for the two platforms that have them, and a separate configuration produces the Linux AppImage.

That is three script pairs to keep in step, and a change to how the application finds its data directory or its configuration has to be made four times. It is the cost of supporting a platform where the shell is not the shell.

The launch scripts for the other two major platforms are less visible: the macOS route runs through the package index or source, and the Windows store route handles its own launcher. So the pairing applies to the two platforms built from binaries, and the other two avoid the problem by not shipping a shell script at all.

One documentation detail rounds this out. The screenshots in the overview are labelled with an older version than the release line at the top of the file. The mismatch is disclosed rather than hidden, which is the same pattern this project uses throughout: the packaging story is thorough, and the caveats are stated instead of smoothed over.

Editorial conclusion

This is a broad assistant rather than a narrow tool, and the breadth is the point: if you want one local application that talks to several model providers, runs retrieval over your files, and can drive tools, this has all of it in one place. Two things to weigh before you install it. It can execute Python and system commands and control the desktop or browser, so it runs with your privileges and the credentials you paste are yours. And every dependency is pinned to an exact version, which makes builds reproducible at the cost of requiring a release for each upstream security fix. Decide which of those tradeoffs suits you before you wire your own keys into it.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. szczyglis-dev/py-gpt on GitHub