Configuration

Config File Location

All configuration lives in a single JSON file:

~/.openacp/config.json

The path can be overridden with the OPENACP_CONFIG_PATH environment variable. The file is created automatically on first run with safe defaults.

Interactive Editor

To edit config interactively while OpenACP is running:

openacp config

This opens a menu-driven editor with sections for Channels, Agent, Workspace, Security, Logging, Run Mode, API, and Tunnel. Changes are saved on exit. When the daemon is running, changes are applied immediately via the local API without requiring a restart (where supported).

Reconfigure Wizard

For a guided reconfiguration of core sections, use:

openacp onboard

This runs runReconfigure(), which loads your existing config, shows a summary, and lets you step through sections selectively. Sections available:

• Channels — Add, modify, disable, or delete channel configurations. For each configured channel you can choose to modify settings, disable the bot without losing credentials, or permanently delete the channel config.

• Agents — Select which installed agent to use as the default.

• Workspace — Change the base directory where agent working directories are created.

• Run Mode — Switch between foreground and daemon mode, and toggle autostart on boot.

• Integrations — Configure optional integrations (e.g., Claude CLI).

For the machine-readable schema with all field types and defaults, see the Configuration Schema. For a full list of environment variable overrides, see Environment Variables.

Full Configuration Reference

channels

Channel adapters. Each key is a channel identifier. The built-in channels are telegram and discord.

Telegram:

"telegram": {
  "enabled": true,
  "botToken": "1234567890:ABC...",
  "chatId": -1001234567890,
  "displayVerbosity": "medium"
}

Field	Type	Default	Description
enabled	boolean	false	Whether this channel is active
botToken	string	—	Telegram Bot API token
chatId	number	—	Forum group chat ID
displayVerbosity	low | medium | high	medium	Detail level for agent output messages

Discord:

"discord": {
  "enabled": true,
  "botToken": "MTI...",
  "guildId": "123456789012345678",
  "forumChannelId": null,
  "notificationChannelId": null
}

agents

Named map of ACP-compatible agent binaries. Each entry describes how to spawn the agent subprocess.

"agents": {
  "claude": {
    "command": "claude-agent-acp",
    "args": [],
    "env": {},
    "workingDirectory": "~/projects"
  }
}

Field	Type	Default	Description
command	string	—	Executable name or path
args	string[]	[]	Additional CLI arguments
env	object	{}	Extra environment variables for the subprocess
workingDirectory	string	—	Override working directory (otherwise uses workspace)

defaultAgent

"defaultAgent": "claude"

The agent key used when a new session is created. Must exist in agents.

workspace

"workspace": {
  "baseDir": "~/openacp-workspace"
}

Base directory for agent working directories. Named workspaces are subdirectories under this path. The ~ prefix is expanded to the home directory.

security

"security": {
  "allowedUserIds": [],
  "maxConcurrentSessions": 20,
  "sessionTimeoutMinutes": 60
}

Field	Type	Default	Description
allowedUserIds	string[]	[]	Allowlist of platform user IDs. Empty = all users allowed.
maxConcurrentSessions	number	20	Hard cap on active + initializing sessions across all channels.
sessionTimeoutMinutes	number	60	Idle session timeout in minutes.

See Security for details.

logging

"logging": {
  "level": "info",
  "logDir": "~/.openacp/logs",
  "maxFileSize": "10m",
  "maxFiles": 7,
  "sessionLogRetentionDays": 30
}

See Logging for details.

runMode

"runMode": "foreground"

"foreground" or "daemon". Controls whether openacp start runs in the terminal or spawns a detached background process.

autoStart

"autoStart": false

If true, OpenACP installs a platform autostart entry (macOS LaunchAgent or Linux systemd user service) so the daemon starts on login. Managed automatically by the run mode setup in the config editor and onboard wizard.

api

"api": {
  "port": 21420,
  "host": "127.0.0.1"
}

