> ## 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.

# Deployment overview

> How the Engine deploys, and which topology matches your needs.

The Engine deploys as a single process backed by a single SQLite database.
It's small, has few moving parts, and is easy to run alone. The
complexity in production comes from running many of them.

## Topologies

### Single-node (laptop / single user)

One Engine process. One brain file. One LLM provider key. Used for local
development and for solo users who run their own Engine.

```mermaid theme={null}
flowchart LR
    Client["client"]
    Engine["engine<br/>(uvicorn)"]
    Brain[("brain.sqlite")]
    LLM["LLM provider"]
    Client --> Engine --> Brain
    Engine --> LLM
```

This is what `docker compose up engine` gives you. See
[Local development quickstart](../local-dev/quickstart).

### Hosted, per-user

A control plane upstream (BAP — the public product's backend) holds user
accounts and routes each request to the right Engine. Each Engine
instance owns one user's brain.

```mermaid theme={null}
flowchart LR
    User["user"]
    BAP["BAP router"]
    EA["engine A"]
    EB["engine B"]
    EC["engine C"]
    BA[("brain_user_a.sqlite")]
    BB[("brain_user_b.sqlite")]
    BC[("brain_user_c.sqlite")]
    LLM["LLM provider"]
    User --> BAP
    BAP --> EA --> BA
    BAP --> EB --> BB
    BAP --> EC --> BC
    EA --> LLM
    EB --> LLM
    EC --> LLM
```

Engine instances are interchangeable — you can lose one and bring up
another against the same brain. They start in seconds.

### Orchestrated (in production)

A separate orchestrator — bap-engine — provisions, health-checks, and
manages a fleet of Engine workers. Adds policy, quotas, and lifecycle
management on top of the per-user model. See
[BAP Engine](../../bap-engine/overview) for the full docs; source at
[bap-engine](https://github.com/septemberai/bap-engine).

## What you need

For a production deployment, you need:

* A container runtime that can run the Engine's image. The image is
  built from the Engine repo's `Dockerfile`.
* Persistent storage for the brain SQLite file (e.g. an EBS volume,
  a Kubernetes PVC).
* LLM provider credentials (one provider for chat, OpenAI for embeddings).
* An `AD_ENCRYPTION_KEY` if you'll use any MCP connectors.
* A public URL with HTTPS termination upstream of the Engine.
* An API key (or hash) for the Engine itself.

## What you don't need

* A queue, broker, or message bus. The Engine is in-process.
* A separate database service. SQLite is the only durable store.
* A Redis or cache layer. The Engine handles its own caching.
* A separate worker pool. The Learning Centre runs in-process on a
  schedule.

## Hardening checklist

Before any production deploy:

* [ ] `ENGINE_KEY_HASH` set, plaintext key not in the Engine environment.
* [ ] `AD_ENCRYPTION_KEY` set if any MCP connectors will be used.
* [ ] HTTPS terminating upstream of the Engine.
* [ ] `CORS_ORIGINS` restricted to your application domains, not `*`.
* [ ] `ASSET_DIRECTORY_SANDBOXED=true`.
* [ ] `SUBPROCESS_SCRUB_MODE=strict` for production.
* [ ] `ENGINE_LOG_LEVEL=INFO` (not `DEBUG`).
* [ ] Brain volume backed up on a schedule.
* [ ] Health probe configured against `/health`.
* [ ] Log shipping configured.
* [ ] Migrations strategy decided (auto-run on boot vs. gate by ops).

## Where to go next

* [Production deploy](./prod-deploy) — step by step.
* [Upgrade](./upgrade) — moving between versions.
* [Rollback](./rollback) — undoing a bad deploy.
* [Threat model](../security/threat-model) — what your hardening is
  defending against.