Skip to main content

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.

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

uv init
uv add bindu
# For the deploy step:
pip install 'bindu[runtime-boxd]'

​
Environment Setup

export BOXD_TOKEN=$(boxd login --json | jq -r .token)

​
Run

Local dev: 
uv run agent.py
# http://localhost:3773
Deploy to a boxd microVM: 
bindu deploy agent.py --runtime=boxd --on-exit=suspend
When you see ✓ runtime-boxd-example serving at https://..., the VM is live: 
curl https://runtime-boxd-example.boxd.sh/.well-known/agent.json
curl https://runtime-boxd-example.boxd.sh/health

​
Example API Calls

{
  "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"
}

{
  "jsonrpc": "2.0",
  "method": "tasks/get",
  "params": {
    "taskId": "9f11c870-5616-49ad-b187-d93cbb100003"
  },
  "id": "9f11c870-5616-49ad-b187-d93cbb100004"
}
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

# 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 and try to chat with the runtime-boxd agent.