Getting Started

This guide is the fastest path from a fresh checkout to a working AGENT-33 demo.

What you will do

Start the runtime with Docker Compose
Verify health
Sign in to the control plane
Mint a JWT for API access
List agents
Invoke one agent

Prerequisites

Docker Desktop or Docker Engine with Compose
Python 3.11+
curl
Ollama reachable from the stack, or one of the documented Ollama override modes

1. Configure the environment

From repo root:

cd engine
cp .env.example .env

For local-only setup, the defaults are acceptable. For anything beyond local development, change at least:

API_SECRET_KEY
JWT_SECRET
ENCRYPTION_KEY
AUTH_BOOTSTRAP_ENABLED

Docker Compose reads .env. The bootstrap/wizard path writes .env.local for local CLI/runtime usage and does not replace the Compose config file.

2. Start the stack

cd engine
docker compose up -d

By default, engine/.env points OLLAMA_BASE_URL at http://host.docker.internal:11434 so the stack can reuse a host/shared Ollama daemon. If you want the repo-managed Ollama container instead, use the bundled profile below and set OLLAMA_BASE_URL=http://ollama:11434 in engine/.env first.

Alternative startup modes:

shared Ollama network:

docker compose -f docker-compose.yml -f docker-compose.shared-ollama.yml up -d

bundled Ollama profile:

# set OLLAMA_BASE_URL=http://ollama:11434 in .env first
docker compose --profile local-ollama up -d

dev container with tooling:

docker compose --profile dev up -d devbox

3. Verify runtime health

curl http://localhost:8000/health

You should see service health information for the runtime and its dependencies.

4. Open the control plane

Frontend: http://localhost:3000
API docs: http://localhost:8000/docs

Default local credentials:

username: admin
password: admin

5. Create a local JWT for API calls

docker compose exec -T api python -c "import os,time,jwt; now=int(time.time()); payload={'sub':'local-admin','scopes':['admin','agents:read','agents:write','agents:invoke','workflows:read','workflows:write','workflows:execute','tools:execute'],'iat':now,'exp':now+3600}; print(jwt.encode(payload, os.getenv('JWT_SECRET','change-me-in-production'), algorithm=os.getenv('JWT_ALGORITHM','HS256')))"

Set the token:

export TOKEN="<paste-token-here>"

PowerShell:

$env:TOKEN = "<paste-token-here>"

6. List agents

curl http://localhost:8000/v1/agents/ \
  -H "Authorization: Bearer $TOKEN"

7. Invoke the orchestrator

curl -X POST http://localhost:8000/v1/agents/orchestrator/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "task": "Create a short checklist for verifying a local AGENT-33 deployment"
    },
    "model": "llama3.2:3b",
    "temperature": 0.2
  }'

8. Optional next steps

Continue with Walkthroughs
Read Operator Onboarding
Review the API Surface
Use the Release Checklist before any non-local deployment

Important security note

The bootstrap login and default secrets in .env.example are not safe for public exposure.

Before shared or production use:

set AUTH_BOOTSTRAP_ENABLED=false
rotate all default secrets
read SECURITY.md
follow the Release Checklist

getting-started