Skip to main content
This page gets the Engine running on your machine, end to end, in development mode. By the end you’ll have:
  • An Engine process listening on port 8000.
  • A brain database with all migrations applied.
  • A passing /health check.
  • Your first successful /execute call.
If anything below doesn’t work for you, see Troubleshooting.

​
Prerequisites

You need:
  • Docker (for docker compose). Tested with Docker Desktop 4.x and Docker CE 24+.
  • Git.
  • An API key for at least one LLM provider (Anthropic, OpenAI, or Gemini) plus an OpenAI key for embeddings.
You do not need Python locally. The Engine runs inside a Docker container.

​
Step 1 — Clone the repo

cd ~/work
git clone git@github.com:septemberai/engine.git
cd engine
If you don’t have repo access yet, request it before continuing.

​
Step 2 — Configure your environment

Copy the example env file: 
cp .env.example .env
Open .env and set, at minimum: 
# Pick one chat provider and set its key + model.
LLM_PROVIDER=anthropic
LLM_API_KEY=sk-ant-...
LLM_MODEL=claude-sonnet-4-5

# Embeddings always route to OpenAI today.
OPENAI_API_KEY=sk-...

# Set a development API key for the Engine itself.
ENGINE_API_KEY=dev-engine-key
For the full list of variables, see Environment variables.

​
Step 3 — Start the Engine

From the engine repo root: 
docker compose up engine
The first run pulls and builds the image, applies migrations, and starts Uvicorn. You’ll see something like: 
engine    | INFO:     Uvicorn running on http://0.0.0.0:8000
engine    | INFO:     Application startup complete.
Leave it running. Open a second terminal for the next steps.

​
Step 4 — Confirm it’s alive

curl -fsS http://localhost:8000/health
You should see: 
{
  "status": "ok",
  "uptime_seconds": 5.2,
  "subsystems": { ... }
}
The /health endpoint is the only route that does not require an API key. Every other endpoint requires X-Engine-Key.

​
Step 5 — Send your first request

Set your dev key as an environment variable for convenience: 
export ENGINE_KEY=dev-engine-key
Now make an /execute call: 
curl -N -X POST http://localhost:8000/execute \
  -H "Content-Type: application/json" \
  -H "X-Engine-Key: $ENGINE_KEY" \
  -d '{"message": "Say hello in one short sentence.", "task_id": "demo-001"}'
-N disables curl’s buffering so you see the SSE stream as it arrives. You should see a series of events, ending with the model’s response.

​
Step 6 — Watch the brain fill up

The brain database lives at /data/brain.sqlite inside the container. To look at it from the host: 
docker compose exec engine sqlite3 /data/brain.sqlite '.tables'
You should see all the tables the migrations created — episodes, knowledge_store, social_graph_nodes, working_memory_log, and so on. After a few /execute calls, the working memory and trajectory tables will have rows.

​
Step 7 — Run the tests

The engine repo includes a test target in docker-compose: 
docker compose run --rm test pytest tests/ --tb=short
Tests run inside a privileged container so the sandbox can use bubblewrap. Expect this to take a few minutes the first time.

​
What’s next

​
Tearing it down

docker compose down
To wipe the brain database too: 
docker compose down --volumes
That removes the engine_data volume, which holds the SQLite file. Use it when you want to start completely fresh.