clawft

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

ShapeUse it forStart here
Docker gatewayA weft gateway (REST and WebSocket API) on a serverDocker Deployment
Per-user daemonA developer or edge machine that runs projects, cogs and a mesh nodePer-user daemon
WASMBrowser tabs, wasmtime or edge hostsWASM

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:latest

Tags, 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 user

Without --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.service

The 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 tabs

The 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.

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.mode at allowlist (the default) and urlPolicy.allowPrivate at false.
  • 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, or GET /api/health on the gateway).
  • Set RUST_LOG to warn for production and info or debug for 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 --detailed

Cannot 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.

On this page