Configuration

AgentCrew is configured through environment variables (set in your .env file) and application settings (managed via the UI). This page documents every available option.

Environment Variables

These variables are defined in the .env file at the root of your AgentCrew installation. They are read when the Docker Compose stack starts.

Variable	Required	Default	Description
`NATS_AUTH_TOKEN`	Yes	None	Authentication token for NATS messaging between the API server and agent containers. Must be a secure, random string.
`API_PORT`	No	`3000`	Port for direct API access (e.g., scripts or automation). The frontend proxies API calls automatically through nginx, so this port is not required for normal usage.
`FRONTEND_PORT`	No	`8080`	Port on which the frontend is served. Change this if port 8080 is already in use.
`SCHEDULE_TIMEOUT`	No	`1h`	Maximum time to wait for a scheduled task response before marking the run as timed out. Accepts Go duration strings (e.g., `30m`, `2h`).
`SCHEDULER_MAX_CONCURRENT`	No	`10`	Maximum number of scheduled tasks that can execute simultaneously. Excess tasks are deferred to the next scheduler tick.
`WEBHOOK_MAX_CONCURRENT`	No	`20`	Global maximum number of webhook executions that can run simultaneously. Excess triggers are queued. Can also be overridden per-webhook.
`AUTH_PROVIDER`	No	`local`	Authentication mode. `local` enables email/password authentication with JWT tokens. `noop` disables authentication entirely (single-user, no login required). See Authentication.
`JWT_SECRET`	Yes*	None	Secret key for signing JWT tokens. Must be at least 32 characters. Required when `AUTH_PROVIDER=local`. Generated automatically by the installer.
`SETTINGS_ENCRYPTION_KEY`	Yes*	None	Key for encrypting sensitive data at rest (API keys, invite tokens) using AES-256-GCM. Required when `AUTH_PROVIDER=local`. Generated automatically by the installer.
`MULTI_TENANT`	No	`false`	When `false`, only one organization can exist. When `true`, multiple organizations can register independently. See Authentication.
`JWT_ACCESS_EXPIRATION`	No	`24h`	Lifetime of JWT access tokens. Accepts Go duration strings (e.g., `1h`, `30m`).
`JWT_REFRESH_EXPIRATION`	No	`7d`	Lifetime of JWT refresh tokens. Accepts Go duration strings (e.g., `7d`, `30d`).

* JWT_SECRET and SETTINGS_ENCRYPTION_KEY are required only when using AUTH_PROVIDER=local. They are not needed with AUTH_PROVIDER=noop.

Example .env file

# Required
NATS_AUTH_TOKEN=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

# Authentication (required for AUTH_PROVIDER=local)
AUTH_PROVIDER=local
JWT_SECRET=your-secure-random-string-at-least-32-characters
SETTINGS_ENCRYPTION_KEY=your-secure-random-encryption-key
MULTI_TENANT=false

# Optional overrides
API_PORT=3000
FRONTEND_PORT=8080

# Optional: JWT token lifetimes
# JWT_ACCESS_EXPIRATION=24h
# JWT_REFRESH_EXPIRATION=7d

# Scheduler settings
SCHEDULE_TIMEOUT=1h
SCHEDULER_MAX_CONCURRENT=10

# Webhook settings
WEBHOOK_MAX_CONCURRENT=20

Application Settings

These settings are configured through the Settings page in the AgentCrew UI (click the gear icon in the sidebar). They are stored in the application database and can be changed at any time without restarting.

Setting	Description
`ANTHROPIC_API_KEY`	Your Anthropic API key from console.anthropic.com. Used by Claude Code teams (required unless you use an OAuth token) and by OpenCode teams when running Anthropic models.
`CLAUDE_CODE_OAUTH_TOKEN`	Alternative authentication method: an OAuth token for Claude Code. Use this if you prefer OAuth over API key authentication. Only one of the two is required.
`OPENAI_API_KEY`	Your OpenAI API key. Required for OpenCode teams using OpenAI models. Also used by Claude Code if configured.
`GOOGLE_GENERATIVE_AI_API_KEY`	Your Google AI API key. Required for OpenCode teams using Google models (Gemini, etc.).

Note: You only need credentials for the provider(s) you use. Claude Code teams require ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN. OpenCode teams require at least one model provider key (ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_GENERATIVE_AI_API_KEY). See Providers for details.

Workspace Path

When creating a team, you can specify a workspace path, a directory on your host machine that will be mounted into the agent container at /workspace. This gives agents read and write access to your project files.

The path must be an absolute path on the host (e.g., /home/user/projects/my-app).
The directory must exist before the team is created.
Agents can read, create, edit, and delete files within the workspace.
If no workspace path is specified, agents work with an empty /workspace directory backed by a Docker volume.

# Host machine                    # Inside agent container
/home/user/projects/my-app  →    /workspace

Persistent Storage

AgentCrew uses a SQLite database to store teams, agents, skills, chat history, and application settings. The database file is persisted in a Docker volume named agentcrew_db.

The volume is created automatically on first run.
Data survives docker compose down and docker compose up cycles.
To fully reset, remove the volume: docker volume rm agentcrew_db.

Tip: Back up your database by copying it from the volume. Use docker cp or mount the volume to a temporary container to access the SQLite file.

Custom Agent Images

AgentCrew lets you use custom Docker images for your agents. This is useful when your agents need extra tools, libraries, or system dependencies beyond what the default images provide.

Important: Your custom image must be based on the official AgentCrew agent images, as they contain the required sidecar binary and CLI tools.

Base Dockerfile for Claude Code Agent

FROM ghcr.io/helmcode/agent_crew_agent:latest

# Add your custom dependencies here
# Example: Install Python packages
RUN pip install pandas numpy

# Example: Install system tools
RUN apt-get update && apt-get install -y --no-install-recommends \
    postgresql-client \
    redis-tools \
    && rm -rf /var/lib/apt/lists/*

# Example: Install user-level tools (use gosu to run as agentcrew)
# RUN gosu agentcrew npx playwright install chromium

Base Dockerfile for OpenCode Agent

FROM ghcr.io/helmcode/agent_crew_opencode_agent:latest

# Add your custom dependencies here
RUN apt-get update && apt-get install -y --no-install-recommends \
    your-tools-here \
    && rm -rf /var/lib/apt/lists/*

Note: You do not need to manage USER directives in your Dockerfile. AgentCrew containers always start as root and the entrypoint script automatically drops privileges to match the workspace owner. Use gosu agentcrew when you need to install user-level tools (e.g., browser binaries) during the build.

How to Build and Use

Build your custom image:

docker build -t myregistry/my-custom-agent:latest .

Then in the AgentCrew UI, set Custom Agent Image to myregistry/my-custom-agent:latest when creating or editing a team.

Warning: Using an image that does not contain the AgentCrew sidecar binary and agent CLI will cause deployment failures.

Next Steps

Authentication: User management, organizations, invites, and role-based access control.
Skills: Extend agent capabilities with installable skills from GitHub.
Architecture: Understand how components interact and where data flows.