Configuration

AgentDock does not currently read one unified YAML, JSON, or TOML configuration file. Runtime configuration is supplied through environment variables, and some common values can also be overridden with CLI flags.

tip

Use the platform installation guides for first setup. This page covers ports, remote access, authentication, browser automation, NexusDock, and advanced deployment settings.

Common configuration

Scenario	What to configure
Local foreground process	Usually keep 127.0.0.1 and the default port
Docker	AGENTDOCK_AUTH_TOKEN in .env; keep the remaining Compose defaults
Browser automation	Enable browser tools and prepare Chrome, Edge, or the browser image
NexusDock (Recall, Workflow, Evolution, Private Notes)	Configure the service URL and optional token
LAN or public access	Authentication, HTTPS, and a reverse proxy; changing only the listen address is not enough

Manage configuration according to the deployment method:

• Local foreground process: shell environment variables or CLI flags.
• Docker Compose: environment or a local .env in the project root.
• systemd: a permission-restricted EnvironmentFile.
• Windows login startup: the current-user configuration and DPAPI-protected data generated by the installer.

Do not commit tokens, passwords, cookies, private keys, or OAuth secrets to a source repository.

Configuration sources and precedence

AgentDock resolves configuration in this order:

1. Built-in defaults.
2. Environment variables.
3. CLI flags.

CLI flags override only the values they explicitly provide. Authentication secrets, OAuth passwords, and NexusDock tokens are available only through environment variables.

The operating-system user that runs AgentDock determines its two primary directories:

~/.agentdock   Internal state, Skills, tasks, MCP configuration, and artifacts
~/AgentDock    Default working directory for file, command, and Git tools

Set AGENTDOCK_HOME or AGENTDOCK_DEFAULT_DIR to absolute paths when you need different locations. For stronger data isolation, use a separate operating-system user or explicit container volumes.

CLI flags

Flag	Environment variable	Default	Description
--host	AGENTDOCK_HOST	127.0.0.1	HTTP listen address
--port	AGENTDOCK_PORT	8765	HTTP listen port, from 1 to 65535
--log-level	AGENTDOCK_LOG_LEVEL	info	debug, info, warn, or error
--nexus-endpoint	AGENTDOCK_NEXUS_ENDPOINT	empty	NexusDock service root URL
--browser-enabled	AGENTDOCK_BROWSER_ENABLED	false	Expose browser automation tools
--browser-executable-path	AGENTDOCK_BROWSER_EXECUTABLE_PATH	empty	Use a specific Chrome, Chromium, or Edge executable
--stdio	AGENTDOCK_STDIO	false	Serve JSON-RPC over standard input and output instead of starting HTTP

Example:

agentdock \
  --host 127.0.0.1 \
  --port 8765 \
  --log-level info

Core runtime configuration

Environment variable	Default	Description
AGENTDOCK_HOME	~/.agentdock	Internal state directory; when set, it must resolve to an absolute directory
AGENTDOCK_DEFAULT_DIR	~/AgentDock	Default working directory for relative file, command, and Git operations; when set, it must resolve to an absolute directory
AGENTDOCK_HOST	127.0.0.1	HTTP listen address. A non-loopback address requires Bearer Token or OAuth authentication
AGENTDOCK_PORT	8765	HTTP listen port
AGENTDOCK_LOG_LEVEL	info	Log level
AGENTDOCK_STDIO	false	Whether to use stdio mode
AGENTDOCK_BROWSER_ENABLED	false	Whether to expose browser_* tools
AGENTDOCK_BROWSER_EXECUTABLE_PATH	empty	Optional absolute Chrome, Chromium, or Edge executable path
AGENTDOCK_NEXUS_ENDPOINT	empty	NexusDock service root URL; enables Recall, Workflow, Evolution, and Private Notes capabilities
AGENTDOCK_NEXUS_TOKEN	empty	NexusDock Bearer Token
AGENTDOCK_INSTRUCTIONS_FILE	empty	Optional UTF-8 text file sent to compatible MCP clients as server instructions during initialization

Use only true or false for boolean values to avoid differences between service managers.

Bearer Token authentication

The simplest HTTP authentication method is:

export AGENTDOCK_AUTH_TOKEN="$(openssl rand -hex 32)"

The client sends this header when it accesses /mcp:

Authorization: Bearer <token>

Authentication may be omitted only when AgentDock listens exclusively on a loopback address. When it listens on 0.0.0.0, a LAN address, or a public address, it refuses to start without authentication.

Docker Compose example:

