# gptme: a terminal-first agent CLI you can point at any model

> gptme is a Python agent that runs in a terminal, talks to Anthropic, OpenAI, OpenRouter or a local llama.cpp server, and executes shell, Python and file edits on your machine. It is a good fit if you want to self-host the loop; it is a poor fit if you want a sandbox by default.

**gptme/gptme** — Your agent in your terminal, equipped with local tools: writes code, uses the terminal, browses the web. Make your own persistent autonomous agent on top!

- Repository: https://github.com/gptme/gptme
- Website: https://gptme.org/docs/
- Stars: 4,438 · Forks: 445
- Language: Python
- License: MIT
- Published: 2026-09-09 · Updated: 2026-09-09 · Language: en
- Canonical page: https://hysenlabs.com/projects/gptme-gptme

## What gptme solves for people who live in a shell

The project describes itself as a personal AI agent that runs anywhere a terminal runs: a laptop, an ssh session, tmux, a headless server, a CI pipeline. That framing is the product decision. gptme is not a code editor with a chat panel bolted on. It is a command you start, which then has access to shell, Python, web and vision tools, and which keeps a conversation log you can resume. The intended user is someone who already works over ssh and wants the agent in the same place as the work, rather than in a separate window that cannot see the filesystem. The README positions it as a capable alternative to Claude Code, Codex, Cursor and Warp, and notes the first commit dates to March 2023, making it one of the earlier agent CLIs. That history matters less than the current shape: provider-agnostic, local-first, and unconstrained are the three words the README uses, and the third is the one to think about hardest.

## The mechanism: a tool loop over a persistent conversation log

gptme is a Python package that installs a family of console scripts. The main one is gptme, with gptme-tui for a terminal UI, gptme-server for an HTTP API, and a long tail of utilities including gptme-doctor, gptme-auth, gptme-resume, gptme-checkpoint and gptme-agent. The loop is the familiar one: your prompt goes to a provider, the model returns a tool call, gptme executes it locally, feeds the result back, and repeats. What distinguishes the implementation is where state lives. The Docker Compose file mounts two volumes, gptme-config at /home/gptme/.config/gptme and gptme-data at /home/gptme/.local/share/gptme, and comments that these persist config, credentials and conversation logs across restarts. That is the persistence model in one line: conversations are files on disk, not rows in a hosted service. Configuration is read from a .env file or your shell environment, and at least one provider key is required. The pyproject file declares Python >=3.10,<3.15 and MIT licensing, and registers two internal plugins, auto_snapshots and aw_watcher_agent, through the gptme.plugins entry point group, which is how the extension surface is wired.

## Installing gptme and running a first session

The README points to https://gptme.org/docs/getting-started.html for installation, and the repository ships several paths. The Makefile builds with Poetry, and the package is published on PyPI, so a pipx install is the shortest route to a working command. Set a provider key first; the .env.example lists OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY and REQUESTY_API_KEY as the supported variables.

```bash
pipx install gptme
gptme "list the Python files in this directory"
```

The first command installs the CLI. The second starts an interactive session with a single instruction; you should see the model propose a tool call and gptme print the result before returning control to you. Exporting a provider key in the same shell is what the .env.example expects before a conversation can run.

If you would rather not install Python packages on the host, the Compose file is the self-hosted route. Copy the example environment file, fill in one key, and bring up the server service.

```bash
cp .env.example .env
docker compose up --build
```

The gptme-server service publishes port 5700 by default, configurable through GPTME_SERVER_PORT, and serves a bundled web UI from the same origin. The Compose comments state that auth is enabled by default when the server binds to 0.0.0.0, and that if GPTME_SERVER_TOKEN is left blank the server generates one at startup, which you retrieve with docker compose logs. There is a second service, computer-use, for a sandboxed desktop with VNC streaming, started with docker compose up --build computer-use and reachable on ports 6080 and 8080. Before running anything that touches your real setup, gptme-doctor exists as a console script and is the obvious first diagnostic.

## Where gptme gives you more rope than you may want

