> ## Documentation Index
> Fetch the complete documentation index at: https://internal.september.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Local development quickstart

> Run the Engine on your laptop in under fifteen minutes.

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](./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

```bash theme={null}
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:

```bash theme={null}
cp .env.example .env
```

Open `.env` and set, at minimum:

```bash theme={null}
# 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](../config/env-vars).

## Step 3 — Start the Engine

From the engine repo root:

```bash theme={null}
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

```bash theme={null}
curl -fsS http://localhost:8000/health
```

You should see:

```json theme={null}
{
  "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:

```bash theme={null}
export ENGINE_KEY=dev-engine-key
```

Now make an `/execute` call:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

* [Common tasks](./common-tasks) — reset the database, seed memory, swap
  models, run a single test.
* [Quickstart in Python](../../platform/get-started/quickstart-python) —
  same first-request flow using the Python client.
* [Architecture overview](../../internal/architecture/overview) — what's
  actually running inside the container you just started.

## Tearing it down

```bash theme={null}
docker compose down
```

To wipe the brain database too:

```bash theme={null}
docker compose down --volumes
```

That removes the `engine_data` volume, which holds the SQLite file. Use it
when you want to start completely fresh.