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.

​
Mess might happen when

Some agents can’t rely on a plain pip install at deploy time:
  • Native deps that require a Rust toolchain or system libraries.
  • CI/CD pipelines that already produce container images.
  • Teams that need pinned, auditable, reproducible deploys.
If any of these apply, the default A2 source-mount mode isn’t enough. You need full control over the environment your agent runs in.

​
What to do then?

Get bindu to boot your agent from a Docker image you built and pushed, instead of packaging your source folder and running pip install inside the VM.

​
How to do it

​
1. Write a Dockerfile

Your image must start an agent that listens on 0.0.0.0:3773 — that’s the port bindu’s boxd proxy forwards public HTTPS traffic to (see BINDU_DEFAULT_PORT). You can either run the script directly or use the bindu serve --script shim (both end up calling bindufy() inside your file): 
FROM python:3.12-slim

# Install bindu + your deps
WORKDIR /app
COPY pyproject.toml requirements*.txt ./
RUN pip install bindu
RUN pip install -r requirements.txt    # or: pip install -e .

# Copy your agent code
COPY . /app

# Make sure your bindufy() config binds 0.0.0.0:3773. Then either:
CMD ["python3", "/app/my_agent.py"]
# ...or via the CLI shim (equivalent):
# CMD ["bindu", "serve", "--script", "/app/my_agent.py"]

​
2. Build and push to a registry

Push to any public registry, or a private one with credentials configured on your boxd account (e.g. ghcr.io, Docker Hub, ECR).

​
3. Deploy with --image

bindu deploy my_agent.py \
    --runtime=boxd \
    --image=ghcr.io/me/my-agent:v1.2.0
When --image is set, bindu changes its behaviour (deploy() source):
  • No source upload — your folder stays on your machine.
  • No pip install step — deps are already baked into the image.
  • Image CMD is the entrypoint — whatever you put in CMD starts the agent. Bindu does not exec into the container after creation; it only waits for GET /health on port 3773.
  • --env is not injected. A2 source mode merges --env flags into the agent process at start time, but the A1 branch skips _start_agent entirely — env values currently never reach your container. Bake required env into the image, or read them from a secret store inside the agent. Tracked as a known gap; once fixed this section will move to “everything else is identical.”
Everything else — health checks, log streaming via /tmp/bindu-agent.log, on-exit lifecycle — works as in A2, provided your image writes its stdout/stderr to /tmp/bindu-agent.log if you want bindu logs <agent> to work. (The default A2 mode does this for you via shell redirection; A1 images have to opt in.)

​
You see that

Your agent boots from a pinned, reproducible image with full control over every system dependency. Here’s how that compares to the default A2 mode:
A2 (source mount)A1 (custom image)
SetupNone - just runBuild + push image
Iteration speedFast (1–3s warm)Slow (build + push + redeploy)
ReproducibilityDepends on pip install resolving the same depsPinned by image hash
Native depsLimited to what pip install can build in the VMAnything that builds at image time
Image registry neededNoYes
Use A1 when correctness and reproducibility matter more than iteration speed - typically once you move from local development into a real CI/CD pipeline. Sunflower LogoCustom image lets you - deploy your agent with custom dependencies.