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 thirteen top-level sections: server, ipc, container, storage, state, logging, auth, llm_proxy, keeper, license, composio, local_models, and orchestrator. 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
  quota_helper_socket: ""       # Root quota helper socket; empty = quota services
                                # with volumes cannot start. Env override:
                                # CREWSHIP_QUOTA_HELPER_SOCKET
  quota_helper_namespace: ""    # Immutable database identity in the helper; set
                                # together with the socket. Env override:
                                # CREWSHIP_QUOTA_HELPER_NAMESPACE
  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
  sidecar_binary_path: ""       # Host path to crewship-sidecar, bind-mounted into
                                # every crew container. Empty = autodetect next to
                                # the crewship binary, then /usr/local/bin.
                                # Env override: CREWSHIP_SIDECAR_PATH
  entrypoint_path: ""           # Host path to entrypoint.sh, bind-mounted the same
                                # way; when set, the container entrypoint is forced
                                # to /usr/local/bin/entrypoint.sh. Empty = autodetect.
                                # Env override: CREWSHIP_ENTRYPOINT_PATH
  egress_fence_crews: []        # Pilot: crews (slug or id) that get the network-layer
                                # egress fence. Restricted, non-privileged crews on
                                # runc only; a listed crew that cannot be fenced
                                # does not start. Empty = off.
                                # Env override: CREWSHIP_EGRESS_FENCE_CREWS (comma list)
  crew_network_crews: []        # Crews (slug or id) that get their own Docker network
                                # instead of the shared one: other crews cannot reach
                                # them and their service aliases are their own. Takes
                                # effect when the crew's container is next recreated;
                                # its existing services then move with it, live (same
                                # container and data; open connections to them drop).
                                # Needs crewshipd on the Docker host with a local
                                # daemon; elsewhere a listed crew does not start.
                                # Empty = off. Env override: CREWSHIP_CREW_NETWORK_CREWS
  crew_network_pool: "10.231.0.0/16"  # IPv4 range (/16 to /27) crew networks take /27
                                # subnets from; must not overlap a host route (LAN,
                                # VPN). Crewship checks host routes only when it can
                                # prove it sees the daemon host's (its bridges show up
                                # as routes); on Docker Desktop you must set this to
                                # a range you know is free on that host.
                                # Env override: CREWSHIP_CREW_NETWORK_POOL
  idle_runtime_retention_days: 0  # Remove stopped runtimes of live crews after this
                                # many days stopped; volumes stay. 0 = off.
                                # Env override: CREWSHIP_IDLE_RUNTIME_RETENTION_DAYS
  cache_eviction: false         # Evict crewship-cache images no container on the
                                # daemon has used for an hour; live crew selections
                                # in this installation stay. Env override:
                                # CREWSHIP_CACHE_EVICTION

# 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"
  memory_root: ""               # Parent directory of the workspace memory tier
                                # (<memory_root>/{workspace_id}). Empty disables the
                                # tier and memory versioning. `crewship start` derives
                                # <dataDir>/memory only when DATABASE_URL is unset.
                                # Env override: CREWSHIP_STORAGE_MEMORY_ROOT
  # Custom Page applications (all five map 1:1 to the CREWSHIP_PAGE_* env vars)
  page_projects_path: ""        # Protected host directory for Page sources, Git and
                                # artifacts; must not overlap base_path. Empty
                                # disables custom Page projects.
  page_build_image: ""          # Immutable image ID or repository@sha256:… digest of
                                # the offline Page compiler. Tags are refused; empty
                                # disables builds. Requires page_projects_path.
  page_studio_origin: ""        # Public browser origin allowed to initialize Page
                                # applications. Empty = auth.nextjs_url.
  page_runtime_origin: ""       # Separate-site public origin that serves published
                                # Page applications (bootstrap route only). Required
                                # to preview, publish or serve custom applications.
  page_runtime_development_same_origin: false
                                # Reviewed development demos only: lets the runtime
                                # share the Studio origin. No process isolation.

# 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

# Agent-run orchestrator admission control
orchestrator:
  max_concurrent_runs: 8        # Server-wide cap on agent runs executing at once;
                                # excess runs queue. Must be > 0. Sized once at
                                # startup, so a change needs a restart.
                                # Env override: CREWSHIP_MAX_CONCURRENT_RUNS

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. memory_root is the parent of the per-workspace memory tier; leave it empty and that tier (and memory versioning) is off. run_output_path selects a host-private directory for protected execution output on supported local Linux Docker runtimes. Startup derives <data-root>/run-output when unset; explicit YAML run_output_path: "" disables capture. CREWSHIP_RUN_OUTPUT_PATH overrides the path. Never mount it into a crew. run_output_max_bytes and run_output_max_runs bound aggregate retained captures; zero selects the defaults of 1 GiB and 4096 runs. Each active run reserves 64 MiB plus 64 KiB of metadata; verified terminal captures release unused reserved bytes. Fully acknowledged natural terminal sources are collected after seven days. Incomplete or forced output remains available for reconciliation. The five page_* keys configure custom Page applications. They are the file-config form of CREWSHIP_PAGE_PROJECTS_PATH, CREWSHIP_PAGE_BUILD_IMAGE, CREWSHIP_PAGE_STUDIO_ORIGIN, CREWSHIP_PAGE_RUNTIME_ORIGIN and CREWSHIP_PAGE_RUNTIME_DEVELOPMENT_SAME_ORIGIN, and the env var wins when both are set. Validation is the same on both paths: page_projects_path must be absolute and must not sit inside (or contain) base_path; page_build_image needs page_projects_path and an immutable sha256:… ID or repository@sha256:… digest; page_runtime_origin must be a different site from the Studio origin unless page_runtime_development_same_origin is true. See the Environment Reference for what each one guards.

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.

Orchestrator

orchestrator:
  max_concurrent_runs: 8

max_concurrent_runs bounds how many agent runs the orchestrator executes at once; the rest wait in its queue. It must be greater than zero (validation refuses 0 or a negative value), and CREWSHIP_MAX_CONCURRENT_RUNS overrides it. The cap is read once when the orchestrator is built, so changing either takes effect on the next restart.

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

Orchestrator

Keeper

Minimal Configuration

Production Configuration

​YAML Configuration

​Loading Order

​Complete Reference

​Section Details

​Server

​Container

​Storage

​State

​Auth

​LLM Proxy

​Orchestrator

​Keeper

​Minimal Configuration

​Production Configuration

YAML Configuration

Loading Order

Complete Reference

Section Details

Server

Container

Storage

State

Auth

LLM Proxy

Orchestrator

Keeper

Minimal Configuration

Production Configuration