YAML Configuration

Crewship can be configured via a YAML file passed at startup. Environment variables override YAML values. The config is loaded and validated in internal/config/config.go.

The config file has twelve top-level sections: server, ipc, container, storage, state, logging, auth, llm_proxy, keeper, license, composio, and local_models. The Complete Reference below shows every field with its default; Section Details explains the load-bearing ones.

Loading Order

Default values (config.Default())
YAML config file (if path provided)
Environment variable overrides (applyEnvOverrides)
Auto-derived values (NextjsURL, InternalToken)
Validation (Config.Validate)

Complete Reference

# Server configuration
server:
  host: "0.0.0.0"              # Listen address
  port: 8080                    # Listen port
  shutdown_timeout: 10s         # Graceful shutdown timeout

# Inter-process communication
ipc:
  socket_path: "/tmp/crewship.sock"  # Unix socket for internal API. The default
                                     # follows the resolved data dir —
                                     # CREWSHIP_DATA_DIR when set, else
                                     # $HOME/.crewship — so <dataDir>/crewship.sock
                                     # is the normal case and this /tmp literal is
                                     # the default only for the packaged
                                     # /var/lib/crewship install.

# Container provider
container:
  provider: "docker"            # "docker" | "apple" | "auto"
  runtime_image: "debian:bookworm-slim"
  default_runtime: "runc"       # "runc" | "runsc" | "kata-runtime" | "sysbox-runc"
  network: "crewship-agents"    # Docker bridge network name
  container_prefix: ""          # Name prefix for multi-instance isolation
  default_memory_mb: 8192       # Default container memory limit
  default_cpus: 2.0             # Default container CPU limit
  sidecar_enabled: false        # Enable sidecar proxy for credential injection

# Note: Crewship injects the sidecar binary and entrypoint script into the
# container at runtime via bind mount from the host. Any glibc-based Linux
# image (debian, ubuntu, or a derivative) works out of the box — no custom
# base image is required.

# File storage
storage:
  provider: "localfs"           # "localfs" | "s3"
  base_path: "/var/lib/crewship"
  log_path: "/var/log/crewship"

# State store (agent run states)
state:
  provider: "bbolt"             # "bbolt" (postgres on the v0.2 roadmap)
  bolt_path: "/var/lib/crewship/state.db"   # <dataDir>/state.db when
                                            # CREWSHIP_DATA_DIR is set to
                                            # something other than
                                            # /var/lib/crewship

# Logging
logging:
  level: "info"                 # "debug" | "info" | "warn" | "error"
  format: "json"                # "json" | "text"

# Authentication
auth:
  jwt_secret: ""                # NEXTAUTH_SECRET (required)
  ws_token_expiry: 5m           # WebSocket token expiry
  nextjs_url: ""                # Auto-derived from port if unset
  internal_token: ""            # Auto-generated if empty
  allow_signup: false           # Allow new user registration
  google_client_id: ""          # Google OAuth (both must be set to mount /auth/google/*)
  google_client_secret: ""
  bootstrap_window: 0s          # First-run /bootstrap window; 0 = open until first admin exists

# LLM proxy (token management)
llm_proxy:
  enabled: true
  token_sync_interval: 30s      # How often to sync token usage
  health_check_interval: 60s    # LLM provider health checks

# Keeper (AI security gatekeeper)
keeper:
  enabled: false
  ollama_url: "http://localhost:11434"
  model: ""                     # No default — REQUIRED (non-empty) when enabled: true,
                                # else startup validation fails. e.g. "claude-haiku-4-5"

# License
license:
  file_path: ""                 # Path to license file

# Composio managed integrations
composio:
  enabled: false                # Derived: setting api_key auto-enables it
  api_key: ""                   # Composio project API key ("ak_…")
  base_url: ""                  # Optional Composio API host override
  default_connector: false      # Give every agent a workspace-wide default connector

# Local models (OpenAI-compatible server for agent CLIs)
local_models:
  base_url: ""                  # e.g. "http://host.docker.internal:11434/v1".
                                # Handed to agent CLIs INSIDE crew containers, so it
                                # must resolve from the container's perspective.
                                # Distinct from keeper.ollama_url (daemon-internal).
                                # Empty = local-model path disabled.
                                # Env override: CREWSHIP_LOCAL_MODEL_BASE_URL

Section Details

Server

server:
  host: "0.0.0.0"
  port: 8080
  shutdown_timeout: 10s

The shutdown_timeout controls how long the server waits for in-flight requests to complete during graceful shutdown. The server port must be between 1 and 65535.

Container

container:
  provider: "docker"
  runtime_image: "debian:bookworm-slim"
  default_runtime: "runc"
  network: "crewship-agents"
  container_prefix: ""
  default_memory_mb: 8192
  default_cpus: 2.0
  sidecar_enabled: false

