Deployment
How to run clawft and the WeftOS node daemon in production: Docker, the per-user daemon, per-project kernels, WASM targets, and recommended configuration.
This page covers how the pieces run on a machine. The step-by-step guides are linked from each section.
Choose a shape
| Shape | Use it for | Start here |
|---|---|---|
| Docker gateway | A weft gateway (REST and WebSocket API) on a server | Docker Deployment |
| Per-user daemon | A developer or edge machine that runs projects, cogs and a mesh node | Per-user daemon |
| WASM | Browser tabs, wasmtime or edge hosts | WASM |
Docker
The image ghcr.io/weftos/weftos is multi-arch (linux/amd64, linux/arm64), based on Alpine, and runs as the non-root user weft. It holds weft and weaver; the default command is gateway, which also starts a kernel daemon in the container. Config lives in /home/weft/.clawft, kernel state in /home/weft/.weftos.
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:latestTags, compose, health checks, hardening and troubleshooting are in the Docker Deployment guide.
Per-user daemon
On a workstation or edge node, weaver runs one daemon per user. Install the binaries (see Installation), then:
weaver kernel start --profile user # start the per-user daemon (backgrounds by default)
weaver kernel status --profile user
weaver kernel stop --profile userWithout --profile user, weaver kernel start starts a daemon for the project in the current directory (or the legacy ~/.clawft daemon). --profile can also be set with WEAVER_PROFILE.
To start it at login, print a launchd or systemd user unit and install it with the commands the tool prints. weaver service unit never runs launchctl or systemctl itself:
weaver service unit --kind launchd --out ~/Library/LaunchAgents/ai.weftos.user.plist
weaver service unit --kind systemd --out ~/.config/systemd/user/weftos.serviceThe per-user daemon keeps its state under ~/.weftos/run. A kernel started inside a project directory uses <project>/.weftos/runtime instead, and $WEFTOS_RUNTIME_DIR overrides both (crates/clawft-types/src/runtime_paths.rs).
Per-project kernels
Under ADR-103 the user daemon hosts a kernel for each registered project, so projects stay isolated while sharing one mesh identity:
weaver project add <source> # fetch, register and detect a project
weaver project up <slug> # start it
weaver project status
weaver project down <slug>
weaver project remove <slug>weaver kernel start --project <id-or-name> and weaver kernel stop --project <id-or-name> act on one project's kernel. The repository guides project-install.md and developer-quickstart.md cover installing a project from another machine over the mesh.
Tailnet router
The user daemon can serve every project on the machine behind one HTTPS name, by path, over a tailnet. It is off by default ([router] enabled = true in ~/.weftos/weave.toml), is tailnet-only, and never enables Funnel. Use weaver route list, weaver route reload and weaver route serve --plan to inspect it. ADR-116, which defines it, still has status Proposed. See the repository guide tailnet-router.md.
Updating
weaver update installs a signed release over the binaries it installed and offers to restart the daemon. See Installation.
WASM
scripts/build.sh wasi # wasm32-wasip2, for wasmtime and edge hosts
scripts/build.sh browser # wasm32-unknown-unknown, for browser tabsThe wasm32-wasip2 module has size gates of 300 KB raw and 120 KB gzipped in CI (release-wasm profile). For the browser, serve clawft_wasm.js and clawft_wasm_bg.wasm from any static host, with Content-Type: application/wasm for the .wasm file and compression on. See Browser Mode and the WASM deployment guide.
Recommended configuration
A conservative gateway configuration, in ~/.clawft/config.json:
{
"agents": {
"defaults": {
"model": "anthropic/claude-sonnet-4-20250514",
"max_tokens": 8192,
"max_tool_iterations": 10,
"memory_window": 30
}
},
"tools": {
"commandPolicy": { "mode": "allowlist" },
"urlPolicy": { "enabled": true, "allowPrivate": false }
}
}The gateway binds to 127.0.0.1 by default (ADR-102). Binding a non-loopback address is refused unless TLS is terminated in front of it and gateway.dangerously_plain_http is set (or --dangerously-plain-http is passed). The Docker image sets that flag because the container boundary is meant to be the TLS boundary.
Checklist
- Set API keys through environment variables, not config files.
- Keep
commandPolicy.modeatallowlist(the default) andurlPolicy.allowPrivateatfalse. - Publish container ports on loopback or behind a TLS proxy.
- Mount config read-only in containers and use named volumes for state.
- Enable health checks (
weft status, orGET /api/healthon the gateway). - Set
RUST_LOGtowarnfor production andinfoordebugfor troubleshooting. - Run
weft security scan <path>before deploying.
Troubleshooting
Container exits immediately. Check that the config is valid JSON and the mounts are right:
docker run --rm -it -v "$HOME/.clawft:/home/weft/.clawft:ro" ghcr.io/weftos/weftos:latest status --detailedCannot reach an LLM API. Check DNS and egress from the container, and pass HTTPS_PROXY if you are behind a proxy.
Permission denied on config. The container user is not root; make the file readable (chmod 644 ~/.clawft/config.json).
weaver update refuses. The install belongs to Homebrew, cargo or a source build. Use the update command it prints.