Skip to main content
Complete guide to deploying your Bindu agent. We’ll walk you through everything you need to get your agent running in production!

​
What You’ll Need

Before we start deploying your awesome agent, make sure you have these tools ready:
  • 🐳 Docker & Docker Compose - For containerization and orchestration
  • 🐍 Python 3.12+ - For local development and testing
  • ⚡ uv package manager - Fast dependency management
  • 🔑 API Keys - Your .env file with all required credentials
Don’t have these yet? No worries! We’ll guide you through each setup step.

​
Setting Up Your Environment

Let’s get your environment configured for success!

​
Configure Your API Keys

First, copy the example environment file: 
cp .env.example .env
Now, open .env and add your secret API keys: 
# OpenRouter API Configuration
OPENROUTER_API_KEY=your_openrouter_api_key_here

# Get your API key from: https://openrouter.ai/keys
Security First! Never commit your .env file to version control. It’s already included in .gitignore to keep your secrets safe.

​
🐳 Docker Deployment Made Easy

Ready to deploy? Your agent comes with a complete Docker Compose setup that handles everything:
  • 🚀 Main Agent Service - Your awesome Bindu agent with health checks and monitoring
  • ⚙️ Smart Environment Support - Storage, scheduler, telemetry, and more
  • 🌐 Production-Ready Networking - Isolated networks and proper port mapping

​
Your Docker Compose Configuration

Here’s what your docker-compose.yml file looks like (using placeholders for your project): 
services:
  {{project_name}}:
    build:
      context: .
      dockerfile: Dockerfile.agent
    container_name: {{project_name}}
    ports:
      - "3773:3773"
    environment:
      # OpenRouter API Configuration
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}

      # Mem0 Memory Configuration
      - MEM0_API_KEY=${MEM0_API_KEY}

      # Database Configuration
      - STORAGE_TYPE=${STORAGE_TYPE:-memory}
      - DATABASE_URL=${DATABASE_URL}

      # Redis Scheduler Configuration
      - SCHEDULER_TYPE=${SCHEDULER_TYPE:-memory}
      - REDIS_URL=${REDIS_URL}

      # Sentry Error Tracking
      - SENTRY_ENABLED=${SENTRY_ENABLED:-false}
      - SENTRY_DSN=${SENTRY_DSN}

      # Telemetry & Observability
      - TELEMETRY_ENABLED=${TELEMETRY_ENABLED:-false}
      - OLTP_VERBOSE_LOGGING=${OLTP_VERBOSE_LOGGING:-false}
      - OLTP_ENDPOINT=${OLTP_ENDPOINT}
      - OLTP_SERVICE_NAME=${OLTP_SERVICE_NAME:-{{project_name}}}
      - OLTP_HEADERS=${OLTP_HEADERS}
    env_file:
      - .env
    restart: unless-stopped
    networks:
      - {{project_name}}-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3773/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

networks:
  {{project_name}}-network:
    driver: bridge

​
🎮 Docker Commands You’ll Use

Ready to get your agent running? Here are the essential commands:
1

🚀 Build & Start

Fire up your agent with all services:
docker-compose up --build
Want it running in the background? Use detached mode:
docker-compose up -d --build
2

📋 View Logs

Keep an eye on what’s happening:View logs from all services:
docker-compose logs -f
Focus on your specific service:
docker-compose logs -f {{project_name}}
3

🛑 Stop Services

Time to shut things down:
docker-compose down
Want to clear everything (including data)?
docker-compose down -v
4

🔄 Quick Restart

Need to restart your agent?
docker-compose restart
Restart just your agent:
docker-compose restart {{project_name}}

​
Access Your Services

Once deployed, access your services at:

Agent API

Your Bindu agent endpoint

Jaeger UI

Distributed tracing dashboard

Phoenix UI

LLM observability dashboard

​
Makefile Commands

Your agent includes a Makefile with common development tasks. Use make help to see all available commands.

​
Development Commands

Install the virtual environment and pre-commit hooks:
make install
This command:
  • Creates a virtual environment using uv
  • Installs all dependencies
  • Sets up pre-commit hooks for code quality
Run all code quality checks:
make check
This command runs:
  • Lock file consistency check
  • Pre-commit hooks (linting, formatting)
  • Static type checking with ty
  • Dependency analysis with deptry
Run tests with coverage:
make test
This command:
  • Runs pytest with coverage reporting
  • Generates XML coverage report
  • Uses configuration from pyproject.toml
Build wheel distribution file:
make build
This command:
  • Cleans previous build artifacts
  • Creates a new wheel file in dist/
  • Uses uv as the installer
