Quick Start

Get ByteBrew Engine running with Docker in under 5 minutes. By the end of this guide, you will have a working AI agent that responds to messages over a REST API.

Prerequisites

You need docker and docker compose installed. ByteBrew Engine runs on Linux, macOS, and Windows (WSL2). Minimum 2 GB RAM for the engine + PostgreSQL.

Step 1: Start the Engine

Download the Docker Compose file and start the engine. This spins up two containers: the ByteBrew Engine and a PostgreSQL database.

curl -fsSL https://bytebrew.ai/releases/docker-compose.yml -o docker-compose.yml
docker compose up -d

The engine starts on port 8443 — both the REST API and Admin Dashboard. Verify it is running:

curl http://localhost:8443/api/v1/health
# {"status":"ok","version":"1.0.0","agents_count":0}

Step 2: Create your first agent

Create an agents.yaml file in the same directory as your docker-compose.yml. This file defines your agents, models, and tools:

agents.yaml

agents:
  my-agent:
    model: glm-5
    system: "You are a helpful assistant for our product."
    tools:
      - knowledge_search

models:
  glm-5:
    provider: openai
    api_key: ${OPENAI_API_KEY}

Environment variables

The ${OPENAI_API_KEY} syntax references an environment variable. Set it in your shell (export OPENAI_API_KEY=sk-...) or in a .env file next to docker-compose.yml. Never hardcode secrets in YAML.

Prefer a visual editor?

Skip the YAML file and use the Admin Dashboard instead. Open http://localhost:8443/admin, log in, and click Create Agent. The dashboard lets you configure everything visually — model, system prompt, tools, security zones, spawn rules, and more.

Step 3: Send your first message

Use the REST API to talk to your agent. The response streams back as Server-Sent Events (SSE), so you see tokens as they are generated:

curl -N http://localhost:8443/api/v1/schemas/{schema_id}/chat \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, what can you do?"}'

Step 4: See the response

The engine returns a stream of SSE events. Each event has a type field that tells you what kind of data it contains:

event: message_delta
data: {"content":"Hello! I'm your product assistant. "}

event: message_delta
data: {"content":"I can help you with product questions, "}

event: message_delta
data: {"content":"documentation search, and more."}

event: done
data: {"session_id":"a1b2c3d4"}

The session_id in the done event lets you continue the conversation. Pass it in subsequent requests to maintain context:

curl -N http://localhost:8443/api/v1/schemas/{schema_id}/chat \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{"message": "Tell me more about that", "session_id": "a1b2c3d4"}'

Step 5: Open the Admin Dashboard

Navigate to http://localhost:8443/admin in your browser to manage agents, models, schemas, and MCP servers through a visual interface. Log in with the admin credentials you created via the CLI.

---

What’s next

Configuration Reference YAML reference for agents, models, tools, MCP servers, and triggers.

API Reference All REST API endpoints with curl examples.

Multi-Agent Orchestration Build teams of specialized agents.

Schemas Group agents into deployable units with chat enabled.