Skip to main content

​
Situation

Your bindu agent runs fine locally, but python my_agent.py ties it to your machine. The moment you close the terminal it’s gone — no public URL, no persistent identity, no way for other agents or users to reach it. Hosting it yourself means provisioning a server, managing TLS, keeping the process alive, and handling secrets safely. That’s infrastructure work that has nothing to do with your agent’s logic.

​
Task

Run your agent inside an isolated boxd microVM — with its own public HTTPS URL, cryptographic DID identity, and persistent state — without changing a single line of your agent script.

​
Action

​
1. Meet the requirements

  • A boxd account and credentials — bindu accepts either form (source):
  export BOXD_API_KEY="<your-key-from-boxd-dashboard>"
  # or, short-lived:
  export BOXD_TOKEN=$(boxd login --json | jq -r .token)
  • The boxd runtime extra for bindu:
  pip install 'bindu[runtime-boxd]'

​
2. Preview before you spend anything

bindu deploy agent.py --runtime=boxd --dry-run
Prints the target VM name, source root, entry script, resource config, env-var keys (values hidden), tarball file count and compressed size, and any sensitive files that would be silently dropped. No VM is touched.

​
3. Deploy

bindu deploy agent.py --runtime=boxd
That’s it. Same script you run locally, one flag, public URL.

​
4. Tune the deploy with CLI flags

FlagTypeDefaultMeaning
--runtimestrboxdRuntime provider.
--namestrfrom config["name"]Override the agent name (e.g. for preview envs).
--imagestrunsetA1 mode: boot from this Docker image instead of shipping source. See custom image.
--vcpuint2vCPUs for the VM.
--memorystr4GRAM. Accepts boxd size strings (512M, 4G, …).
--diskstr20GDisk size.
--auto-suspendint0 (disabled)Seconds of idle (no HTTP request) before boxd auto-suspends the VM. Off by default — bindu agents commonly run background work (scheduler ticks, streaming LLM calls, websockets) that would be frozen mid-flight. Pass --auto-suspend=60 only if your agent is pure request/response.
--on-exitstrsuspendBehaviour on Ctrl-C: suspend (call box.suspend()), destroy (tear down VM), detach (leave running).
--bindu-versionstrunsetPin the bindu version installed in the VM. local ships the host’s source instead of pulling from PyPI — useful for testing a patched bindu.
--envKEY=VALUE—Extra env var injected into the VM (repeatable).

​
5. Understand the lifecycle

  1. First run — bindu packages your project source, ships it to a fresh VM, runs pip install bindu plus your deps, starts your agent, and polls /health until ready. Cold path: ~10–30 seconds depending on dep weight.
  2. Subsequent runs (same agent name) — the CLI reuses the existing VM, updates source, restarts the agent. ~1–3 seconds.
  3. Ctrl-C with --on-exit=suspend (default) — the CLI calls box.suspend(), freezing the VM’s memory. DID keys, vector store, conversation history all survive. Re-running bindu deploy resumes in 1–3 seconds with state intact.
  4. --auto-suspend=N — while the agent is running, suspend after N seconds without an HTTP request. Avoid if the agent has scheduled tasks, streaming LLM calls, or websocket connections — those will be frozen mid-execution and most upstreams don’t tolerate resuming mid-RPC.

​
6. Pass secrets safely

The agent’s DID keys, x402 wallet, and OAuth tokens are generated and persisted inside the VM. BOXD_API_KEY / BOXD_TOKEN stays on your host and is never shipped. User secrets go in via --env: 
bindu deploy agent.py --runtime=boxd \
  --env OPENAI_API_KEY=sk-... \
  --env ANTHROPIC_API_KEY=sk-ant-...
The deploy CLI never ships secret-looking files. The exact patterns are defined in source_packager._SENSITIVE_PATTERNS:
TypePatterns (exact fnmatch)
Files.env, .env.*, *.pem, *.key, *.p12, *.pfx, *.kdbx, id_rsa, id_dsa, id_ecdsa, id_ed25519, credentials.json, credentials.yaml, credentials.yml, *.kubeconfig
Dirs (whole subtree excluded).aws/, .gnupg/, .ssh/, .bindu/
A warning lists what was dropped. Run --dry-run to see the full list before deploying.

​
7. Source packaging rules

Your project root is auto-discovered by walking up from the entry script looking for pyproject.toml, setup.py, requirements.txt, or .git (see find_project_root). The packager is inclusion-by-default: every file under the project root ships unless it matches an exclude rule. There is no allowlist of extensions — your .csv, .sql, .html, etc. all ship. Excluded by directory name (any path segment matches): __pycache__/, .git/, .venv/, venv/, node_modules/, .pytest_cache/, .mypy_cache/, .ruff_cache/ Excluded by suffix: .pyc, .pyo, .log, .sqlite, .db Also excluded: the sensitive patterns from Section 6, plus everything matched by .gitignore and .binduignore at the project root (same syntax as gitignore). Hard cap: 50 MB compressed. Bigger sources fail fast with a SourceTooLargeError pointing to .binduignore.

​
8. Dev tools while it’s running

CommandWhat it does
bindu logs <agent>Stream the agent’s stdout/stderr to your terminal. Reads /tmp/bindu-agent.log inside the VM via tail -F. Pass --no-follow to cat the file and exit.
bindu shell <agent>Open an interactive bash inside the VM as the boxd user. You land in /home/boxd; your shipped source is at /home/boxd/app.

​
Result

Your agent is live at https://<name>.boxd.sh — isolated, HTTPS, with a cryptographic identity and persistent state across suspends. You didn’t touch a server, write a Dockerfile, or manage TLS.

​
Troubleshooting

ProblemLikely causeFix
BOXD_API_KEY or BOXD_TOKEN must be set in the host environmentNo credentials in host envexport BOXD_API_KEY=<your-key> (or export BOXD_TOKEN=$(boxd login --json | jq -r .token))
script did not call bindufy()Entry script raised before reaching bindufy()Run python agent.py directly to see the underlying error
agent at <url> did not become healthy within 60sVM up but agent failed to startbindu logs <agent> — common causes: missing dep, syntax error, port 3773 already in use
pip install failureDep not on PyPI or native build failsSwitch to A1 mode and install the dep at image-build time
Source >50 MBLarge data files includedAdd them to .binduignore
Old bindu in VM rejects new featuresPublished bindu lags the host’sPass --bindu-version=local to ship host source instead
upload to /tmp/... corrupted after 3 attemptsboxd write_file truncation (boxd#45)Re-run bindu deploy — the corruption is intermittent and almost always clears on retry
Wrong code running after redeployboxd 0.1.x sometimes ships truncated tarballsThe deploy now sha256-verifies every upload and retries on mismatch. If it persists, run bindu shell <agent> and check cat /tmp/bindu-agent.pid against pgrep python3
Sunflower LogoRuntime with boxd - turn your agent into a web discoverable service.