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

# 3.13 Runtime Boxd Agent

> Deploy a vanilla Bindu agent to a boxd microVM with one CLI command

The agent code is a plain `bindufy(config, handler)` echo — identical to a local example. The interesting part is the deploy step: `bindu deploy agent.py --runtime=boxd` packages this directory, ships it to a [boxd](https://boxd.sh) microVM, installs deps, and serves the agent at its own public URL with persistent disk across suspend/resume.

## Code

Create `agent.py` with the code below, or save it directly from your editor.

```python theme={null}
"""Bindu echo agent — runs in-process locally, or in a boxd VM via the CLI.

The script body is a vanilla bindu agent: ``bindufy(config, handler)`` and
nothing else. There is no deploy logic here — that lives in the ``bindu
deploy`` CLI, which packages this directory, ships it to a boxd VM, installs
bindu + the user's deps, and starts the agent there. The host streams VM
logs and supervises until Ctrl-C; A2A clients talk directly to the public
URL printed at startup.

Local dev::

    python agent.py
    # serves on http://localhost:3773

Deploy to a boxd VM::

    pip install 'bindu[runtime-boxd]'
    export BOXD_TOKEN=$(boxd login --json | jq -r .token)
    bindu deploy agent.py --runtime=boxd --on-exit=suspend

After ``✓ runtime-boxd-example serving at https://...``, hit it::

    curl https://runtime-boxd-example.boxd.sh/health
    curl https://runtime-boxd-example.boxd.sh/.well-known/agent.json

Ctrl-C explicitly suspends the VM (preserves memory + disk state); re-running
``bindu deploy`` resumes in ~1s with DID keys, vector store, conversation
history all intact.

See ``docs/runtime/`` for the full runtime-provider documentation.
"""

from bindu.penguin.bindufy import bindufy


def handler(messages: list[dict[str, str]]):
    """Echo the latest user message back."""
    if not messages:
        return "send a message"
    return [
        {
            "role": "assistant",
            "content": messages[-1].get("content", ""),
        }
    ]


config = {
    "author": "you@example.com",
    "name": "runtime-boxd-example",
    "description": "Echo agent running inside a boxd microVM.",
    "deployment": {
        # The agent inside the VM binds 0.0.0.0:3773 so the boxd proxy can
        # reach it. The host injects BINDU_PUBLIC_URL automatically when
        # deployed via ``bindu deploy``.
        "url": "http://0.0.0.0:3773",
        "expose": True,
    },
}


if __name__ == "__main__":
    bindufy(config, handler)
```

## How It Works

**Agent code (unchanged)**

* Same `bindufy(config, handler)` shape as every other Bindu example
* Binds to `0.0.0.0:3773` so the boxd proxy can reach it inside the VM
* No deploy logic in the script — that lives in the `bindu deploy` CLI

**Deploy command**

* `bindu deploy agent.py --runtime=boxd --on-exit=suspend`
* Packages this directory and ships it to a fresh boxd microVM
* Installs bindu + the agent's deps inside the VM
* Starts the agent and prints a public URL like `https://runtime-boxd-example.boxd.sh`
* Host process streams VM logs and supervises until Ctrl-C

**Suspend / resume**

* Ctrl-C on the local terminal suspends the VM (preserves memory + disk + DID keys)
* Re-running `bindu deploy` resumes in \~1s — vector store, conversation history, and DID identity all intact

**Logs and teardown**

* `bindu logs runtime-boxd-example` — fetch logs after suspend
* `bindu destroy runtime-boxd-example` — stop and discard the VM (loses disk + DID keys)

## Dependencies

```bash theme={null}
uv init
uv add bindu
# For the deploy step:
pip install 'bindu[runtime-boxd]'
```

## Environment Setup

```bash theme={null}
export BOXD_TOKEN=$(boxd login --json | jq -r .token)
```

## Run

Local dev:

```bash theme={null}
uv run agent.py
# http://localhost:3773
```

Deploy to a boxd microVM:

```bash theme={null}
bindu deploy agent.py --runtime=boxd --on-exit=suspend
```

When you see `✓ runtime-boxd-example serving at https://...`, the VM is live:

```bash theme={null}
curl https://runtime-boxd-example.boxd.sh/.well-known/agent.json
curl https://runtime-boxd-example.boxd.sh/health
```

## Example API Calls

<AccordionGroup>
  <Accordion title="Message Send Request">
    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "method": "message/send",
      "params": {
        "message": {
          "role": "user",
          "kind": "message",
          "messageId": "9f11c870-5616-49ad-b187-d93cbb100001",
          "contextId": "9f11c870-5616-49ad-b187-d93cbb100002",
          "taskId": "9f11c870-5616-49ad-b187-d93cbb100003",
          "parts": [
            {
              "kind": "text",
              "text": "echo me"
            }
          ]
        },
        "configuration": {
          "acceptedOutputModes": ["application/json"]
        }
      },
      "id": "9f11c870-5616-49ad-b187-d93cbb100003"
    }
    ```
  </Accordion>

  <Accordion title="Task get Request">
    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "method": "tasks/get",
      "params": {
        "taskId": "9f11c870-5616-49ad-b187-d93cbb100003"
      },
      "id": "9f11c870-5616-49ad-b187-d93cbb100004"
    }
    ```
  </Accordion>
</AccordionGroup>

Point requests at `http://localhost:3773` while running locally, or at the public `https://<agent-name>.boxd.sh` URL printed by `bindu deploy`.

## Frontend Setup

```bash theme={null}
# Clone the Bindu repository
git clone https://github.com/GetBindu/Bindu

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Start frontend development server
npm run dev
```

Open [http://localhost:5173](http://localhost:5173) and try to chat with the runtime-boxd agent.