Skip to content

configuration.md

Latest commit

 

History

History
207 lines (144 loc) · 9.42 KB

configuration.md

File metadata and controls

207 lines (144 loc) · 9.42 KB
Raw

Configuration

Acolyte merges user and project configuration for models, providers, localization, logging, memory, lifecycle behavior, and feature flags.

Paths (see Paths for platform-specific details):

  • user: config dir + config.toml
  • project: <cwd>/.acolyte/config.toml, where ACOLYTE_PROJECT_DIR replaces <cwd> when set

Common commands

acolyte config list
acolyte config set model gpt-5-mini
acolyte config set locale en
acolyte config set --project logFormat json
acolyte config unset openaiBaseUrl

Provider auth

acolyte auth authenticates providers with an API key or, where supported, a subscription:

acolyte auth                         # pick a provider from the list, then how to authenticate
acolyte auth openai                  # pick key or subscription from the list
acolyte auth openai --key            # store OPENAI_API_KEY
acolyte auth openai --subscription   # browser OAuth
acolyte auth vercel --key            # store AI_GATEWAY_API_KEY
acolyte auth openai --logout         # remove stored credentials for openai
acolyte auth openai --logout --key   # remove only OPENAI_API_KEY
acolyte auth openai --logout --subscription # remove only the subscription

Both lists are chosen with the arrow keys; enter confirms and esc cancels. Without a terminal — a pipe, a script, CI — acolyte auth prints provider status instead of asking, and a provider supporting both methods needs --key or --subscription.

API keys are written to <configDir>/credentials (mode 0600), the same file acolyte login uses. Subscription tokens are stored separately in <configDir>/oauth.json. auth asks for confirmation before replacing stored credentials.

Acolyte reads each provider key from the environment first, then the credentials file. Any variable in the process environment — exported in your shell, injected by CI, or loaded from a project .env — takes precedence over the stored key.

Providers: anthropic (ANTHROPIC_API_KEY), google (GOOGLE_API_KEY), openai (OPENAI_API_KEY), vercel (AI_GATEWAY_API_KEY). acolyte status and acolyte auth list which providers are configured and how they authenticate.

Vercel AI Gateway (recommended)

The fastest way to get started. The Vercel AI Gateway provides unified access to 20+ providers with a single API key.

acolyte auth vercel --key
acolyte config set model anthropic/claude-sonnet-4

When a direct provider key is also set (e.g. ANTHROPIC_API_KEY), Acolyte prefers the direct connection. When it's missing, requests fall back to the gateway automatically — no prefix or config change needed.

Acolyte enables AI Gateway automatic prompt caching on gateway requests. For direct Anthropic requests, Acolyte marks stable system and tool prefixes for ephemeral prompt caching. OpenAI-hosted models use stable prompt cache keys when supported, and Google models use provider-side implicit caching when available.

# Explicitly target a provider only available through the gateway
acolyte config set model vercel/xai/grok-4.1

# Override the gateway base URL
acolyte config set vercelBaseUrl https://custom-gateway.example.com/v1

OpenAI subscription

Authenticate OpenAI with a subscription instead of (or in addition to) an API key:

acolyte auth openai --subscription

This runs a browser OAuth flow (loopback callback on port 1455, required by OpenAI) and stores the tokens in <configDir>/oauth.json (mode 0600). Tokens refresh automatically.

The models your subscription serves then route through it. Other OpenAI models fall back to OPENAI_API_KEY when one is set, or return an error asking for a key. A subscription and an API key can be active at once — acolyte status and acolyte auth report the methods in effect — and acolyte auth openai --logout removes both the stored key and the subscription for that provider.

Provider base URLs