services:
  agentdock:
    environment:
      AGENTDOCK_AUTH_TOKEN: "${AGENTDOCK_AUTH_TOKEN:?set AGENTDOCK_AUTH_TOKEN}"

OAuth configuration

OAuth is suitable for remote MCP clients such as ChatGPT that require browser authorization. AgentDock supports Authorization Code, PKCE S256, dynamic client registration, and Refresh Tokens. Compatible clients can register automatically from server metadata; administrators do not need to create a Client ID or Client Secret in advance.

All of these variables are required when OAuth is enabled:

Environment variable	Requirement	Description
AGENTDOCK_OAUTH_ENABLED	true	Enable OAuth
AGENTDOCK_SERVER_URL	required	Public AgentDock origin, for example https://agentdock.example.com
AGENTDOCK_OAUTH_PASSWORD	at least 12 characters	Connection password entered on the authorization page
AGENTDOCK_OAUTH_TOKEN_SECRET	at least 32 bytes	Signing key for OAuth state and tokens; store it persistently instead of regenerating it on each restart

Optional: AGENTDOCK_OAUTH_ACCESS_TOKEN_TTL controls Access Token lifetime. The default is 1h; Go duration values such as 12h, integer day values such as 90d, and never are supported.

Example:

AGENTDOCK_OAUTH_ENABLED=true
AGENTDOCK_SERVER_URL=https://agentdock.example.com
AGENTDOCK_OAUTH_PASSWORD=<long-login-password>
AGENTDOCK_OAUTH_TOKEN_SECRET=<random-secret-at-least-32-bytes>

Generate random values with OpenSSL:

openssl rand -base64 24
openssl rand -hex 32

AGENTDOCK_SERVER_URL must be a complete origin without a path, query, or fragment. A non-loopback address must use HTTPS; only localhost or a loopback IP may use HTTP. The MCP URL entered in a client adds /mcp, for example https://agentdock.example.com/mcp.

Enabling OAuth exposes these endpoints:

Path	Purpose
/.well-known/oauth-authorization-server	OAuth Authorization Server metadata
/.well-known/oauth-protected-resource/mcp	MCP Protected Resource metadata
/register	Dynamic client registration
/oauth/authorize	Browser authorization page
/oauth/token	Exchange Authorization Codes and Refresh Tokens

Bearer Token and OAuth may be enabled together. When only one method is required, do not keep unused secrets. See Connect ChatGPT to AgentDock for the complete ChatGPT flow.

Trusted reverse proxies

AgentDock does not trust a client-provided X-Forwarded-For header by default. Configure trusted proxies only when the reverse proxy is in a controlled network and rewrites the forwarding chain correctly:

AGENTDOCK_TRUSTED_PROXY_CIDRS=127.0.0.0/8,::1/128

Separate multiple networks with commas. Do not add uncontrolled public networks, or authentication rate limiting and client-address checks may be spoofed.

NexusDock Recall, Workflows, Evolution, and Private Notes

After NexusDock is configured, AgentDock exposes recall_*, workflow_template_manage, evolve, and private_note_manage. Recall and Workflows use NexusDock shared services, AgentDock owns the Evolution lifecycle policy, and Private Notes use NexusDock Private Notes:

AGENTDOCK_NEXUS_ENDPOINT=https://nexus.example.com
AGENTDOCK_NEXUS_TOKEN=<nexus-token>

AGENTDOCK_NEXUS_ENDPOINT is the NexusDock service root URL; do not append a specific API path. When it is not configured:

• Local task_manage still manages ordinary recoverable tasks.
• evolve, recall_*, workflow_template_manage, and private_note_manage do not appear in tools/list.

For multi-device routing, fleet context, and node Artifact downloads, see NexusDock.

Coding Agents (ACP)

ACP is disabled by default. Desktop users should normally enable it from AgentDock Advanced Settings; see Use local Coding Agents.

Headless deployments can use these host settings:

Environment variable	Default	Description
AGENTDOCK_ACP_ENABLED	false	Expose the built-in ACP tools
AGENTDOCK_ACP_AGENT	claude	Short profile name reported for the configured Coding Agent
AGENTDOCK_ACP_COMMAND	empty	Required absolute executable path when ACP is enabled
AGENTDOCK_ACP_ARGS_JSON	empty	Optional JSON string array of adapter arguments
AGENTDOCK_ACP_ENV_FROM_ENV_JSON	empty	Optional JSON object mapping child variable names to existing host variable names
AGENTDOCK_ACP_MAX_CONCURRENT_PROMPTS	2	Maximum concurrent prompt runs, from 1 to 8
AGENTDOCK_ACP_INTERACTION_TIMEOUT_MS	300000	Permission-interaction timeout in milliseconds, from 1000 to 3600000