Build and serve documentation:
make docs
This starts a local documentation server. Access it at http://localhost:8000To test documentation build without serving:
make docs-test
Clean build artifacts:
make clean-build
Removes the dist/ directory and all build artifacts.
Display all available commands:
make help
Shows a formatted list of all Makefile targets with descriptions.

​
Dockerfile Overview

The Dockerfile uses a modern multi-stage approach optimized for Python 3.12 and uv: 
# Dockerfile.agent
# Multi-stage build for a Bindu agent ({{project_name}} example).
# Builder: python:3.12-bookworm + uv
# Runtime: bindu-runtime-base

# ---------- Builder stage ----------
FROM python:3.12-bookworm AS builder

# Install uv once in builder (no need in runtime)
RUN pip install --no-cache-dir uv

ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
WORKDIR /app

# 1) Install dependencies into .venv (lockfile + pyproject)
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-install-project --no-dev

# 2) Copy agent code
COPY {{project_name}}/ /app/{{project_name}}/
COPY *.py /app/
COPY README.md /app/

# 3) Install project itself into the same venv
RUN uv sync --frozen --no-dev

# ---------- Runtime stage ----------
FROM raahulrahl/bindu-runtime-base:latest

# OCI labels
LABEL org.opencontainers.image.title="{{project_name}}-agent"
LABEL org.opencontainers.image.description="A Bindu AI agent for intelligent task handling"
LABEL org.opencontainers.image.authors="{{author}} <{{email}}>"
LABEL org.opencontainers.image.version="{{agent_version}}"
LABEL org.opencontainers.image.source="https://github.com/{{author_github_handle}}/{{project_name}}"
LABEL org.opencontainers.image.licenses="{{open_source_license}}"

# Copy app + venv from builder
COPY --from=builder /app /app

# Use the agent venv Python by default
ENV PATH="/app/.venv/bin:$PATH"

WORKDIR /app
EXPOSE 3773

CMD ["python", "-m", "{{project_name}}"]

​
Key Features

  • Multi-Stage Build - Separates build and runtime environments for optimal size and security
  • Bindu Runtime Base - Uses raahulrahl/bindu-runtime-base:latest for production-ready runtime
  • UV Package Manager - Fast dependency resolution and installation with bytecode compilation
  • Frozen Dependencies - Ensures reproducible builds with --frozen flag
  • OCI Labels - Complete container metadata for better container management
  • Optimized Layers - Dependencies installed before code copy for faster rebuilds
  • Production Ready - Health checks, proper networking, and environment configuration

​
Deployment Workflows

​
Local Development

1

Install Dependencies

make install
2

Run Quality Checks

make check
3

Run Tests

make test
4

Start Agent Locally

uv run python -m {{project_name}}.main

​
Docker Development

1

Configure Environment

cp .env.example .env
# Edit .env with your API keys
2

Build and Run

docker-compose up --build
3

Monitor Logs

docker-compose logs -f {{project_name}}
4

Test Agent

Access your agent at http://localhost:3773

​
Production Deployment

1

Build Production Image

docker build -t {{project_name}}:latest .
2

Tag for Registry

docker tag {{project_name}}:latest your-registry/{{project_name}}:latest
3

Push to Registry

docker push your-registry/{{project_name}}:latest
4

Deploy to Production

Use your preferred orchestration platform (Kubernetes, ECS, etc.)

​
Monitoring and Observability

​
Jaeger Tracing

Access Jaeger UI at http://localhost:16686 to:
  • View distributed traces across your agent
  • Analyze request latency and performance
  • Debug issues with detailed span information
  • Monitor service dependencies

​
Phoenix LLM Observability

Access Phoenix UI at http://localhost:6006 to:
  • Track LLM calls and token usage
  • Analyze prompt and response quality
  • Monitor model performance metrics
  • Debug LLM-specific issues
Phoenix uses the OpenInference standard, which is compatible with many observability providers.

​
Troubleshooting

​
Common Issues

If you see port conflict errors:
# Check what's using the port
lsof -i :3773

# Kill the process or change the port in docker-compose.yml
Ensure your .env file exists and is in the project root:
# Verify .env file exists
ls -la .env

# Check environment variables are loaded
docker-compose config
Clear Docker cache and rebuild:
docker-compose down -v
docker system prune -a
docker-compose up --build
Check agent logs for errors:
docker-compose logs -f {{project_name}}
Verify the agent is healthy:
docker-compose ps
curl http://localhost:3773/health

​
Next Steps

Configure Agent

Customize your agent’s behavior and capabilities

Learn Observability

Deep dive into monitoring and debugging

Join Community

Connect with other agent developers

Get Help

Find support and resources