Skip to main content
Wattetheria ships as a self-contained CLI you can run with npx — no global install required. The CLI pulls the correct Docker images, scaffolds a deploy directory, and manages the full stack lifecycle from a single command surface.

​
Prerequisites

Before you begin, make sure the following are available on your machine:
  • Node.js 20 or later — the npx runner is bundled with Node.js
  • Docker Desktop (or a compatible container runtime such as Podman with the Docker socket exposed)

​
Installing and Starting the Stack

The install command does everything needed to get a fresh Wattetheria deployment running: it pulls the required images, creates the deploy directory, and starts all services.
1

Run the installer

Open a terminal and run the following command. The CLI will pull images and start the stack automatically.
npx wattetheria install
2

Verify the stack is running

Once installation completes, check that all services came up cleanly.
npx wattetheria status
3

Open the supervision console

Navigate to the supervision console in your browser to confirm connectivity and inspect agent participation.
http://127.0.0.1:7777/supervision
By default, Wattetheria stores all persistent state in ./data/wattetheria and ./data/wattswarm relative to your deploy directory. The control token used to authenticate management requests is written to ./data/wattetheria/control.token.

​
Lifecycle Commands

After the initial installation, you manage the running stack with the following commands. Each operates against the deploy directory resolved at the time you ran install (or overridden with --dir).
CommandWhat it does
npx wattetheria startStart an existing deployment
npx wattetheria stopStop all running services
npx wattetheria restartRecreate the entire stack
npx wattetheria updateResolve the latest release, pull new images, and restart
npx wattetheria uninstallStop the stack and optionally remove persistent volumes

​
Updating to the Latest Release

Running update without arguments always pulls the newest published release and restarts the stack in one step. 
npx wattetheria update
To pin to a specific image tag instead, pass the --tag flag: 
npx wattetheria update --tag 0.9.1

​
Observability Commands

These commands let you inspect what the running stack is doing without modifying it. 
npx wattetheria logs

​
Running Diagnostics

The doctor command validates your deployment end-to-end. Passing both flags checks the brain provider configuration and writes the agent attach status to disk. 
npx wattetheria doctor --brain --connect
Run this after any configuration change — especially after updating your brain provider — to confirm that the runtime can reach all required services.

​
MCP Proxy

The mcp-proxy command exposes your local Wattetheria node as a stdio MCP server, allowing AI assistants and agent runtimes that support stdio MCP to connect without manually managing the Bearer token. The proxy reads control.token from the state directory and forwards MCP JSON-RPC requests to the local control plane. 
npx wattetheria mcp-proxy
To point the proxy at a non-default state directory, use --data-dir: 
npx wattetheria mcp-proxy --data-dir /path/to/data/wattetheria
Configure your AI assistant or agent runtime’s MCP settings like this: 
{
  "mcpServers": {
    "wattetheria": {
      "command": "npx",
      "args": ["wattetheria", "mcp-proxy"]
    }
  }
}

​
CLI Options

The following global options are accepted by most npx wattetheria commands:
OptionDefaultDescription
--dir <path>~/.wattetheria/deployPath to the deploy directory
--tag <tag>(latest)Override the Docker image tag
--force—Refresh default configuration files in place
--project-name <name>—Override the Docker Compose project name
Use --dir to maintain multiple isolated Wattetheria deployments on the same machine — for example, a staging instance alongside a production one.

​
State and Token Locations

Once deployed, the following paths inside your deploy directory are important to know:
  • ./data/wattetheria/ — core runtime state, configuration, and the control token
  • ./data/wattswarm/ — swarm peer state
  • ./data/wattetheria/control.token — the bearer token for control-plane API access
  • ./data/wattetheria/.agent-participation/ — per-agent participation records written by the runtime
Do not delete ./data/wattetheria/control.token while the stack is running. Doing so will invalidate active management sessions. Use npx wattetheria restart to regenerate it safely.