Example environment mapping:

AGENTDOCK_ACP_ENV_FROM_ENV_JSON='{"OPENAI_API_KEY":"OPENAI_API_KEY"}'

Only the variable names are stored in the mapping; the child process receives the current host value when AgentDock starts. Keep secrets in the host environment and avoid embedding them directly in AGENTDOCK_ACP_ARGS_JSON.

AgentDock does not maintain an ACP project-root whitelist. Session workspaces may use any host-accessible directory, so use operating-system permissions or container mounts when a Coding Agent needs a stricter boundary.

Static MCP server instructions

Set AGENTDOCK_INSTRUCTIONS_FILE when you want compatible MCP clients to receive a short, static instruction block during MCP initialization:

AGENTDOCK_INSTRUCTIONS_FILE=/absolute/path/to/agentdock-instructions.md

The file must be a non-empty regular UTF-8 file, no larger than 64 KiB, and its path must be absolute. AgentDock reads it at startup and returns the text as MCP server instructions.

This is bootstrap guidance for the client, not dynamic Recall memory and not a replacement for agentdock_context. Whether a client incorporates MCP server instructions into its own prompt or UI is controlled by that client.

Browser tools

Browser automation is disabled by default. Enable it with:

AGENTDOCK_BROWSER_ENABLED=true

or:

agentdock --browser-enabled

AgentDock supports Chrome, Chromium, and Microsoft Edge. If automatic browser discovery is not suitable, configure the browser executable explicitly.

Environment variable	Default	Description
AGENTDOCK_BROWSER_ENABLED	false	Expose browser_session, browser_act, and browser_snapshot
AGENTDOCK_BROWSER_EXECUTABLE_PATH	empty	Optional absolute browser executable path when automatic discovery is not suitable

The macOS and Windows apps detect installed supported browsers before enabling the feature. The Docker browser image includes Chromium and configures its executable path automatically. See Browser automation for usage details.

Isolated environments for Skills and dynamic MCP

Do not keep business secrets for Skills and dynamic MCP servers in the main AgentDock process environment longer than necessary. Prefer each integration's isolated environment:

{
  "action": "env_set",
  "skill": "example-skill",
  "key": "EXAMPLE_API_KEY",
  "value": "..."
}

{
  "action": "env_set",
  "name": "example-mcp",
  "key": "SERVICE_TOKEN",
  "value": "..."
}

Use skill_package and mcp_manage, respectively. env_list returns only variable names and whether they are configured; it never returns actual values.

Private Notes

Starting with v0.4.4, private_note_manage uses the NexusDock Private Notes API. It no longer reads a local AgentDock private-note directory or AGENTDOCK_PRIVATE_NOTES_* environment variables. Configure AGENTDOCK_NEXUS_ENDPOINT and the optional token first.

NexusDock manages plaintext boundaries, age X25519 encrypted backups, and Git ignore rules. Initialize or inspect encryption through a maintenance action:

{
  "action": "maintain",
  "maintenance_action": "init-encryption"
}

Search matches only safe metadata such as title, summary, tags, category, and path. It does not search or return the body. Only an explicit read returns plaintext; both write and delete require confirmed=true.

Inspect current state

Call agentdock_context to inspect the runtime and capability bootstrap for the current connection. A direct AgentDock response includes:

• AgentDock version, operating system, and architecture.
• AgentDock home, default directory, current default working directory, and path model.
• Installed Skill summaries and enabled dynamic MCP servers.
• Optional ACP state plus Nexus-backed Workflow and Recall indexes when configured.

agentdock_context does not duplicate the built-in MCP tool catalog or report the active authentication method. Use the MCP client's tools/list for the tools actually exposed by that connection, and inspect the deployment configuration or desktop control panel for authentication settings.

Neither agentdock_context nor tools/list returns authentication tokens, OAuth passwords, signing keys, or NexusDock tokens.

Startup validation

AgentDock refuses to start when configuration is invalid. Common checks include:

• The port is between 1 and 65535.
• The log level is valid.
• Authentication is enabled for a non-loopback listener.
• All OAuth variables are present and satisfy length requirements.
• A public AGENTDOCK_SERVER_URL uses HTTPS.
• Every entry in AGENTDOCK_TRUSTED_PROXY_CIDRS is a valid CIDR.

After deployment, verify at least:

curl -fsS http://127.0.0.1:8765/healthz

Then complete one real MCP initialize and tool call from the actual client. See the Security model for deployment boundaries and recommendations.