Quick Start

Get up and running with Capsule Agents in just a few minutes using Docker.

What is Capsule Agents?

Capsule Agents is a framework for creating containerized AI agents that are natively compatible with the Agent-to-Agent (A2A) protocol. It enables you to build powerful agents with:

No-code configuration - Create agents using YAML files or the built-in GUI
Full shell environments - Agents can execute commands and use CLI tools
A2A protocol support - Connect and orchestrate multiple agents
Remote MCP integration - Access Model Context Protocol servers
Containerized state - Each agent has isolated workspace and database

Prerequisites

You only need Docker installed on your system.

Quick Start with Docker

1. Create Environment File

Create a .env file with your AI provider API key. You need at least one provider key and an admin password for the editor/API:

# Choose at least one provider
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
GOOGLE_GENERATIVE_AI_API_KEY=your-google-key

# Required: Basic auth for the editor + API (username is "admin")
ADMIN_PASSWORD=your-secure-password

# Required: Public URL the agent advertises for A2A
AGENT_URL=http://localhost:8080

2. Run the Container

docker run \
  --env-file .env \
  -e AGENT_URL=http://localhost:8080 \
  -p 8080:9000 \
  -it brycewcole/capsule-agents:latest

3. Access Your Agent

Once the container starts, you can access:

Editor UI (chat + config): http://localhost:8080/editor
A2A endpoint (JSON-RPC): http://localhost:8080/
A2A Agent Card: http://localhost:8080/.well-known/agent.json
A2A Agent Card (alias): http://localhost:8080/.well-known/agent-card.json

That’s it! Your agent is now running and ready to use.

Customizing Your Agent

Using the Configuration UI

Open http://localhost:8080/editor and log in as admin
Modify your agent’s:
- Name and description
- AI model and parameters
- Built-in tools (exec, file operations, memory)
- System prompts
Click “Save” to apply changes

Using a Configuration File

Create an agent.config.yaml file:

agent:
  name: My Custom Agent
  description: A helpful assistant for specific tasks

  model:
    name: openai/gpt-5-mini
    parameters:
      temperature: 0.7
      max_tokens: 4000

  tools:
    exec:
      enabled: true
    memory:
      enabled: false
    read_file:
      enabled: true
    grep_files:
      enabled: true
    edit_file:
      enabled: true

Run with your custom config:

docker run \
  --env-file .env \
  -e AGENT_URL=http://localhost:8080 \
  -p 8080:9000 \
  -v $(pwd)/agent.config.yaml:/app/agent.config.yaml \
  -it brycewcole/capsule-agents:latest

Next Steps

Learn about advanced configuration options
Explore the examples directory for:
- Basic single-agent setups
- MCP server integration (Context7 + GitHub)
- Multi-agent deployments
- Development environment with observability

Development Setup

For local development with hot reload:

# Clone the repository
git clone https://github.com/brycewcole/capsule-agents.git
cd capsule-agents/examples/development-setup

# Start the development environment
docker-compose up

This includes:

Backend with hot reload
Grafana for observability (port 3000)
OpenTelemetry stack (Tempo, Prometheus, Loki)

Troubleshooting

Container won’t start

Ensure Docker is running
Check that port 8080 is not already in use
Verify your API keys are correct in the .env file

Agent not responding

Check container logs: docker logs <container-id>
Verify at least one AI provider API key is set
Ensure the model name is correct (e.g., openai/gpt-5-mini)

Configuration changes not applying

Restart the container after modifying agent.config.yaml
Check logs for configuration validation errors
Ensure YAML syntax is valid