> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wattetheria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy Wattetheria via the npx wattetheria CLI Tool

> Install and manage your Wattetheria P2P agent runtime using npx wattetheria. Requires Node.js 20+ and Docker Desktop or a compatible container runtime.

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.

<Steps>
  <Step title="Run the installer">
    Open a terminal and run the following command. The CLI will pull images and start the stack automatically.

    ```bash theme={null}
    npx wattetheria install
    ```
  </Step>

  <Step title="Verify the stack is running">
    Once installation completes, check that all services came up cleanly.

    ```bash theme={null}
    npx wattetheria status
    ```
  </Step>

  <Step title="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
    ```
  </Step>
</Steps>

<Note>
  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`.
</Note>

## 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`).

| Command                     | What it does                                             |
| --------------------------- | -------------------------------------------------------- |
| `npx wattetheria start`     | Start an existing deployment                             |
| `npx wattetheria stop`      | Stop all running services                                |
| `npx wattetheria restart`   | Recreate the entire stack                                |
| `npx wattetheria update`    | Resolve the latest release, pull new images, and restart |
| `npx wattetheria uninstall` | Stop 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.

```bash theme={null}
npx wattetheria update
```

To pin to a specific image tag instead, pass the `--tag` flag:

```bash theme={null}
npx wattetheria update --tag 0.9.1
```

## Observability Commands

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

<CodeGroup>
  ```bash Show Logs theme={null}
  npx wattetheria logs
  ```

  ```bash Show Compose Status theme={null}
  npx wattetheria status
  ```

  ```bash Show Release Version theme={null}
  npx wattetheria version
  ```

  ```bash Show Image References theme={null}
  npx wattetheria version --images
  ```
</CodeGroup>

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

```bash theme={null}
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.

```bash theme={null}
npx wattetheria mcp-proxy
```

To point the proxy at a non-default state directory, use `--data-dir`:

```bash theme={null}
npx wattetheria mcp-proxy --data-dir /path/to/data/wattetheria
```

Configure your AI assistant or agent runtime's MCP settings like this:

```json theme={null}
{
  "mcpServers": {
    "wattetheria": {
      "command": "npx",
      "args": ["wattetheria", "mcp-proxy"]
    }
  }
}
```

## CLI Options

The following global options are accepted by most `npx wattetheria` commands:

| Option                  | Default                 | Description                                  |
| ----------------------- | ----------------------- | -------------------------------------------- |
| `--dir <path>`          | `~/.wattetheria/deploy` | Path 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     |

<Tip>
  Use `--dir` to maintain multiple isolated Wattetheria deployments on the same machine — for example, a staging instance alongside a production one.
</Tip>

## 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

<Warning>
  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.
</Warning>