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

# NanoClaw: Agent Orchestration with the Gateway

> Run NanoClaw agents with OneCLI handling credential injection and policy enforcement. No code changes needed in the agent.

[NanoClaw](https://github.com/onecli/nanoclaw) is an open-source agent runtime that isolates every agent in its own Docker container. OneCLI is an open-source credential and policy layer for AI agents. Together, they give you the full stack: runtime isolation, credential isolation, and policy enforcement.

## The full stack

| Layer                    | What it solves                                                                                   | Project  |
| ------------------------ | ------------------------------------------------------------------------------------------------ | -------- |
| **Runtime isolation**    | Each agent gets its own container, filesystem, and process space. No ambient access to the host. | NanoClaw |
| **Credential isolation** | Agents never hold raw API keys. Credentials are injected at the proxy level per-request.         | OneCLI   |
| **Policy enforcement**   | Rules control what agents can access, which operations are allowed, and how often.               | OneCLI   |

NanoClaw solves the problem of agents escaping their sandbox. OneCLI solves the problem of agents misusing the access they've been given. You need both.

## How it works

NanoClaw runs each agent in a Docker container. OneCLI runs as a sidecar (or shared service) that acts as the HTTP gateway for all agent traffic. When NanoClaw spawns an agent container, it configures the agent to route HTTP traffic through OneCLI's gateway.

```mermaid theme={null}
%%{init: {'theme': 'neutral', 'flowchart': {'defaultRenderer': 'elk', 'nodeSpacing': 30, 'rankSpacing': 40}}}%%
flowchart LR
    NC["<b>NanoClaw</b><br/>Spawns agent containers"]
    A1["<b>Agent 1</b><br/>Docker container"]
    A2["<b>Agent 2</b><br/>Docker container"]
    OC["<b>OneCLI Gateway</b><br/>Credential injection<br/>+ policy enforcement"]
    S["<b>External Services</b><br/>Gmail · GitHub · Slack"]

    NC --> A1
    NC --> A2
    A1 -- "HTTP via proxy" --> OC
    A2 -- "HTTP via proxy" --> OC
    OC --> S
```

1. NanoClaw creates a Docker container for the agent
2. The container's `HTTP_PROXY` / `HTTPS_PROXY` environment variables point to OneCLI's gateway
3. The agent makes normal HTTP requests. It doesn't know OneCLI exists
4. OneCLI checks rules (block/rate-limit), injects credentials, and forwards the request
5. The response flows back to the agent

## Setup

### Prerequisites

* Docker running on your machine
* OneCLI running (see [Quickstart](/quickstart))
* NanoClaw installed ([github.com/qwibitai/nanoclaw](https://github.com/onecli/nanoclaw))

### 1. Start OneCLI

```bash theme={null}
docker run --pull always \
  -p 10254:10254 \
  -p 10255:10255 \
  -v onecli-data:/app/data \
  ghcr.io/onecli/onecli
```

### 2. Configure agents and credentials in OneCLI

You can do this through the dashboard at [localhost:10254](http://localhost:10254), or automate it with the [OneCLI CLI](/cli/onecli-cli):

<Tabs>
  <Tab title="CLI (recommended for automation)">
    ```bash theme={null}
    # Install the CLI
    curl -fsSL onecli.sh/cli/install | sh

    # Create an agent for each NanoClaw agent
    onecli agents create --name "email-agent" --identifier email-agent

    # Add credentials
    onecli secrets create --name "Gmail" --type google --value "$GMAIL_TOKEN"

    # Assign specific secrets to the agent
    AGENT_ID=$(onecli agents list --quiet id | head -1)
    onecli agents set-secrets --id "$AGENT_ID" --secret-ids "$SECRET_ID"
    onecli agents set-secret-mode --id "$AGENT_ID" --mode selective
    ```

    This is especially useful when NanoClaw is provisioning agents dynamically. The CLI lets your orchestrator create agent identities, assign scoped credentials, and configure rules without any manual dashboard interaction.
  </Tab>

  <Tab title="Dashboard">
    Open [localhost:10254](http://localhost:10254) and:

    * Create an agent (each NanoClaw agent should have its own OneCLI agent identity)
    * Add credentials for the services the agent needs
    * Set up [rules](/guides/rules) to control what the agent can do
  </Tab>
</Tabs>

### 3. Configure NanoClaw to route through OneCLI

When NanoClaw spawns agent containers, configure them to use OneCLI as their HTTP proxy. The agent containers need:

* `HTTP_PROXY` and `HTTPS_PROXY` pointing to OneCLI's gateway
* The OneCLI CA certificate for HTTPS interception
* A `Proxy-Authorization` header with the agent's access token

If you're using the [Node.js SDK](/sdks/node), `applyContainerConfig()` handles all of this automatically:

```typescript theme={null}
import { OneCLI } from "@onecli-sh/sdk";

const onecli = new OneCLI({
  url: "http://localhost:10254",
  apiKey: "oc_agent_access_token",
});

const args = ["run", "-i", "--rm", "--name", "my-nanoclaw-agent"];
await onecli.applyContainerConfig(args);

// args now has HTTPS_PROXY, CA certs, and volume mounts configured
```

## One-line install (Cloud)

If you're using OneCLI Cloud, the dashboard provides a one-line install command that clones NanoClaw, configures your `.env` with the correct Cloud URL and API key, installs dependencies, and sets up the CLI:

```bash theme={null}
curl -fsSL https://app.onecli.sh/v1/install/nanoclaw | sh
```

After the script completes, follow the on-screen instructions to run the `/setup` wizard inside the NanoClaw directory.

## Migrating from self-hosted to Cloud

If you're already running NanoClaw with a self-hosted OneCLI instance and want to move to Cloud, use the migration script:

```bash theme={null}
curl -fsSL https://app.onecli.sh/v1/migrate/nanoclaw | sh
```

The migration script:

1. Exports secrets from your local OneCLI instance
2. Updates your CLI config to point at OneCLI Cloud
3. Finds all NanoClaw installations on your machine (via launchd, systemd, or common directories)
4. Updates each NanoClaw `.env` with the Cloud URL and API key
5. Restarts NanoClaw services so they route through Cloud

<Note>
  After migration, reconnect your OAuth app integrations (Gmail, GitHub, etc.) in the Cloud dashboard since OAuth tokens are not transferable between instances.
</Note>

## Per-agent policies

Since each NanoClaw agent gets its own OneCLI agent identity, you can set different rules per agent:

* Your "email-agent" can read emails but not delete them
* Your "code-agent" can access GitHub but not Slack
* Your "research-agent" has read-only access to everything, rate-limited to 100 requests per hour

See [Rules](/guides/rules) for the full details on setting up policies.