Quick Start

Get SyntheticBrew 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.

Recommended

The fastest path is to let your coding agent (Claude Code, Cursor, VS Code, OpenAI Codex) do the setup for you via our MCP server — it provisions a ready-to-chat agent and hands you the embed snippet, no YAML and no dashboard clicks. See Install via Coding Agent (MCP). Prefer to set things up by hand? Continue with the Docker steps below.

Prerequisites

You need docker and docker compose installed. SyntheticBrew 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.

curl -fsSL https://syntheticbrew.ai/releases/docker-compose.yml -o docker-compose.yml

Create a .env file in the same directory:

.env

SYNTHETICBREW_AUTH_MODE=local
LLM_API_KEY=sk-your-key
POSTGRES_PASSWORD=syntheticbrew

docker compose up -d

This spins up three containers: the SyntheticBrew Engine, a PostgreSQL database, and the db-migrate service that runs schema migrations. The engine starts on port 8443 — both the REST API and the Admin Dashboard are served on this single port. Verify it is running:

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

Open the Admin Dashboard in your browser at http://localhost:8443/admin. In the default local auth mode the engine mints a short-lived admin session for you automatically — there is no login form and no password to set. You land straight in the dashboard.

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 and models:

agents.yaml

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

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

Available built-in tools

show_structured_output emits structured data or form questions to the user (non-blocking). knowledge_search requires a knowledge: path in the agent config — see Knowledge / RAG. Web search is available via MCP servers (Tavily, Brave, Exa) — add them in Admin Dashboard → MCP Servers.

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.

Embeddable chat widget

To embed a chat interface on any web page, use the embeddable widget served by the engine at /widget.js. The fastest way to generate a ready-to-paste <script> tag is the Connect a Coding Agent flow; see also the examples repo.

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

Before sending messages, enable chat on your schema in the Admin Dashboard: open Schemas, select your schema, toggle Chat Enabled to on, and save. Then get the schema ID from the URL or the schemas list.

You also need an API token for the Authorization header below. Mint one in the Admin Dashboard under API Keys → Generate New Token (a chat scope is enough for this call); the full bb_… value is shown once, so copy it immediately. For automated/headless setups you can instead set SYNTHETICBREW_BOOTSTRAP_ADMIN_TOKEN at boot.

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_api_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: message
data: {"content":"Hello! I'm your product assistant. I can help you with product questions, 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_api_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. Log in with the admin credentials you created in Step 1. From the dashboard you can manage agents, models, schemas, MCP servers, and API keys — all without editing YAML.

---

Connect your AI assistant

SyntheticBrew provides an MCP server with full documentation search. Connect it to your AI coding assistant for instant answers.

This section covers the public docs-search MCP server (a single search_docs tool, no account needed) — it is distinct from the engine’s provisioning MCP server described in Install via Coding Agent (MCP).

Claude Code

claude mcp add syntheticbrew-docs --transport sse https://mcp.syntheticbrew.ai/sse

Other MCP clients

SSE endpoint: https://mcp.syntheticbrew.ai/sse — use with Cursor, Windsurf, or any MCP client that supports SSE transport.

Tip

After connecting, ask questions like “How do I configure multi-agent spawn?” or “What SSE event types does the chat API return?” — your assistant will search our documentation automatically.

---

What’s next

• Configuration Reference
• API Reference
• Bootstrap & GitOps — deploy a fully-configured installation from a git repository
• Core Concepts: Agents
• Core Concepts: Schemas