Each provider has a configurable base URL with a sensible default:

  • openaiBaseUrl — OpenAI API base (default: https://api.openai.com/v1). Set to a local endpoint for OpenAI-compatible providers (Ollama, vLLM, etc.).
  • anthropicBaseUrl — Anthropic API base (default: https://api.anthropic.com/v1). Must end with /v1.
  • googleBaseUrl — Google AI API base (default: https://generativelanguage.googleapis.com).

Local models

Configure an OpenAI-compatible local endpoint directly in project config, then set the model explicitly:

acolyte config set --project openaiBaseUrl http://localhost:11434/v1
ollama pull <model>
acolyte config set --project model openai-compatible/<model>

Local embeddings

Keep chat on its configured provider while routing semantic memory to an OpenAI-compatible embedding endpoint:

acolyte config set embeddingModel nomic-embed-text
acolyte config set embeddingBaseUrl http://localhost:11434/v1
ACOLYTE_EMBEDDING_API_KEY=ollama acolyte run "..."

embeddingBaseUrl is a user-scoped route for embedding requests only. Its API key is read from ACOLYTE_EMBEDDING_API_KEY or the private credentials file, never project configuration. HTTP is allowed only for localhost; remote endpoints must use HTTPS.

It is deliberately not project-scoped: a repository-controlled config must not redirect memory queries or a private embedding credential to an arbitrary endpoint.

Localization

  • locale — active UI language, and the language the model writes its replies in (defaults to en). It is user-scoped: the language a person reads in follows them across projects, so a repository cannot set it.
  • Messages are authored in src/i18n/*.arb and compiled into the binary; see localization for adding a language.

Logging

  • logFormat — log output format (logfmt | json, default: logfmt).

logfmt emits one key=value line per entry:

2026-03-20T12:00:00.000Z level=info msg="request started" model=gpt-5-mini

json emits one JSON object per line with typed fields:

{"ts":"2026-03-20T12:00:00.000Z","level":"info","msg":"request started","model":"gpt-5-mini"}
acolyte config set logFormat json

MCP servers

Connect Acolyte to external services (Figma, Jira, Notion, Chrome DevTools, etc.) via MCP servers. Configure servers under the mcpServers key in .mcp.json at the project root.

MCP is disabled by default. Enable it explicitly with:

acolyte config set --project features.mcp true

The equivalent TOML is:

[features]
mcp = true

Only enable MCP in trusted repositories. .mcp.json is project-controlled and stdio servers execute local commands.

Two transports are supported:

  • stdio — server runs as a local subprocess (command, args, optional env). Only a minimal set of environment variables is forwarded to the subprocess (PATH, HOME, SHELL, TERM, USER, LANG, LC_ALL, TMPDIR, XDG_RUNTIME_DIR) plus any explicitly configured in env.
  • http — server is reachable over HTTPS (url, optional headers). Non-HTTPS URLs are allowed for localhost (127.0.0.1, ::1) but blocked for remote hosts.

Each server's tools appear in the agent alongside native tools. If a server is unreachable at task start it is skipped with a warning and the lifecycle continues.

Installed plugins contribute servers too, namespaced by plugin name and requiring features.plugins as well. See Plugins.

Feature flags

Feature flags are opt-in toggles for experimental behavior, configured under [features] in config.toml and set from the CLI with dotted keys.

Enable via TOML:

[features]
undoCheckpoints = true

Enable via CLI:

acolyte config set features.undoCheckpoints true

Available flags

Flag Description
undoCheckpoints Write tools create undo checkpoints under .acolyte/undo/<sessionId>/. The model can list and restore via undo-list and undo-restore.
workspaces Enable /workspaces chat commands for managing git worktrees and workspace-scoped sessions.
cloudSync Use the cloud API for memory and session storage. Requires acolyte login.
mcp Opt-in: load MCP servers from .mcp.json and expose their tools to the agent.
plugins Opt-in: load Agent Plugins from .agents/plugins, contributing their skills and — with mcp also on — their MCP servers.

All settable keys

Key Description
port daemon server port (default: 6767)
locale UI and reply language (default: en)
model model
reasoning reasoning level for supported models (low, medium, high)
openaiBaseUrl OpenAI API base URL
anthropicBaseUrl Anthropic API base URL
googleBaseUrl Google AI API base URL
vercelBaseUrl Vercel AI Gateway base URL
logFormat log output format (logfmt or json)
embeddingModel embedding model for semantic recall
embeddingBaseUrl explicit OpenAI-compatible embedding API base URL
distillModel model used for memory distillation
replyTimeoutMs max reply wait time in ms (min 1000, default 180000)
features.undoCheckpoints opt-in: capture write-tool undo checkpoints
features.workspaces opt-in: enable /workspaces chat commands
features.cloudSync opt-in: use cloud API for memory and session storage
features.mcp opt-in: enable MCP servers from .mcp.json
features.plugins opt-in: enable Agent Plugins from .agents/plugins