> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# YAML Configuration

> Configure Crewship via a YAML config file with server, container, storage, auth, Keeper, and LLM proxy settings.

# 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`.

<Info>
  The config file has ten top-level sections: `server`, `ipc`, `container`, `storage`, `state`, `logging`, `auth`, `llm_proxy`, `keeper`, and `license`. The [Complete Reference](#complete-reference) below shows every field with its default; [Section Details](#section-details) explains the load-bearing ones.
</Info>

## Loading Order

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

## Complete Reference

```yaml theme={null}
# 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

# 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"

# 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

# 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: "claude-haiku-4-5"

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

## Section Details

### Server

```yaml theme={null}
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

```yaml theme={null}
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
```

<Accordion title="Provider options">
  | Provider | Description                                                              |
  | -------- | ------------------------------------------------------------------------ |
  | `docker` | Standard Docker (auto-detects Docker, Podman, Colima, OrbStack, Rancher) |
  | `apple`  | Apple Containers on macOS Tahoe+ (lightweight VMs)                       |
  | `auto`   | Auto-detect between docker and apple                                     |

  Kubernetes provider is on the v0.2 roadmap.
</Accordion>

<Accordion title="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    |
</Accordion>

<Note>
  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.
</Note>

### Storage

```yaml theme={null}
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

```yaml theme={null}
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.

### Auth

```yaml theme={null}
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
```

<Warning>
  Never commit the `jwt_secret` or `internal_token` to version control. Use environment variables for sensitive values.
</Warning>

### LLM Proxy

```yaml theme={null}
llm_proxy:
  enabled: true
  token_sync_interval: 30s
  health_check_interval: 60s
```

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

### Keeper

```yaml theme={null}
keeper:
  enabled: false
  ollama_url: "http://localhost:11434"
  model: "claude-haiku-4-5"
```

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

  ```bash theme={null}
  OLLAMA_MODELS="/Volumes/SSD/ollama-models" ollama serve
  ```

  Then enable Keeper: `KEEPER_OLLAMA_URL=http://localhost:11434 ./dev.sh start`
</Tip>

## 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](/configuration/environment) for the full list.

## Production Configuration

```yaml theme={null}
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"
```