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
weftandweaver, in/usr/local/bin.- A non-root user
weftwith$HOME=/home/weft. Config and state live in two volumes:/home/weft/.clawftand/home/weft/.weftos. - A default
/home/weft/.clawft/config.jsonthat turns on the Bearer-token-gated REST and WebSocket API on port 8080, bound to0.0.0.0inside the container, over plain HTTP. Only/api/healthand the token-bootstrap path are public. - An entrypoint that runs
weftwith your arguments. The default command isgateway. Forgateway, the entrypoint first startsweaver kernel start --foregroundin the background and waits up to 30 seconds for it to answer, because the gateway reports the kernel's reachability on/api/health. SetWEFT_NO_EMBEDDED_KERNEL=1to skip that. - A
HEALTHCHECKthat runsweft statusevery 30 seconds.
Quick start
docker pull ghcr.io/weftos/weftos:latest
docker run --rm ghcr.io/weftos/weftos:latest --versionThe 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:latestImage tags
The release workflow tags each image with the version without a leading v (for example 0.8.4) and with latest.
| Tag | Contents |
|---|---|
latest | The most recent image the workflow published |
X.Y.Z | A 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 gatewayAPI 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 -fIt 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 -dHealth 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
weftuser; do not override it with--user 0:0. - Mount config read-only and keep state on named volumes.
- Publish on
127.0.0.1or behind a TLS proxy; the API is plain HTTP inside the container. - Use
--network=nonefor 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 --detailedPermission 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
Kernel Modules
Where each part of the clawft-kernel crate is documented, grouped by subsystem. The per-file reference was removed because it could not be kept in step with the code.
Release Process
Tag-driven SemVer releases: cargo-dist binaries and installers, signed manifest, WASM, SBOMs, crates.io, multi-arch Docker, and release gates.