# bamboo-claw

`bamboo-claw` is a CLI-first Python client agent that connects a Bamboo Claw central server to a local OpenClaw gateway.

It is not a general-purpose SDK at this point. The main entry point is the `bambooclaw` command installed by the package.

## What It Does

- Connects to the Bamboo Claw central server over WebSocket.
- Connects to the local OpenClaw gateway over WebSocket.
- Registers the client with the server and waits for admin approval on first setup.
- Forwards `chat` commands from the server to the gateway and streams responses back.
- Supports Linux `systemd` installation and Windows `.bat` generation for service wrappers.

## Requirements

- Python 3.11+
- A reachable Bamboo Claw server
- A reachable OpenClaw gateway

Default gateway URL:

```text
ws://127.0.0.1:18789
```

## Installation

From PyPI:

```bash
pip install bamboo-claw
```

For local development from this repository:

```bash
pip install -e ./client
```

## Quick Start

### 1. Configure the client

```bash
bambooclaw setup --server https://central.example.com
```

You can also pass the gateway settings during setup:

```bash
bambooclaw setup \
  --server https://central.example.com \
  --gateway-url ws://127.0.0.1:18789 \
  --gateway-token YOUR_GATEWAY_TOKEN \
  --hostname worker-01
```

Notes:

- `--server` can be `http://`, `https://`, `ws://`, or `wss://`.
- If the path does not already end with `/ws/client`, the client appends it automatically.
- If no token exists yet, `setup` starts the registration flow immediately.

### 2. Approve the registration

On first setup, the client prints an approval code and waits for approval from the Bamboo Claw server.

The server-side approval flow uses this endpoint:

```text
POST /api/admin/registrations/{approval_code}/approve
```

After approval, the client stores the issued token locally.

### 3. Run the agent

```bash
bambooclaw run
```

This starts the long-running agent process. It connects to the central server and the local OpenClaw gateway, then waits for commands.

### 4. Check local configuration state

```bash
bambooclaw status
```

This prints the configured server URL, whether a token exists, the client ID, the gateway URL, and the configured hostname.

## Configuration File

Default config path:

```text
~/.bamboo_claw/bamboo_claw.toml
```

Legacy fallback path:

```text
~/.bamboo_claw/config.toml
```

Example config:

```toml
[server]
url = "https://central.example.com"

[auth]
token = "bcl_..."
client_id = "2f3c8d5a-7f3c-4c4a-b2d8-1f46d8f1e0d0"

[client]
hostname = "worker-01"

[gateway]
url = "ws://127.0.0.1:18789"
token = ""
```

The client also stores additional runtime data in `~/.bamboo_claw/`, including:

- `device-identity.json` for the persistent Ed25519 device identity used with the gateway
- `device-tokens.json` for gateway-issued device tokens

## Command Reference

### `bambooclaw setup`

Creates or updates local configuration and starts registration if no server token is present.

Useful options:

- `--config PATH`
- `--server URL`
- `--gateway-url URL`
- `--gateway-token TOKEN`
- `--hostname NAME`

### `bambooclaw run`

Starts the agent. If the gateway is unavailable on startup, the client keeps retrying in the background while continuing to reconnect to the server as needed.

Useful option:

- `--config PATH`

### `bambooclaw status`

Shows local config state.

Useful option:

- `--config PATH`

### `bambooclaw daemon install`

Installs and starts a Linux `systemd` service named `bamboo-claw.service`.

```bash
sudo bambooclaw daemon install
```

With an explicit config path:

```bash
sudo bambooclaw daemon install --config /etc/bamboo-claw/client.toml
```

Important behavior:

- Linux `systemd` only
- Requires root privileges
- Uses the current Python interpreter for `ExecStart`
- Uses the current working directory as `WorkingDirectory`

That means you should run the install command from the environment and directory you want the service to use.

Related commands:

```bash
bambooclaw daemon status
sudo bambooclaw daemon uninstall
```

### `bambooclaw windows-bat`

Generates a Windows startup batch file for use with a wrapper such as NSSM.

```bash
bambooclaw windows-bat --output C:\bamboo\start-client.bat
```

Example with explicit working directory, virtualenv activation script, and config path:

```bash
bambooclaw windows-bat \
  --output C:\bamboo\start-client.bat \
  --working-dir C:\bamboo \
  --venv-activate C:\bamboo\.venv\Scripts\activate.bat \
  --config C:\bamboo\bamboo_claw.toml
```

## Operational Notes

- If the server token is invalid or expired, the client clears the token and attempts the registration flow again.
- The gateway connection uses a persistent device identity and can store a gateway-issued device token after a successful handshake.
- The package currently exposes a few importable modules, but the stable interface is the CLI, not a documented Python library API.
