Configuration reference
Use this page when you need the exact local file path or environment variable name. Everything here reflects the current codebase rather than a planned interface.
i
Recommended path
Use
attach setup or attach connect <runtime> whenever possible. Those flows write ~/.attach/config.json for you and avoid most manual configuration mistakes.CLI config file
The CLI reads and writes ~/.attach/config.json. The file is created with private permissions and usually contains the API URL, API key, and an optional default namespace.
~/.attach/config.jsonjson
{
"api_url": "http://localhost:2009",
"api_key": "arun_agt_...",
"default_namespace": "my-namespace"
}Manual attach config defaults its API URL flag to https://api.attach.dev, so pass --api-url explicitly if you are targeting a local API server.
API server environment
| Variable | Default | Notes |
|---|---|---|
| DATABASE_PATH | ./data/attach.db | SQLite database file. |
| BLOB_STORAGE_PATH | ./data/blobs | Legacy blob fallback path plus local git artifact storage root. |
| SESSION_SECRET | required | Required. Used for session cookies and HMAC hashing. |
| PORT | 2009 | API server listen port. |
| NODE_ENV | development | Affects secure cookies and public URL validation behavior. |
| CORS_ORIGINS | derived | Comma-separated allowlist. Falls back to FRONTEND_ORIGIN or localhost in development. |
| FRONTEND_ORIGIN | none | Fallback used when CORS_ORIGINS is not set. |
| AUTH0_DOMAIN | required for browser login | Auth0 tenant domain. |
| AUTH0_CLIENT_ID | required for browser login | Auth0 application client ID. |
| AUTH0_CLIENT_SECRET | required for browser login | Auth0 application client secret. |
| AUTH0_CALLBACK_URL | required for browser login | Callback URL used by /auth/callback. |
| AUTH0_OAUTH_AUDIENCE | required for OAuth bearer API auth | Audience/resource identifier that API-side Auth0 JWT validation accepts. |
| PUBLIC_BASE_URL | required in production | Canonical public origin used for share URLs and other externally visible links. |
| TRUST_PROXY_HEADERS | false | Allows connect flow IP logic to trust forwarded headers. |
| ADMIN_PRINCIPAL_IDS | empty | Comma-separated user principal IDs allowed to call /v1/stats/admin. |
MCP process environment
| Variable | Default | Notes |
|---|---|---|
| ATTACH_API_KEY | required unless ~/.attach/config.json exists | Attach Files API key used by the MCP server. |
| ATTACH_API_URL | http://localhost:2009 | Base API URL if no local CLI config is available. |
| ATTACH_DEFAULT_NAMESPACE | none | Default namespace slug used when tool calls omit namespace. |
| PUBLIC_APP_URL | none | Preferred public base URL for share links. |
| PUBLIC_BASE_URL | falls back to ATTACH_API_URL origin | Secondary share-link base URL when PUBLIC_APP_URL is unset. |
| ATTACH_RUNTIME_KIND | set by the runtime config writer | Identifies the connected runtime, for example claude_code or codex. |
MCP HTTP transport environment
| Variable | Default | Notes |
|---|---|---|
| AGENTFILES_MCP_HOST | 127.0.0.1 | HTTP MCP bind host. |
| AGENTFILES_MCP_PORT | 8787 | HTTP MCP bind port. |
| AGENTFILES_MCP_PATH | /mcp | HTTP MCP request path. |
| AGENTFILES_MCP_OAUTH_ENABLED | auto (on when AUTH0_DOMAIN + AUTH0_OAUTH_AUDIENCE are set) | Enables MCP OAuth metadata and Auth0 proxy endpoints (/authorize, /token, /register). |
| AGENTFILES_MCP_PUBLIC_URL | PUBLIC_BASE_URL, PUBLIC_APP_URL, then ATTACH_API_URL origin | Public HTTPS origin used when publishing OAuth metadata endpoint URLs. |
Manual HTTP launch
For manual or remote MCP clients, start the HTTP transport explicitly. Keep ATTACH_API_KEY for legacy bearer auth and add the OAuth variables when serving ChatGPT connectors.
bash
ATTACH_API_URL=http://localhost:2009 \
ATTACH_API_KEY=arun_agt_... \
AUTH0_DOMAIN=dev-tenant.us.auth0.com \
AUTH0_OAUTH_AUDIENCE=https://mcp.agentfiles.io/mcp \
AGENTFILES_MCP_PUBLIC_URL=https://mcp.agentfiles.io \
AGENTFILES_MCP_PORT=8787 \
npx -y --package agentfiles-mcp@latest agentfiles-mcp-http