Environment variables

Every environment variable agentty reads, grouped by what it affects. Nothing here is required: agentty runs with none of them set. Reach for one when you need to override a default, debug a problem, or script a headless run.

Persistent preferences belong in settings (the config overlay, Ctrl+S) — environment variables are for per-invocation overrides and diagnostics.

Diagnostics

One log, one switch. See Logging & diagnostics for the channel list and line format.

Providers & models

Smart Mode

Off by default and a byte-for-byte no-op when off — see Smart Mode.

Context window

agentty learns a model's context window from three places, most specific first: your override, then what the provider advertised, then what the model id implies. Nothing known falls back to a conservative 200k.

That middle layer is why most setups need no configuration — the /v1/models listing is read for model_info.max_input_tokens (LiteLLM), context_length and top_provider.context_length (OpenRouter), max_model_len (vLLM), and n_ctx (llama.cpp). Where a row advertises both a catalog window and the serving endpoint's, the serving one wins: it is the one that will reject an over-long prompt.

But a gateway is not obliged to say anything — OpenAI's own /v1/models schema is just {id, object, created, owned_by} — so when every layer comes up empty the picker shows auto and the turn runs on the conservative default. For that case:

| Variable | Effect | |---|---| | AGENTTY_MAX_CONTEXT_TOKENS | The window to assume when nothing else knows one. Spelled to mirror Claude Code's CLAUDE_CODE_MAX_CONTEXT_TOKENS, so it is guessable if you have hit this before. |

It is consulted last, after the catalog, the probe and the model id, so it only speaks when nothing better did — it is global, and a session that reaches several models should not apply one number to all of them.

In practice almost nothing needs it: between the /v1/models listing, the endpoint probes and models.dev, discovery covers nearly every provider agentty ships. What is left is the genuinely unknowable case — a private gateway serving an id no catalog has published.

Retrieval (RAG)

Full detail in Retrieval. Most default sensibly; the common ones are AGENTTY_DOCS_DIR and AGENTTY_EMBED_MODEL.

Tools, MCP & ACP

Security & storage

Keeping config local and bulk elsewhere

AGENTTY_HOME moves everything. The per-directory variables move one thing each, usually the parts that grow:

export AGENTTY_THREADS_DIR=/mnt/data/agentty/threads
export AGENTTY_LOGS_DIR=/mnt/data/agentty/logs

Use agentty config move threads /mnt/data/agentty/threads to bring existing data along; it prints the export line to add.

See Storage for every file and how long it stays.

Retrieval indexes are per-project

AGENTTY_RAG_DIR is the odd one out, because the data is. Retrieval indexes are keyed to the tree that produced them — they are meaningless away from it, and sharing one between unrelated checkouts would invalidate it constantly — so they default to <project>/.agentty rather than anywhere under AGENTTY_HOME. Only AGENTTY_RAG_DIR and AGENTTY_PROJECT_DIR move them.

They are also the biggest thing agentty writes per project: on the agentty repo itself, 31 MB of code index and 7 MB of docs index. If your code already lives on a roomy disk they follow it and there is nothing to do. If it does not:

export AGENTTY_RAG_DIR=/mnt/data/agentty/rag

With the override set, each project gets its own readable subdirectory (myrepo-04b42962/) so two checkouts pointed at one location do not fight over the same file.

The "project" is the nearest enclosing directory containing .git, .agentty, .hg or .svn — not the directory you launched from. So cd src/ && agentty reuses the index at the repo root instead of building a second one beside it.

Superseded indexes are reclaimed

The filename carries an identity tag for the embedding backend that built it (rag_code.e45ba1de.ragdb), so changing backends can never serve vectors from an incompatible space. The cost is that the filename set grows every time you switch.

After a successful index write, agentty deletes superseded variants — keeping the live one plus the most recent previous one, so A/B-ing two backends does not force a full rebuild each time you switch back. Untagged indexes from before the tag existed are removed outright: no current build can read them.

Two deliberate limits. Variants newer than an hour are left alone, since another agentty process may be mid-write. And if any file in the directory cannot be examined, nothing is deleted at all — being wrong about what is present should cost disk, not data.

Details worth knowing:

• A relative value is resolved against the root, not your current directory — AGENTTY_LOGS_DIR=logs2 always means ~/.agentty/logs2.
• An empty value counts as unset, so an exported-but-blank variable relocates nothing.
• If a directory can't be created (unmounted drive, a file in the way), agentty prints one warning and falls back to the default rather than losing the data silently.
• An overridden threads directory is forced to 0700, because conversation history is as sensitive as the credentials it used to sit beside.

Symlinking the subdirectories works too, and predates these variables: ln -s /mnt/data/agentty-logs ~/.agentty/logs.

Interface

Development & testing

Not for normal use. Listed so a reader of the source isn't left guessing.

Variables agentty reads from your environment

Standard variables consulted for platform behaviour, listed for completeness: HOME / USERPROFILE / HOMEDRIVE + HOMEPATH · XDG_CONFIG_HOME · APPDATA · PATH · USER / USERNAME · SUDO_USER · HOSTNAME · COLUMNS / LINES · DISPLAY / WAYLAND_DISPLAY / XDG_SESSION_TYPE · SSH_CONNECTION / SSH_CLIENT / SSH_TTY / SSH_AUTH_SOCK · MOSH_CONNECTION / MOSH_KEY / MOSH_SERVER_PID · INSIDE_EMACS.