Provider options

Provider	Description
`docker`	Standard Docker (auto-detects Docker, Podman, Colima, OrbStack, Rancher)
`apple`	Apple Containers on macOS Tahoe+ (lightweight VMs); applies none of the crew isolation controls and does not enforce `restricted` egress
`auto`	Tries Docker first, falls back to Apple Containers — the hardened provider wins on a host with both

Kubernetes provider is on the v0.2 roadmap.

Runtime options

Runtime	Security	Performance
`runc`	Standard Linux namespaces	Fast
`runsc` (gVisor)	Kernel-level syscall interception	Moderate
`kata-runtime`	Lightweight VM isolation	Slower
`sysbox-runc`	Enhanced container isolation	Moderate

The container_prefix is prepended to container names. For example, with container_prefix: "prod", a container would be named prod-team-engineering instead of crewship-team-engineering. Essential for multi-instance deployments.

Storage

storage:
  provider: "localfs"
  base_path: "/var/lib/crewship"
  log_path: "/var/log/crewship"

The base_path stores crew workspace files, agent output, and persistent data. The log_path stores agent execution logs.

State

state:
  provider: "bbolt"
  bolt_path: "/var/lib/crewship/state.db"

BoltDB is the default state store for agent run tracking. A PostgreSQL state provider for high-throughput deployments is on the v0.2 roadmap. The /var/lib/crewship/state.db default holds for a packaged install (the deb/rpm unit pins CREWSHIP_DATA_DIR=/var/lib/crewship). Point CREWSHIP_DATA_DIR anywhere else and the default becomes <dataDir>/state.db — the bbolt file is exclusively locked by one process, so instances that share a data root cannot share it. The IPC socket_path default follows the same rule.

Auth

auth:
  jwt_secret: ""           # Set via NEXTAUTH_SECRET env var
  ws_token_expiry: 5m
  nextjs_url: ""           # Auto-derived: http://localhost:{port}
  internal_token: ""       # Auto-generated if empty
  allow_signup: false

Never commit the jwt_secret or internal_token to version control. Use environment variables for sensitive values.

LLM Proxy

llm_proxy:
  enabled: true
  token_sync_interval: 30s
  health_check_interval: 60s

The LLM proxy manages token usage tracking and provider health monitoring.

Keeper

keeper:
  enabled: false
  ollama_url: "http://localhost:11434"
  model: ""   # no built-in default; set a model (e.g. "claude-haiku-4-5") before enabling

For development, start Ollama with models on an external SSD:

OLLAMA_MODELS="/Volumes/SSD/ollama-models" ollama serve

Then enable Keeper: KEEPER_OLLAMA_URL=http://localhost:11434 ./dev.sh start

Minimal Configuration

As of PR #446, no env vars are required for first boot. Run crewship start against an empty data directory and the server will:

Listen on 0.0.0.0:8080
Use Docker as container provider
Store data in ~/.crewship (or $CREWSHIP_DATA_DIR)
Use BoltDB for state
Auto-generate ENCRYPTION_KEY, NEXTAUTH_SECRET, and CREWSHIP_INTERNAL_TOKEN with crypto/rand, persisting them to <dataDir>/secrets.env at mode 0600
Auto-derive the NextJS URL from the listen port

Set env vars only when you need to override a default (different port, external secret manager, custom data dir, etc.). See Environment Reference for the full list.

Production Configuration

server:
  host: "0.0.0.0"
  port: 8080
  shutdown_timeout: 30s

container:
  provider: "docker"
  runtime_image: "debian:bookworm-slim"
  default_runtime: "runsc"      # gVisor for production security
  network: "crewship-agents"
  default_memory_mb: 1024
  default_cpus: 2.0
  sidecar_enabled: true

storage:
  provider: "localfs"
  base_path: "/data/crewship"
  log_path: "/var/log/crewship"

state:
  provider: "bbolt"
  bolt_path: "/var/lib/crewship/state.db"

logging:
  level: "info"
  format: "json"

auth:
  allow_signup: false

keeper:
  enabled: true
  ollama_url: "http://ollama-host:11434"
  model: "claude-haiku-4-5"

Get Started

Guides

Security

Configuration

Manifest Reference

YAML Configuration

YAML Configuration

Loading Order

Complete Reference

Section Details

Server

Container

Storage

State

Auth

LLM Proxy

Keeper

Minimal Configuration

Production Configuration

​YAML Configuration

​Loading Order

​Complete Reference

​Section Details

​Server

​Container

​Storage

​State

​Auth

​LLM Proxy

​Keeper

​Minimal Configuration

​Production Configuration

YAML Configuration

Loading Order

Complete Reference

Section Details

Server

Container

Storage

State

Auth

LLM Proxy

Keeper

Minimal Configuration

Production Configuration