Configuration Reference
Reference for Andromity's config.toml (every section and key), the files Andromity keeps on disk, and the environment variables it reads.
Andromity's settings live in config.toml, shared by the VS Code extension, the terminal app and headless andromity run. Most of it is easier to change from the app: API keys, the Model Hub, Preferences and Trust & Security. This page is the reference for editing it directly.
Where files are kept
The config folder holds config.toml and Andromity's local data:
| OS | Config folder |
|---|---|
| Windows | %APPDATA%\andromity |
| macOS and Linux | ~/.andromity |
Set ANDROMITY_CONFIG_DIR to use another folder.
| In the config folder | Contents |
|---|---|
config.toml | Settings, API keys and trusted folders |
sessions/, andromity.db | Your sessions and usage history |
skills/ | Skills installed for all projects |
model_*_cache.json | Cached model lists, context windows and prices |
andromity.log | Debug log (rotated at 5 MB, three files kept) |
A few files always live in .andromity in your home folder, also on Windows (%USERPROFILE%\.andromity):
In ~/.andromity | Contents |
|---|---|
mcp.json | MCP servers for all projects |
tokens.json | MCP sign-in tokens |
In a project, Andromity uses .andromity/ for project MCP servers (mcp.json), project skills (skills/) and cron jobs.
Example
[default]
provider = "anthropic"
model = "claude-sonnet-4-6"
profile = "builder"
permission_mode = "safe"
reasoning_effort = "auto"
telemetry = true
include_co_author = true
allowed_commands = ["npm run", "npm test", "git status", "git diff", "git log", "ls", "cat", "echo"]
allowed_domains = ["docs.python.org"]
[user]
name = "Alex"
email = "alex@example.com"
[[providers]]
name = "anthropic"
type = "anthropic"
api_key = "$ANTHROPIC_API_KEY_WORK"
[[providers]]
name = "lmstudio"
display_name = "LM Studio"
type = "openai"
base_url = "http://localhost:1234/v1"
model = "qwen2.5-coder-7b-instruct"
[models]
pinned = [{ id = "claude-sonnet-4-6", provider = "anthropic", name = "Claude Sonnet 4.6" }]
[subagents]
max_concurrent = 5
timeout_seconds = 600
[[subagents.roles]]
name = "search"
model = "gemini-2.5-flash"
provider = "google"
[advanced]
auto_compact = true
max_file_size_kb = 500
[tools]
default_timeout_seconds = 300
[collaboration]
max_auto_wakes = 2[default]
| Key | Default | Meaning |
|---|---|---|
provider | andromity | Active connection ID. See API keys. |
model | auto | Active model ID, as the provider names it. |
profile | builder | Default profile: builder, coder, reviewer or planner. |
permission_mode | safe | Default permission mode: safe, trust, full or yolo. |
reasoning_effort | auto | auto, a level the model supports (such as low or high), or budget:<tokens>. |
allowed_commands | 11 common read-only and npm commands | Commands TRUST mode runs without asking. See Allowlists. |
allowed_domains | none | Domains TRUST mode fetches without asking. |
telemetry | true | Anonymous usage telemetry. See Preferences. |
include_co_author | true | Add the Andromity co-author trailer to commits. |
sound_done, sound_attention | true | VS Code sounds when a turn finishes or needs approval. |
expand_tools_while_working | true | Terminal app: show tool details expanded while the agent works. |
[[providers]]
One table per connection. Built-in connections need only name, type and, if you use one, api_key.
| Key | Meaning |
|---|---|
name | Connection ID, such as anthropic or lmstudio. |
type | LiteLLM adapter: the provider ID for built-in connections, openai for OpenAI-compatible servers, or another LiteLLM provider. |
api_key | The key, or $VARIABLE to read it from an environment variable. |
base_url | API root for custom, Ollama or gateway connections. |
model | Model ID for a custom connection. |
display_name | Name shown in the app. |
api_version | API version for adapters that need one, such as azure. |
See Custom providers for the validation rules.
Other sections
| Section and key | Default | Meaning |
|---|---|---|
[user] name, [user] email | empty | Your name and email from Preferences. Not sent to the model. |
[models] pinned | Andromity Auto and Claude 3.7 Sonnet | Pinned models in the Model Hub. |
[subagents] max_concurrent | 5 | Subagents that can run at once. |
[subagents] timeout_seconds | 600 | Time limit for one subagent. |
[subagents] result_max_tokens | 750 | Longest result a subagent returns. |
[[subagents.roles]] | none | Per-role model, provider, tools, description, system_prompt and temperature. Roles: search, coder, reviewer, analyst, general. |
[advanced] auto_compact | true | Compact long conversations automatically. |
[advanced] max_file_size_kb | 500 | Largest file read_file reads. |
[tools] default_timeout_seconds | 300 | Time limit for one tool call. |
[collaboration] max_auto_wakes | 2 | Automatic wake-ups in a row before a session waits for you. |
[trusted_projects.<key>] | none | Trusted folders. Managed by the app. |
Editing by hand
- Andromity rewrites the whole file when it saves a setting, so comments are removed and keys may be reordered.
- If the file has a syntax error, Andromity keeps it as
config.toml.unreadable-<time>next toconfig.tomland starts with default settings. VS Code warns you and offers Open Saved Copy; the terminal app prints the copy's path. Fix the copy, copy it overconfig.toml, and restart. - Changes made by hand apply the next time Andromity starts. In VS Code, run Andromity: Restart Engine / Server or reload the window.
- The agent can't read or edit
config.tomlfor you; it is a protected file.
Environment variables
| Variable | Effect |
|---|---|
ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY or GOOGLE_API_KEY, DEEPSEEK_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, NVIDIA_API_KEY or NVIDIA_NIM_API_KEY, ANDROMITY_API_KEY | Provider keys, used when config.toml has none. See API keys. |
ANDROMITY_CONFIG_DIR | Use this folder instead of the default config folder. |
ANDROMITY_SKIP_CONFIG_SAVE=1 | Never write config.toml. Useful for read-only or shared setups. |
DO_NOT_TRACK=1, ANDROMITY_NO_TELEMETRY=1, CI=1 | Turn off telemetry. |
ANDROMITY_AIRGAP=1 | Block the agent's own network use. See Air-gap mode. |
ANDROMITY_SKILLS_CATALOG_URL | Load the skills catalog from another URL. |
ANDROMITY_RG_PATH | Path to a ripgrep binary for file search. |
Variables must be set in the environment Andromity starts in. For VS Code, set them before starting VS Code.
Data and privacy
- Model requests go to the provider you choose. Cloud providers receive the prompt and the code context the task needs. The Andromity gateway forwards requests without storing prompts, completions or code. Ollama and other local endpoints run on your machine.
- Sessions are stored only on your machine, in the config folder.
- Telemetry is anonymous and can be turned off; see Preferences.
Personalisation
Customise how Andromity looks in VS Code. Turn the Andro-Pet companion on or off and set up the ambient wallpaper, water ripples, floating particles and cursor spotlight.
Terminal CLI Commands and Shortcuts
Reference for Andromity terminal commands, slash commands, headless andromity run options, background processes, and keyboard shortcuts.