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

Most users should not start on this page. Follow the Docker, Linux, Windows, or macOS installation guide, then use the MCP URL and token shown there. Return here only for port conflicts, remote access, browser automation, NexusDock, or advanced deployment requirements.

Configuration most users need

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, 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

The current CLI does not expose public flags for changing these directories. Use a separate operating-system user, container volumes, or a separate home directory when data isolation is required.

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
--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_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_RUNNER_DIR	~/.agentdock/browser-runner	Browser runner directory; the Docker browser image points this to a read-only directory inside the image
AGENTDOCK_NEXUS_ENDPOINT	empty	NexusDock service root URL; enables Recall, Workflow, and Private Notes capabilities
AGENTDOCK_NEXUS_TOKEN	empty	NexusDock Bearer Token

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

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, and Private Notes

After NexusDock is configured, AgentDock exposes recall_*, workflow_template_manage, and private_note_manage. Recall and Workflows use the NexusDock Registry; 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.
• recall_*, workflow_template_manage, and private_note_manage do not appear in tools/list.

Browser tools

Browser automation is disabled by default. Enable it with:

AGENTDOCK_BROWSER_ENABLED=true

or:

agentdock --browser-enabled

The switch only exposes browser_session, browser_act, and browser_snapshot. The runtime still needs the browser runner together with Node.js and playwright-core.

Environment variable	Default	Description
AGENTDOCK_BROWSER_RUNNER_DIR	~/.agentdock/browser-runner	Directory containing browser-runner.js and Node dependencies
AGENTDOCK_BROWSER_EXECUTABLE_PATH	empty	Chromium executable used by the runner; the Docker browser image sets this to /usr/bin/chromium

The Docker browser image configures the runner and Chromium automatically. Native macOS, Windows, and Linux releases do not currently install the runner; prepare Node.js, the runner, and playwright-core separately before enabling the tools. See Browser automation for the available choices.

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 server_info to inspect public runtime state for the current instance, including:

• AgentDock version, operating system, and architecture.
• Default directories and path model.
• Whether authentication, browser tools, and NexusDock Recall are enabled.
• The tools actually exposed by the current instance.
• Trusted proxy networks and command-session limits.

server_info does not return 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.