Environment variables

All Claworc configuration is done via environment variables with the CLAWORC_ prefix.

Core settings

Variable	Default	Description
CLAWORC_DATA_PATH	/app/data	Directory to store the Claworc’s data like SQLite database, SSH key pair, and etc. Mount a persistent volume here.
CLAWORC_DATABASE	(empty)	Database connection URL. Leave empty to use SQLite under CLAWORC_DATA_PATH. Set to a postgres://, mysql://, or mariadb:// URL to use an external database. See Database.
CLAWORC_BACKUPS_PATH	(empty)	Directory for backup archives. When empty, backups are written under <CLAWORC_DATA_PATH>/backups. Set this to place backups on a separate (for example, cheaper or slower) volume. The directory must exist and be writable.
CLAWORC_K8S_NAMESPACE	claworc	Kubernetes namespace where agent instances are created. Must exist before starting.
CLAWORC_DOCKER_HOST	(empty)	Docker socket or TCP address. Example: unix:///var/run/docker.sock. Leave empty to auto-detect orchestrator (Kubernetes takes priority).

Authentication

Variable	Default	Description
CLAWORC_AUTH_DISABLED	false	Set to true to disable all authentication. Never use in production.
CLAWORC_RP_ORIGINS	http://localhost:8000	Allowed origins for WebAuthn passkey registration. Set to your dashboard URL in production. Comma-separated for multiple values.
CLAWORC_RP_ID	localhost	Relying Party ID for WebAuthn. Must match the domain of your dashboard. Example: claworc.example.com.

Caution

CLAWORC_RP_ID must match the domain users access the dashboard from. Passkey registration will fail if this is wrong.

Terminal sessions

Variable	Default	Description
CLAWORC_TERMINAL_HISTORY_LINES	1000	Number of output lines retained in the scrollback buffer for SSH terminal sessions. Set to 0 to disable scrollback.
CLAWORC_TERMINAL_RECORDING_DIR	(empty)	Directory to write terminal session recordings. Leave empty to disable. Recordings are timestamped files named by session ID.
CLAWORC_TERMINAL_SESSION_TIMEOUT	30m	How long an idle detached terminal session is kept before being reaped. Accepts Go duration strings: 30m, 1h, 2h30m.

LLM gateway

Variable	Default	Description
CLAWORC_LLM_GATEWAY_PORT	40001	Port the internal LLM gateway listens on. The gateway binds to 127.0.0.1 only and is never publicly accessible — instances reach it through an SSH tunnel. Change this if port 40001 conflicts with another service on the control plane host.
CLAWORC_LLM_RESPONSE_LOG	(empty)	Path to a file where raw upstream LLM response bodies are appended for debugging. Each entry includes a timestamp, model ID, API type, HTTP status, and the full response body. Leave empty (the default) to disable. Do not enable in production — response bodies may contain sensitive content.

Example configurations

Minimal Docker Compose

services:
  claworc:
    image: claworc/claworc:latest
    environment:
      - CLAWORC_DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - claworc-data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "8000:8000"

Production Kubernetes (via Helm values)

values.yaml

config:
  dataPath: /app/data
  k8sNamespace: claworc

# Pass additional env vars via extraEnv
extraEnv:
  - name: CLAWORC_RP_ORIGINS
    value: "https://claworc.example.com"
  - name: CLAWORC_RP_ID
    value: "claworc.example.com"
  - name: CLAWORC_TERMINAL_HISTORY_LINES
    value: "2000"
  - name: CLAWORC_TERMINAL_SESSION_TIMEOUT
    value: "1h"

Development (authentication disabled)

CLAWORC_DATA_PATH=./data \
CLAWORC_AUTH_DISABLED=true \
CLAWORC_DOCKER_HOST=unix:///var/run/docker.sock \
./claworc

Orchestrator selection

Claworc selects an orchestrator backend automatically:

1. Kubernetes — if a valid kubeconfig or in-cluster config is detected
2. Docker — if CLAWORC_DOCKER_HOST is set or the Docker socket is accessible
3. None — the control plane starts but cannot provision instances

Set CLAWORC_DOCKER_HOST explicitly to force Docker mode even when kubectl is available.