Docker Deployment

clawft ships as a minimal FROM scratch Docker image containing only the statically-linked weft binary. The resulting image is typically around 5 MB.

Prerequisites

• Docker 20.10 or later

Quick Start

Pull the pre-built image and run the gateway:

docker pull ghcr.io/clawft/clawft:latest
docker run --rm -it ghcr.io/clawft/clawft:latest --version

By default the container starts in gateway mode (weft gateway).

Building from Source

Clone the repository and build a static musl binary, then build the Docker image:

git clone https://github.com/weave-logic-ai/clawft.git
cd clawft

# Build the static binary (requires musl target)
rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl

# Prepare the Docker build context
mkdir -p docker-build
cp target/x86_64-unknown-linux-musl/release/weft docker-build/weft-linux-x86_64

# Build the image
docker build -t clawft:local .

Configuration

Mounting a Config File

The container expects configuration at /root/.clawft/config.json. Mount your local config into the container:

docker run --rm -it \
  -v "$HOME/.clawft:/root/.clawft:ro" \
  ghcr.io/clawft/clawft:latest gateway

Environment Variables

Pass API keys and settings via environment variables:

docker run --rm -it \
  -e OPENAI_API_KEY="sk-..." \
  -e CLAWFT_CONFIG="/root/.clawft/config.json" \
  -v "$HOME/.clawft:/root/.clawft:ro" \
  ghcr.io/clawft/clawft:latest gateway

Workspace Persistence

To persist agent session data across container restarts, mount the workspace directory:

docker run --rm -it \
  -v "$HOME/.clawft:/root/.clawft" \
  ghcr.io/clawft/clawft:latest gateway

Docker Compose

A Docker Compose configuration for running the gateway with persistent storage:

services:
  clawft:
    image: ghcr.io/clawft/clawft:latest
    command: ["gateway"]
    restart: unless-stopped
    volumes:
      - ./config.json:/root/.clawft/config.json:ro
      - clawft-data:/root/.clawft/workspace
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    healthcheck:
      test: ["CMD", "/usr/local/bin/weft", "status"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  clawft-data:

Start the service:

docker compose up -d
docker compose logs -f clawft

Health Checks

The weft status command returns a non-zero exit code if the agent cannot initialise. Use it as a Docker health check (shown in the Compose example above) or probe it manually:

docker exec <container> /usr/local/bin/weft status

Security Considerations

The FROM scratch image has no shell, no package manager, and no OS libraries -- the attack surface is minimal. For additional hardening:

• Read-only filesystem: mount the config volume as :ro and use a named volume for workspace data.
• Non-root execution: the scratch image has no users, so the process runs as UID 0 inside a minimal namespace. For stricter isolation, run with --user 1000:1000 and adjust volume permissions accordingly.
• Network restrictions: use --network=none for offline testing, or create a dedicated Docker network to restrict egress.
• Secrets: never bake API keys into the image. Pass them via environment variables or Docker secrets.

Troubleshooting

Container exits immediately

Check that the config file is valid JSON and the volume mount path is correct:

docker run --rm -it \
  -v "$HOME/.clawft:/root/.clawft:ro" \
  ghcr.io/clawft/clawft:latest status --detailed

Permission denied on config file

Ensure the config file is readable by the container user. On Linux:

chmod 644 ~/.clawft/config.json

Cannot reach LLM API

Verify DNS and network access from the container:

docker run --rm ghcr.io/clawft/clawft:latest agent -m "ping"

If running behind a corporate proxy, pass proxy environment variables:

docker run --rm -e HTTPS_PROXY="http://proxy:8080" ...

CI/CD Pipeline (K2)

clawft uses a GitHub Actions workflow (.github/workflows/pr-gates.yml) to enforce quality gates on every pull request. The pipeline also supports multi-arch Docker image builds for releases.

PR Gate Jobs

Every pull request must pass all of the following jobs before merge:

The pipeline uses concurrency groups to cancel stale runs when new commits are pushed to the same PR branch.

Clippy Gate

Clippy runs with -D warnings (deny all warnings), which means any new warning introduced by a PR will fail the build:

cargo clippy --workspace -- -D warnings

Test Gate

The full workspace test suite runs without feature flags to catch regressions in the default build:

cargo test --workspace

WASM Size Assertion

The WASM size gate builds the clawft-wasm crate with the release-wasm profile and checks both raw and gzipped sizes:

cargo build --target wasm32-wasip2 --profile release-wasm -p clawft-wasm
bash scripts/bench/wasm-size-gate.sh "$WASM_BINARY" 300 120

The release-wasm profile uses opt-level = "z" for aggressive size optimization. The CI job also installs binaryen for wasm-opt.

Binary Size Check

The release binary must stay under 10 MB:

cargo build --release --bin weft
SIZE_BYTES=$(wc -c < target/release/weft)
# Fail if > 10 MB

A size report is posted to the GitHub Actions step summary for visibility.

Multi-Arch Docker Release

The CI pipeline supports multi-architecture Docker image builds:

docker buildx build --platform linux/amd64,linux/arm64 -t weft .

The Dockerfile uses a multi-stage build with cargo-chef for dependency caching:

1. Chef stage: Install cargo-chef for dependency recipe extraction
2. Planner stage: Generate the dependency recipe from Cargo.toml
3. Builder stage: Cook dependencies (cached layer), then build the app
4. Runtime stage: debian:bookworm-slim with only the stripped binary

The runtime image includes ca-certificates, libssl3, and libgcc-s1 (required by wasmtime). It runs as a non-root weft user.

Docker Image Variants

To build with WASM plugin support:

docker build --build-arg FEATURES="wasm-plugins" -t weft:wasm .

Integration Smoke Test

The smoke test job runs after the test suite passes:

1. Build a Docker image using docker/build-push-action@v6 with GHA cache
2. Start the container in gateway mode (weft gateway)
3. Wait 5 seconds and verify the container is still running
4. Shut down the container

This catches issues like missing runtime dependencies, incorrect entrypoint configuration, or crash-on-startup bugs that unit tests cannot detect.

See Also

• Installation -- source build instructions
• Configuration -- runtime configuration reference