Skip to main content

Documentation Index

Fetch the complete documentation index at: https://septemberai.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The Engine is single-tenant by design — one process, one brain, one user. Real products serve thousands of users. Something has to stand between the product and the Engine fleet to provision instances, route traffic, monitor health, rotate keys, and clean up after sleeping users. That something is bap-engine. bap-engine is the orchestrator we use to run the public Engine product. It lives in septemberai/bap-engine.

​
What it does

A product (like our bap-backend) talks to bap-engine, not directly to Engine instances. bap-engine handles:
  • Provisioning — creating a fresh Engine for a new user.
  • Discovery — looking up which Engine belongs to which user.
  • Admission — rate-limit + quota checks before letting a request through.
  • Lifecycle — start, stop, sleep, wake, destroy, key-rotate.
  • Health — periodic probes; auto-restart on failure with backoff.
  • Audit — every lifecycle action logged to Postgres.
  • Fleet metrics — aggregate state for ops dashboards.
The product never touches Docker, never holds engine API keys long-term, never decides whether to provision. bap-engine owns all of that.

​
How it fits

The orchestrator stays out of the data path. Once POST /admit returns an Engine URL and key, the product talks to the Engine directly for /execute — including SSE streaming. bap-engine coordinates; it does not proxy.

​
Why a separate service

bap-engine could in principle live inside the Engine. It used to — the orchestrator was extracted from engine into bap-engine in v2.3.0. We split because:
  1. Different lifecycles. The Engine ships when its agent loop or memory layer changes. The orchestrator ships when fleet management changes. Coupling them slows both.
  2. Different runtimes. The Engine runs as one container per user with the user’s brain mounted. The orchestrator runs once and talks to many Engines via the Docker API.
  3. Different blast radius. A bug in the Engine affects one user; a bug in the orchestrator affects the whole fleet. Different review thresholds.
  4. Different surface. The Engine’s API is for agents (/execute, /hitl, /memory). The orchestrator’s API is for fleet ops (/engines/provision, /admit). They don’t share callers.

​
What it isn’t

  • Not a load balancer. Each user has their own Engine; there’s no routing across users.
  • Not a proxy. The orchestrator hands the product an Engine URL and stays out of the call.
  • Not a cache. It writes state to Postgres and reads on every request.
  • Not multi-product-shared. Each product has its own product ID and its own slice of the fleet. Users are unique within a product, not across products.

​
Where to start

Quickstart

Run bap-engine locally with the orchestrator + Postgres in Docker.

Architecture

The orchestrator’s internals — registry, lifecycle, health, backends.

API reference

Every endpoint, every parameter.
If you’re integrating an existing product, the engine contract is the relevant page — it spells out what you call, what you get back, and how the keys flow.