clawft

Docker Deployment

Run the WeftOS image from GHCR, configure it, compose it, and build it locally.

Docker Deployment

WeftOS publishes a multi-arch (linux/amd64, linux/arm64) image at ghcr.io/weftos/weftos. It is based on alpine:3.21 and is built from the repository by a self-contained multi-stage Dockerfile: the build compiles weft and weaver as static musl binaries, so the image does not depend on the cargo-dist release assets. Arm64 is built on a native runner, not under QEMU.

The repository's operator guide has more detail: docs/deployment/docker.md.

Images published before 2026-10-27 live under ghcr.io/weave-logic-ai/weftos.

What is in the image

  • weft and weaver, in /usr/local/bin.
  • A non-root user weft with $HOME=/home/weft. Config and state live in two volumes: /home/weft/.clawft and /home/weft/.weftos.
  • A default /home/weft/.clawft/config.json that turns on the Bearer-token-gated REST and WebSocket API on port 8080, bound to 0.0.0.0 inside the container, over plain HTTP. Only /api/health and the token-bootstrap path are public.
  • An entrypoint that runs weft with your arguments. The default command is gateway. For gateway, the entrypoint first starts weaver kernel start --foreground in the background and waits up to 30 seconds for it to answer, because the gateway reports the kernel's reachability on /api/health. Set WEFT_NO_EMBEDDED_KERNEL=1 to skip that.
  • A HEALTHCHECK that runs weft status every 30 seconds.

Quick start

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

The entrypoint is weft, so everything after the image name is a weft argument. A bare docker run starts the gateway. Publish the port on loopback unless you front it with a TLS proxy, because the container serves plain HTTP:

docker run -d --name weftos \
  -v weftos-clawft:/home/weft/.clawft \
  -v weftos-state:/home/weft/.weftos \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/weftos/weftos:latest

Image tags

The release workflow tags each image with the version without a leading v (for example 0.8.4) and with latest.

TagContents
latestThe most recent image the workflow published
X.Y.ZA pinned release, such as 0.8.4

The workflow runs after any successful Release run on a version tag and does not skip release candidates, so latest can point at a pre-release. Pin a version in production.

Configuration

Mount your own config over the default (read-only is fine; the workspace needs a writable volume):

docker run --rm -it \
  -v "$HOME/.clawft:/home/weft/.clawft:ro" \
  -e OPENAI_API_KEY \
  ghcr.io/weftos/weftos:latest gateway

API keys come from environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, and so on). Do not bake them into an image. The gateway default is loopback (ADR-102); the shipped config overrides it so a published port is reachable, which is why the container boundary should be your TLS boundary.

Docker Compose

The repository ships a working definition in scripts/deploy/docker-compose.yml:

docker compose -f scripts/deploy/docker-compose.yml up -d
docker compose -f scripts/deploy/docker-compose.yml logs -f

It uses the named volume weft-config for /home/weft/.clawft, publishes ${WEFT_PORT:-8080}, and takes the image tag from WEFT_VERSION:

WEFT_VERSION=0.8.4 docker compose -f scripts/deploy/docker-compose.yml up -d

Health checks

docker inspect --format '{{.State.Health.Status}}' weftos
docker exec weftos weft status
curl -sS http://127.0.0.1:8080/api/health

/api/health returns 503 with a "degraded" status when the gateway cannot reach a kernel daemon.

Building locally

./scripts/build/docker-build.sh --tag dev --version dev
# or
docker build -t weft:dev --build-arg VERSION=dev .

The build compiles inside Docker; no pre-built binary is needed. A kernel-only image (weaver, no gateway) builds from crates/clawft-kernel/Dockerfile.alpine:

docker build -f crates/clawft-kernel/Dockerfile.alpine -t weft-kernel:dev .

Security

  • Run as the built-in weft user; do not override it with --user 0:0.
  • Mount config read-only and keep state on named volumes.
  • Publish on 127.0.0.1 or behind a TLS proxy; the API is plain HTTP inside the container.
  • Use --network=none for offline work, or a dedicated Docker network to limit egress.
  • Pass secrets by environment variable or Docker secret, never in the image.

Troubleshooting

Container exits immediately. Check the config is valid JSON and that any provider key your config references is set:

docker run --rm -it -v "$HOME/.clawft:/home/weft/.clawft:ro" ghcr.io/weftos/weftos:latest status --detailed

Permission denied on a mounted config. The container runs as a non-root user. Make the file readable (chmod 644 ~/.clawft/config.json).

"degraded" health. The kernel daemon did not start. Look at the container logs, or check whether WEFT_NO_EMBEDDED_KERNEL=1 is set.

Cannot reach an LLM API. Test from inside the container, and pass HTTPS_PROXY, HTTP_PROXY and NO_PROXY if you are behind a proxy:

docker run --rm -e OPENAI_API_KEY ghcr.io/weftos/weftos:latest agent -m "ping"

CI and release pipeline

.github/workflows/release-docker.yml runs after the Release workflow succeeds on a tag (or by manual dispatch). It builds each architecture on a native runner, merges the digests into one multi-arch manifest, and then pulls the published image for a health smoke test (scripts/release/docker-smoke.sh).

Pull requests run the gates in .github/workflows/pr-gates.yml, which include clippy, the test suite, WASM and binary size checks, browser WASM checks, cargo audit, the docs site build, and an integration smoke test. Run the same checks locally with scripts/build.sh gate.

See also

On this page