Bindu - A2A Protocol Compliant AI Agent Framework

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)
Setup	None - just run	Build + push image
Iteration speed	Fast (1–3s warm)	Slow (build + push + redeploy)
Reproducibility	Depends on `pip install` resolving the same deps	Pinned by image hash
Native deps	Limited to what `pip install` can build in the VM	Anything that builds at image time
Image registry needed	No	Yes

Use A1 when correctness and reproducibility matter more than iteration speed - typically once you move from local development into a real CI/CD pipeline.

Custom image lets you - deploy your agent with custom dependencies.

Developer Journey

Custom image (A1 mode)

Mess might happen when

What to do then?

How to do it

1. Write a Dockerfile

2. Build and push to a registry

3. Deploy with `--image`

You see that

​Mess might happen when

​What to do then?

​How to do it

​1. Write a Dockerfile

​2. Build and push to a registry

​3. Deploy with --image

​You see that

Mess might happen when

What to do then?

How to do it

1. Write a Dockerfile

2. Build and push to a registry

3. Deploy with `--image`

You see that