Configuration

config.json structure, environment variables, and deployment mode differences.

AgentDesk separates non-secret settings (host, port, paths, timings) from secrets (encryption keys, auth tokens). Non-secret config lives in a JSON file; secrets live in .env.

Deployment Modes

AgentDesk operates in one of two modes, determined by the AGDESK_HOME environment variable:

The CLI never auto-falls-back to ~/.agent-desk. Installed mode activates only when AGDESK_HOME is explicitly set.

Value Resolution Order

Every setting follows the same priority chain:

1. Config file (config.json / agent-desk.json) — user-editable
2. Environment variable — for CI/container overrides
3. Code default — depends on deployment mode

config.json Structure

{
  "server": {
    "host": "0.0.0.0",
    "port": 3737,
    "allowedHosts": ["myhost.example.com", "https://agentdesk.tailnet.ts.net"]
  },
  "paths": {
    "projectsDir": "/data/agentdesk/projects"
  },
  "dispatcher": {
    "tickActiveMs": 15000,
    "tickCoolingMs": 45000,
    "tickIdleMs": 90000,
    "perTurnHardTimeoutMs": 600000,
    "postRunCooldownMs": 60000
  },
  "websocket": {
    "keepAlivePingMs": 30000
  }
}

All keys are optional. Unknown top-level keys emit a warning but never crash the server. Numeric fields are validated at load time — non-finite or non-number values are discarded with a warning.

server

paths

dispatcher

Controls the proactive dispatcher’s adaptive tick loop. See the Dispatcher page for behavioral details.

websocket

platforms

An optional array of platform adapter overrides. Each entry has an id (e.g. "claude-code", "openclaw") and an optional enabled boolean. This key is consumed by the platform adapter layer (src/lib/adapters/index.ts) to control which agent-platform modules are loaded at boot time. Most single-platform installs can omit this entirely.

Environment Variables

Secrets (.env only — never in config.json)

Server / networking

Paths

Platform

Bootstrap (first-boot only)

These variables are written by agdesk setup and consumed on the server’s first boot to seed the initial provider row. After seeding, they are automatically wiped from .env — the encrypted DB row is the source of truth from that point forward.

.env File Loading

AgentDesk uses @next/env (bundled with Next.js) to load .env files so precedence matches what API routes and the app router see at runtime. The load directory is:

1. $AGDESK_HOME if set (installed mode)
2. process.cwd() otherwise (dev mode)

The .env loader runs as the very first import in server.ts via a side-effect module (load-env.ts). This guarantees environment variables are available before any other module evaluates.

Auto-generation of AGDESK_SECRET_KEY

On boot, if AGDESK_SECRET_KEY is missing, blank, or not a valid 64-character hex string, the load-env.ts module generates a fresh 32-byte random key and persists it to .env with file mode 0600. This safety net ensures encryption always uses a strong key, even on installs that predate the key or have a corrupted value.

Example .env

# Shared secret for agent CLI auth (auto-generated by agdesk setup)
AGDESK_INTERNAL_TOKEN=your-generated-token-here

# Encryption key for credentials at rest (auto-generated)
AGDESK_SECRET_KEY=64-hex-characters-here

# Optional: set when behind HTTPS reverse proxy
# AGDESK_COOKIE_SECURE=true

# Optional: override the public URL for reverse-proxy setups
# AGDESK_URL=https://desk.example.com

Editing Configuration

To change non-secret settings, edit the config file directly and restart:

$ vim ~/.agent-desk/config.json
$ agdesk restart

For secrets, edit .env:

$ vim ~/.agent-desk/.env
$ agdesk restart

Changes to config.json and .env require a server restart to take effect. There is no hot-reload for configuration.