The local REST API used by the CLI and web UI. host defaults to 127.0.0.1 (loopback only). Do not bind to 0.0.0.0 unless you have network-level access controls in place.

tunnel

"tunnel": {
  "enabled": true,
  "port": 3100,
  "provider": "cloudflare",
  "options": {},
  "maxUserTunnels": 5,
  "storeTtlMinutes": 60,
  "auth": { "enabled": false }
}

Field	Type	Default	Description
enabled	boolean	false	Enable tunnel
port	number	3100	Local port the tunnel exposes
provider	string	"cloudflare"	cloudflare, ngrok, bore, or tailscale
options	object	{}	Provider-specific options (domain, authtoken, etc.)
auth.enabled	boolean	false	Require bearer token on tunnel requests

usage

"usage": {
  "enabled": true,
  "monthlyBudget": 50,
  "warningThreshold": 0.8,
  "currency": "USD",
  "retentionDays": 90
}

Usage tracking. When monthlyBudget is set and usage reaches warningThreshold (80% by default), a notification is sent. Set enabled: false to disable tracking entirely.

speech

"speech": {
  "stt": {
    "provider": null,
    "providers": {
      "groq": { "apiKey": "gsk_..." }
    }
  },
  "tts": {
    "provider": null,
    "providers": {}
  }
}

Speech-to-text and text-to-speech configuration. Set provider to the key of a configured entry in providers to enable. null disables speech for that direction.

sessionStore

"sessionStore": {
  "ttlDays": 30
}

How long completed session records are retained before cleanup.

integrations

Managed automatically. Records which optional integrations are installed.

Environment Variable Overrides

The following environment variables override their corresponding config fields at startup. They do not modify the config file on disk.

Variable	Config path
OPENACP_CONFIG_PATH	(config file path itself)
OPENACP_TELEGRAM_BOT_TOKEN	channels.telegram.botToken
OPENACP_TELEGRAM_CHAT_ID	channels.telegram.chatId
OPENACP_DISCORD_BOT_TOKEN	channels.discord.botToken
OPENACP_DISCORD_GUILD_ID	channels.discord.guildId
OPENACP_SLACK_BOT_TOKEN	channels.slack.botToken
OPENACP_SLACK_APP_TOKEN	channels.slack.appToken
OPENACP_SLACK_SIGNING_SECRET	channels.slack.signingSecret
OPENACP_DEFAULT_AGENT	defaultAgent
OPENACP_RUN_MODE	runMode
OPENACP_API_PORT	api.port
OPENACP_LOG_LEVEL	logging.level
OPENACP_LOG_DIR	logging.logDir
OPENACP_DEBUG	Sets logging.level to debug (when OPENACP_LOG_LEVEL is not set)
OPENACP_TUNNEL_ENABLED	tunnel.enabled
OPENACP_TUNNEL_PORT	tunnel.port
OPENACP_TUNNEL_PROVIDER	tunnel.provider
OPENACP_SPEECH_STT_PROVIDER	speech.stt.provider
OPENACP_SPEECH_GROQ_API_KEY	speech.stt.providers.groq.apiKey

Environment variables are applied after the config file is read and before Zod validation. They take precedence over file values.

Hot-Reload

When openacp config communicates changes via the local API (daemon mode), supported fields are applied to the running process immediately. Fields that require a full restart (e.g., channel credentials, API port) emit a needsRestart signal in the response.

Backward Compatibility

Every new config field uses .default() or .optional() in the Zod schema. This means an older config.json will always pass validation after an upgrade — missing fields are filled with their defaults. Fields are never renamed or removed without a migration.

Automatic migrations run at startup before validation. Current migrations:

• add-tunnel-section — Adds the tunnel block if absent (pre-0.3 configs).

• fix-agent-commands — Renames legacy agent command names to their current equivalents.

• migrate-agents-to-store — Moves agent definitions from config.json into the separate ~/.openacp/agents.json store.

Migrations mutate the raw JSON in place and write it back to disk if any change was made. No action is required from you.