Skip to main content
A growing collection of commands you’ll reach for repeatedly when developing against a local Engine. Copy-paste-friendly. All examples assume: 
export ENGINE_URL=http://localhost:8000
export ENGINE_KEY=dev-engine-key

​
Engine lifecycle

​
Start

docker compose up engine

​
Start in background

docker compose up -d engine

​
Stop

docker compose down

​
Stop and wipe the brain

docker compose down --volumes
The --volumes flag removes the engine_data Docker volume — the brain SQLite file and everything in it. Use this for a clean slate.

​
Rebuild after code changes

docker compose build engine && docker compose up engine

​
Tail logs

docker compose logs -f engine

​
Brain inspection

​
List tables

docker compose exec engine sqlite3 /data/brain.sqlite '.tables'

​
Count rows in a table

docker compose exec engine sqlite3 /data/brain.sqlite \
  'SELECT COUNT(*) FROM episodes'

​
Browse recent episodes

docker compose exec engine sqlite3 -header -column /data/brain.sqlite \
  'SELECT id, key, description, created_at FROM episodes
   ORDER BY created_at DESC LIMIT 10'

​
Browse recent trajectories

docker compose exec engine sqlite3 -header -column /data/brain.sqlite \
  'SELECT id, thread_id, task_id, created_at FROM trajectories
   ORDER BY created_at DESC LIMIT 5'

​
Reset memory (keep schema)

docker compose exec engine sqlite3 /data/brain.sqlite \
  'DELETE FROM episodes; DELETE FROM knowledge_store;
   DELETE FROM social_graph_nodes; DELETE FROM working_memory_log;
   DELETE FROM trajectories;'
This wipes memory but keeps the schema and migrations applied. Faster than rebuilding the volume.

​
Configuration changes

​
Edit env, restart

$EDITOR .env
docker compose up -d engine  # picks up the new .env
If you set environment variables inline (not in .env), you’ll need to recreate the container: 
ENGINE_LOG_LEVEL=DEBUG docker compose up -d engine

​
Reload the catalog without restart

curl -X POST "$ENGINE_URL/admin/reload-catalog" \
  -H "X-Engine-Key: $ENGINE_KEY"
Use after editing agent definitions, skill definitions, or tool entries in catalog/.

​
Reload the soul template

curl -X POST "$ENGINE_URL/admin/reload-core-soul" \
  -H "X-Engine-Key: $ENGINE_KEY"

​
Quick API tests

​
Health check

curl -fsS "$ENGINE_URL/health" | jq

​
One-shot execute

curl -N -X POST "$ENGINE_URL/execute" \
  -H "X-Engine-Key: $ENGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Say hi.","task_id":"smoke-1"}'

​
List MCP servers

curl -fsS "$ENGINE_URL/assets/servers" \
  -H "X-Engine-Key: $ENGINE_KEY" | jq

​
Search knowledge

curl -fsS -X POST "$ENGINE_URL/memory/knowledge/search" \
  -H "X-Engine-Key: $ENGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"prefer","limit":5}' | jq

​
Trigger a Learning Centre batch

curl -X POST "$ENGINE_URL/admin/lc/trigger" \
  -H "X-Engine-Key: $ENGINE_KEY"
Useful when you want trajectories from recent dev runs to consolidate into long-term memory immediately.

​
Tests

​
Run the full test suite

docker compose run --rm test pytest tests/ --tb=short

​
Run one test file

docker compose run --rm test pytest tests/test_agent_loop.py --tb=short

​
Run one test by name

docker compose run --rm test pytest -k test_compaction_handles_overflow

​
Run with verbose output

docker compose run --rm test pytest tests/ -vv

​
Switching configurations

​
Switch LLM provider

In .env: 
LLM_PROVIDER=openai
LLM_API_KEY=sk-...
LLM_MODEL=gpt-5.4
OPENAI_API_KEY=sk-...
Then docker compose up -d engine.

​
Use a smaller model for development

Set in .env: 
LLM_MODEL=claude-haiku-4-5-20251001
Cheaper and faster for iteration. Ship with the production model.

​
Disable a feature flag

REACTIVE_COMPACT_ENABLED=false
Don’t forget the values are "true"/"false" strings, not booleans.

​
Dev shortcuts

​
Watch logs filtered by task

docker compose logs -f engine | grep task-001

​
See requests in real time with low log level

ENGINE_LOG_LEVEL=DEBUG docker compose up engine
DEBUG logs include MCP traces, model parameters, and context-assembly steps. Noisy but useful when investigating a specific call.

​
Curl with pretty SSE

curl -N -X POST "$ENGINE_URL/execute" \
  -H "X-Engine-Key: $ENGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"hi","task_id":"demo"}' \
  | grep -E '^(event|data):' \
  | sed 's/^data: //'

​
See also