The README's own word is unconstrained, and that is the honest framing of the main risk. gptme ships with shell and Python execution as first-class tools. Nothing in the documentation describes a default sandbox around those tools when you install the CLI on your host. The container path is the isolation story, and it is opt-in: you have to choose Compose, or the computer-use image, rather than getting a boundary for free. A second limitation is provider-side. Because gptme is provider-agnostic, output quality and tool-calling reliability track whichever backend you configure, and the README does not promise parity between them. Local llama.cpp is listed as an option, but the documentation gives no guidance on which local models handle multi-step tool calls well. Third, the server enables authentication by default and auto-generates a token when none is supplied; if you skim past that, you will find yourself locked out of your own instance until you read the logs. Finally, the demos in the README are explicitly labelled as being from 2023, with a note that the project has evolved a lot since. Treat the screencasts as historical, not as a current walkthrough.

## gptme against Aider and OpenHands

Aider is the closest comparison a terminal user will reach for, and the difference is scope. Aider is built around editing code in a repository with a diff-oriented workflow. gptme is general purpose: the README says it is a great coding agent but general-purpose enough to assist in all kinds of knowledge-work, and the tool set includes web browsing and vision alongside shell and Python. If your task is refactoring a codebase, a diff-first tool is a tighter fit. OpenHands takes the other direction, running the agent in a sandboxed environment with a browser and a workspace as the primary abstraction. gptme's equivalent is the optional computer-use container, not the default mode. The practical distinction is where the trust boundary sits: gptme assumes you are running it where you already have authority, and you add isolation if you want it; OpenHands-style designs put the boundary in the architecture. Neither is strictly better, but they fail differently, and gptme's failure mode is your own shell.

## Maintenance, licensing and the upgrade path

The repository is not archived and the last push was on 2026-09-09, so the project is under current development by any reasonable reading. The release cadence visible in the repository is fast and slightly unusual: the three most recent releases are all dev-tagged builds, v0.33.1.dev20260903, v0.33.1.dev20260831 and v0.33.1.dev20260827, while pyproject.toml declares version 0.33.0. That gap between the declared version and the published dev tags is worth knowing before you pin a version in a lockfile. Upgrading means reinstalling the CLI or rebuilding the container images, and the Compose volumes mean your conversation logs and credentials survive that rebuild, which is convenient and also means a bad upgrade does not roll your state back. The project is MIT licensed, which permits commercial and private use with the usual requirement to keep the copyright notice; the repository does not discuss third-party model provider terms, and those are separate agreements you accept when you set a provider key. Nothing here is legal advice.

## Conclusion

Adopt gptme if you work in a terminal, want to choose the model provider per session, and are willing to run it inside a container or a throwaway checkout. Skip it if you need a sandbox on by default or a GUI-first workflow, because the CLI executes tools in your own shell and the README does not document an isolation boundary for that path. Before committing, run gptme-doctor and confirm which provider key it picks up, then start a session in a scratch directory and read the tool calls before approving anything that writes outside it.

## FAQ

### Can gptme run against a local model instead of a hosted API?

Yes. The README lists fully local operation via llama.cpp as a supported option alongside Anthropic, OpenAI, Google, xAI, DeepSeek and OpenRouter. The documentation does not say which local models handle multi-step tool calls reliably, so that is something to determine yourself.

### How do I set the API key gptme uses?

Set one of the provider keys in your shell environment or in a .env file. The .env.example lists OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY and REQUESTY_API_KEY, and notes that at least one is required for gptme to run conversations.

### Does gptme run in Docker?

The repository ships a docker-compose.yml with two services. gptme-server builds an API server with the web UI on port 5700, and computer-use builds a sandboxed desktop with VNC streaming, started with docker compose up --build computer-use and reachable on ports 6080 and 8080.

### What is the gptme server auth token and where do I find it?

gptme-server enables auth by default when bound to 0.0.0.0. If you leave GPTME_SERVER_TOKEN blank, the server auto-generates a token at startup, and the .env.example says to find it with docker compose logs.

## Sources

- [gptme/gptme on GitHub](https://github.com/gptme/gptme)
- [License: MIT](https://github.com/gptme/gptme/blob/master/LICENSE)
- [Project website](https://gptme.org/docs/)
- [README](https://github.com/gptme/gptme/blob/master/README.md)
- [Releases](https://github.com/gptme/gptme/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gptme-gptme