Environment variables

All Clawforce configuration is done via environment variables with the CLAWFORCE_ prefix.

Core settings

Variable	Default	Description
CLAWFORCE_DATA_PATH	/app/data	Directory to store the Clawforce’s data like SQLite database, SSH key pair, and etc. Mount a persistent volume here.
CLAWFORCE_K8S_NAMESPACE	clawforce	Kubernetes namespace where agent instances are created. Must exist before starting.
CLAWFORCE_BOOTSTRAP_DEFAULT_CONTAINER_IMAGE	(empty, falls back to clawforceone/agent-chromium:1.4.2)	Initial default agent image to seed into settings for fresh installs. Useful for Helm installs that should start from a pinned runtime image instead of the built-in fallback.
CLAWFORCE_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
CLAWFORCE_AUTH_DISABLED	false	Set to true to disable all authentication. Never use in production.
CLAWFORCE_RP_ORIGINS	http://localhost:8000	Allowed origins for WebAuthn passkey registration. Set to your dashboard URL in production. Comma-separated for multiple values.
CLAWFORCE_RP_ID	localhost	Relying Party ID for WebAuthn. Must match the domain of your dashboard. Example: clawforce.example.com.

Caution

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

Terminal sessions

Variable	Default	Description
CLAWFORCE_TERMINAL_HISTORY_LINES	1000	Number of output lines retained in the scrollback buffer for SSH terminal sessions. Set to 0 to disable scrollback.
CLAWFORCE_TERMINAL_RECORDING_DIR	(empty)	Directory to write terminal session recordings. Leave empty to disable. Recordings are timestamped files named by session ID.
CLAWFORCE_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
CLAWFORCE_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.
CLAWFORCE_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:
  clawforce:
    image: clawforceone/clawforce:1.4.2
    environment:
      - CLAWFORCE_DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - clawforce-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: clawforce

# Pass additional env vars via extraEnv
extraEnv:
  - name: CLAWFORCE_RP_ORIGINS
    value: "https://clawforce.example.com"
  - name: CLAWFORCE_RP_ID
    value: "clawforce.example.com"
  - name: CLAWFORCE_TERMINAL_HISTORY_LINES
    value: "2000"
  - name: CLAWFORCE_TERMINAL_SESSION_TIMEOUT
    value: "1h"

Development (authentication disabled)

CLAWFORCE_DATA_PATH=./data \
CLAWFORCE_AUTH_DISABLED=true \
CLAWFORCE_DOCKER_HOST=unix:///var/run/docker.sock \
./clawforce

Orchestrator selection

Clawforce selects an orchestrator backend automatically:

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

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