Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

32.0 KB
Raw Blame

Deployment

Open Executive ships as two containers — the FastAPI backend and the Next.js UI — plus one persistent volume. Anything that can run a Docker image and attach a disk will host it: docker compose on a single box, a container platform, or a Kubernetes deployment.

docker/docker-compose.yml is the reference topology. It is also what make docker runs locally, with one difference: the compose UI is a next dev server on a bind mount, not the production image from Dockerfile.ui.


⚠️ Single instance only

The API must run exactly one replica. The scheduler claims due rows with UPDATE … RETURNING, which is safe against concurrent claims within a process but not across processes: a second API container fires every scheduled action a second time — duplicate emails, duplicate Slack messages, duplicate briefings.

There is no leader election. Whatever you deploy on, pin the API to one instance and use a replace-in-place rollout rather than one that briefly runs two containers. The UI is stateless and scales freely.


Topology

Component Dockerfile Published image State
API docker/Dockerfile ghcr.io/sentelabsai/openexecutive-api One persistent volume at /data
UI docker/Dockerfile.ui ghcr.io/sentelabsai/openexecutive-ui Stateless

The UI never talks to the API directly from the browser. It proxies through its own server (/api/backend/*), stamping the shared secret on each upstream call, so the UI origin is the only one that needs to be public. See auth.md.

The compose file binds the API to 127.0.0.1 on purpose. The UI reaches it over the compose network, so nothing needs it on 0.0.0.0. If you change that binding or put the API behind a proxy on its own hostname, you have made it internet-reachable — set BACKEND_SHARED_SECRET and OE_PUBLIC_DEPLOYMENT=1 before you do. Neither is set by default, and without them the API serves every route unauthenticated with only a log line to say so.

Images

.github/workflows/release-images.yml builds both images from the Dockerfiles above, with the repo root as build context, and pushes them to GitHub Container Registry. Nothing is added or configured in CI. Note that make docker builds only the API image — the compose file runs the UI as a next dev server — so this workflow is the only thing that builds Dockerfile.ui.

Tag Set by Meaning
X.Y.Z, X.Y pushing git tag vX.Y.Z A release. Pin deployments to one of these.
latest pushing git tag vX.Y.Z The most recently published release, by push order, not the highest version. Pushing a v0.2.1 patch after v0.3.0 moves latest back to 0.2.1.
main every push to main Current head of main; not a release.
sha-<short> every push The commit the image was built from.
buildcache every push BuildKit layer cache. Not an image; ignore it.

Cutting a release is merging the release PR. .github/workflows/release-please.yml runs release-please on every push to main and keeps one open PR, "chore(main): release X.Y.Z", up to date. PRs are squash-merged, so each one lands as a single commit whose subject is the PR title, and the version comes from those titles' conventional-commit types since the last release. Before 1.0, feat and fix both bump the patch version and a breaking change (! or a BREAKING CHANGE: footer) bumps the minor; minor versions are kept for milestones. From 1.0 the usual rule applies: feat → minor, fix → patch, breaking → major. The PR bumps every place the version is written (listed in release-please-config.json) and adds the CHANGELOG.md entry, which can be edited in the PR before merging. Merges that are only chore/docs/test/refactor wait for the next feat or fix. Merging the release PR tags the merge commit vX.Y.Z and creates the GitHub Release; the tag push then runs the image workflow. It needs the RELEASE_PLEASE_TOKEN repository secret (a fine-grained token for this repository with Contents and Pull requests read/write), because events made with the default GITHUB_TOKEN start no workflows: without it the release PR would get no CI and the tag would publish no images.

Pushing a vX.Y.Z tag by hand still works (git tag v0.3.0 && git push origin v0.3.0) but bypasses the version bump and changelog, so the release PR is the normal path.

The image workflow runs on the tag push and publishes the versioned tags. It does not check CI: it publishes whatever commit the tag points at, and the main tag is published in parallel with CI on every push, so the release PR should only be merged once its CI is green. The two images are separate jobs, so a release is not atomic — if one fails, check the package pages and re-run the failed job from the Actions UI.

Once both images are published, the same run creates the GitHub Release for the tag if it does not exist yet (release-please normally already made it), with that version's CHANGELOG.md section as the notes. A hand-pushed tag with no ## [X.Y.Z] section fails that job instead of publishing an empty release. If the images fail, no release is created; re-running the failed job from the Actions UI creates it once the images succeed. A release that already exists for the tag is left alone.

The images are linux/amd64 only. The API image bakes the embedding models at build time (see the Dockerfile), which makes an emulated arm64 build impractically slow.

First publish: GitHub creates each package as private. An org admin makes openexecutive-api and openexecutive-ui public once under the org's Packages settings; until then docker pull needs a token with read:packages.


Persistent state

One volume, mounted at /data:

  • /data/chroma_db/ — ChromaDB vector index (built-in knowledge + uploaded company docs)
  • /data/episodic_memory.db — SQLite: episodic memory, people, alerts, scheduled actions, audit log
  • /data/company/profile.yaml + /data/company/docs/ — onboarding output + uploaded docs
  • /data/company/mcp_servers.json — MCP gateway config. Placing this file is what enables MCP when MCP_ENABLED is unset; set MCP_ENABLED=false to keep MCP off with the file in place. A config defining no servers under mcpServers, or a gateway that fails to start, is logged and skipped — the API boots without MCP tools (and without the email poller) rather than failing to boot.
  • /data/google_credentials/ — Google Workspace OAuth token, if that integration is enabled
  • /data/ms365_credentials/ — Microsoft 365 MSAL token cache (+ its .cache-key), if that integration is enabled

Nothing hardcodes those paths. Each is an env var, and the defaults are repo-relative so a local checkout works with no configuration:

VECTOR_STORE_PATH             = /data/chroma_db
EPISODIC_DB_PATH              = /data/episodic_memory.db
COMPANY_PROFILE_PATH          = /data/company/profile.yaml
MCP_SERVERS_CONFIG_PATH       = /data/company/mcp_servers.json
WORKSPACE_MCP_CREDENTIALS_DIR = /data/google_credentials
MS365_MCP_CREDENTIALS_DIR     = /data/ms365_credentials

On first boot the volume is empty. ChromaDB rebuilds the built-in knowledge index from files shipped inside the Python package (openexecutive/knowledge/builtin/), and the SQLite database is created on demand. The company profile stays empty until you run the onboarding wizard against the deployed URL — the wizard failing with "no company profile" on a fresh volume is expected, not a fault.


Required configuration

Variable Why
ANTHROPIC_API_KEY Every agent call. The app will not start without it.
BACKEND_SHARED_SECRET Gates every API route via x-api-key. Generate with openssl rand -hex 32; the UI needs the same value.
CALLER_ASSERTION_PUBLIC_KEYS (API), CALLER_ASSERTION_PRIVATE_KEY (UI) Signed callers: the UI signs who is signed in and the API checks it, so the shared secret alone can't act as the owner. Recommended. Make the pair with scripts/make-caller-keys.py; see auth.md.
OE_PUBLIC_DEPLOYMENT=1 Set this on every internet-reachable instance. See below.
BACKEND_ALLOWED_ORIGINS Comma-separated UI origins allowed through CORS, e.g. https://exec.example.com. With OE_PUBLIC_DEPLOYMENT set these are the only ones: the localhost:3000 origins make dev uses are dropped.
OE_HOST_ORIGINS (UI) Optional. Origins of other apps that may frame the UI and call its short host list from their pages, e.g. https://app.example.com. Unset, only the UI frames itself. See below.
AUTH_SECRET, AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET, AUTH_OIDC_ISSUER, AUTH_OIDC_ID, AUTH_OIDC_SECRET, AUTH_URL, ALLOWED_EMAILS UI sign-in (Google and/or SSO). See auth.md.

Integrations (Slack, Discord, email, Google Workspace, Microsoft 365) are all optional and off unless their variables are set. .env.example is the full list.

OE_PUBLIC_DEPLOYMENT

If BACKEND_SHARED_SECRET is unset the API serves every route unauthenticated. That is the intended default for local development and a serious incident anywhere else, so a deployment declares itself public:

OE_PUBLIC_DEPLOYMENT=1

With it set and no shared secret, create_app() raises at startup instead of booting an open API. The check is deliberately fail-safe — any value other than 0/false/no/off/empty arms it, so a typo requires the secret rather than skipping the check.

Showing Open Executive inside another app (OE_HOST_ORIGINS)

A host app (another web app that frames Open Executive's pages and calls a short list of its routes, auth.md) is listed on the UI by its exact origin:

OE_HOST_ORIGINS=https://app.example.com

Host it like this:

  • A sibling host, one site. Serve the UI at the root of its own host under the host app's registrable domain (exec.example.com beside app.example.com), never under a path of the host app and never on an unrelated domain: the session cookie is SameSite=Lax, so a host on another site would get no cookie in its frame or with its calls (Safari and Firefox block third-party cookies).
  • Its own server block (or its own proxy), not a location inside the host app's, with its own TLS, buffering off for /api/backend/ (streamed chat), and a body limit of 55 MB (the largest upload the API takes, with room). A header added inside a location can drop the server's other headers; keep the UI's own Content-Security-Policy as it sends it.
  • A fixed sign-in address. Set AUTH_URL=https://exec.example.com and leave AUTH_TRUST_HOST unset, so no request's Host header steers where sign-in returns. The sign-in provider's client returns to that host.
  • Internal ports stay internal. The API, the UI's own port and the host app's application port are reachable only from their proxies.
  • Nothing else on the domain serves outsiders' content. Every host under the same registrable domain can make same-site requests that carry both apps' cookies. Keep a public website, a customer portal or uploaded files off this domain, or accept that a script on one of them can make same-site requests to both apps. Each app's own checks still stand: the UI's proxy refuses every same-site write except the host list from the exact host origin.

Never list the UI's own origin: its pages' writes would then be judged as a host's and refused.

Removing an origin from OE_HOST_ORIGINS (and restarting the UI) stops that host's framing and every call from its pages at once. make embed-outputs writes the files a host app checks itself against (embed-manifest.json, host-list.json, openapi.json).


Health checks

GET /health is exempt from the shared-secret gate so a platform health checker can reach it unauthenticated. It returns:

{"status": "ok", "builtin_knowledge_chunks": 1234, "google_tools_missing": [], "version": "0.1.0"}

google_tools_missing is the pinned Google tools startup priming could not find. [] means it checked and they are all there — the only value that says so. A list of names means a workspace-mcp update renamed one, or the configured services and tool tier never loaded it; Settings → Setup status names them too. null means no answer: Google Workspace is not configured, or the probe has not finished, or it failed. Expect null during the startup grace period below, so alert on a non-empty list rather than on "not []".

Give it a startup grace period of about 5 minutes. A cold container builds the MCP tool-discovery vector index and loads Chroma before it serves. The embedding model is baked into the image, so no network fetch is involved, but the work is real — a short grace period will kill the container mid-boot in a crash loop that looks like a deploy failure.

Resources

2 GB of memory for the API. 1 GB out-of-memories during ingest, where the ONNX embedder and Chroma writes run concurrently. One shared CPU is sufficient; the workload is I/O-bound on the Anthropic API.


Google Workspace credentials

The Gmail/Calendar/Drive tools come from workspace-mcp, which runs co-located inside the API as a stdio child of the MCP gateway rather than as its own service — the product is single-tenant, so the server is inherently one per install. It is baked into the API image and launched by docker/workspace-mcp-launch.sh from the google_workspace entry in /data/company/mcp_servers.json (see packages/core/mcp_servers.json.example for the exact block).

GWORKSPACE_AUTH_MODE picks the auth mode; it defaults to oauth.

Option A — oauth (single user). Set GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET. The API serves no OAuth callback, so the token has to be seeded: complete the flow once locally with WORKSPACE_MCP_CREDENTIALS_DIR pointed at a local folder, then copy the credential file onto the volume.

docker compose exec api mkdir -p /data/google_credentials
docker compose cp <local-credentials-dir>/<token-file> api:/data/google_credentials/
docker compose restart api        # the gateway reads config and credentials at startup

Option B — service_account (domain-wide delegation). No browser flow, but a Workspace admin must authorize the service account's client ID for the Gmail/Calendar/Drive scopes:

GWORKSPACE_AUTH_MODE=service_account
[email protected]
GOOGLE_SERVICE_ACCOUNT_KEY_JSON=<contents of service-account.json>

(GOOGLE_SERVICE_ACCOUNT_KEY_FILE, a path to a key already on the volume, works too. The launcher fails fast if neither the key nor USER_GOOGLE_EMAIL is set.)

Outbound egress is gated either way: the Executive can only email, invite, or share with People on the roster.

Every Google Workspace call acts as the Executive's own account: the gateway refuses a call whose user_google_email names any other address.

Narrowing the Google tool surface (optional)

Two variables decide how much of Google Workspace the co-located child loads. Both default to everything; leave them unset unless you want less.

Variable Default Values
WORKSPACE_MCP_TOOLS all all, or comma-separated service names: gmail, calendar, drive, docs, sheets (also chat, forms, slides, tasks, contacts, search, appscript)
WORKSPACE_MCP_TOOL_TIER complete core, extended, complete

WORKSPACE_MCP_TOOLS reaches workspace-mcp as --tools, which decides which service modules it imports. A service you leave out is never imported, so none of its tools exist — not in the index, and not callable. The tier decides how many tools per service are registered; tiers are cumulative, and core is the smallest.

Both are prompt-visible. The Connected Systems block in the cached system prompt names only the services actually loaded and pins only the tool names that exist at the active tier, and startup priming probes the same set — so the Executive is never told a tool is "already available" when it is not. If you narrow these, expect the block to name fewer services; that is the intended effect, not a fault.

Two things worth knowing before narrowing:

  • core leaves out ten of the pinned tools — Gmail drafts, threads and attachments, Drive item listing, calendar freebusy, and the Docs/Sheets listing and info tools. extended and complete both cover all of them.
  • all means every service only as the whole value (surrounding commas or spaces are fine). gmail,all is passed through as the two names gmail and all, and since all is not a service name, workspace-mcp's argument parser rejects it and the child does not start at all — you lose every Google tool, not just the misspelled one. Write all on its own, or list only real service names.
  • Both variables reach the child through the env block of the google_workspace entry in mcp_servers.json, which must forward them ("WORKSPACE_MCP_TOOLS": "$WORKSPACE_MCP_TOOLS" and the same for WORKSPACE_MCP_TOOL_TIER, as mcp_servers.json.example does). A config that forwards only one of them leaves the API filtering the prompt on a value the child never saw, which hides tools that are in fact callable.

A pinned tool that priming cannot find is logged once at startup, naming both possible causes — the service list or tier excluding it, or workspace-mcp having renamed it since the pin in docker/Dockerfile.

Your own Gmail or Outlook (Act as me, optional)

Act as me lets the Executive draft replies as the owner, in the owner's own Drafts (Gmail or Outlook), when they ask it to, and (with Draft replies to my inbox on) for mail that needs them. Nothing goes out unless the owner sends it: from their mailbox, or with Send on a reply card on Today, which needs signed sign-ins on a server (see docs/auth.md). It uses a separate credential for the owner's mailbox, read by the API directly and never handed to workspace-mcp, so it must not live in the credentials directory above.

# On a machine with a browser, with the same OAuth client exported:
uv run --with google-auth-oauthlib python scripts/connect-own-gmail.py --email [email protected]
docker compose exec api mkdir -p /data/delegation_google
docker compose cp delegation-credentials/<file>.json api:/data/delegation_google/

For an Outlook mailbox (work, school or personal), run scripts/connect-own-outlook.py instead, with the Microsoft 365 app from .env.example exported (MS365_MCP_CLIENT_ID, and MS365_MCP_TENANT_ID if it is single-tenant). It prints a code to enter at Microsoft's sign-in page, from any browser, and writes the same kind of file, which goes in the same directory. The app needs public client flows on and the delegated Graph permissions User.Read, Mail.ReadWrite and Mail.Send. A person has one mailbox for Act as me: connecting the other kind replaces the file. The address is checked against Microsoft's directory, never the mail itself: a personal account that signs in with another address (a Gmail one, say) and has no Outlook address of its own on file is matched by that sign-in address, so use it on the People page and with --email.

Read my calendar (optional). Run either script with --calendar to also grant access to the person's own calendar (calendar.events on Google, which the OAuth client's consent screen must list; the delegated Calendars.ReadWrite permission on the Microsoft app). Then turn on Read my calendar in Delegate → Act as me. The Executive reads events fresh each time and keeps nothing. The one change it makes there is answering a meeting invite: Accept or Decline on an invite card on Home, or an accept on its own under Handle it for me. A credential minted without --calendar keeps working for mail, and the switch says to reconnect with the flag; one minted earlier with read-only calendar access (calendar.readonly, Calendars.Read) keeps reading, and its invite cards say to connect again to answer.

MS365_MCP_CLIENT_ID=<app id> uv run python scripts/connect-own-outlook.py --email [email protected]

No restart is needed. The address must be the owner's email on the People page, and it must not be the Executive's own EXEC_EMAIL_ADDRESS. Then turn it on in Delegate → Act as me; the setup status page shows the connection.

Team members (optional). Set DELEGATION_TEAM_MEMBERS=true and the owner gets Let team members use it in Delegate → Act as me. Once they turn it on, each team member connects their own Gmail or Outlook the same way (the script with their own address, one file each in the same directory) and turns it on for themselves. A team member's mail, drafts, reply cards and audit rows are theirs alone: the owner sees only who uses it and how much.


Upgrading

Settings → About shows the version you are running. When a newer release is out it says so and links the release notes and this section. The API asks GitHub's public releases API for the latest release at most every six hours, and sends nothing about your install. Set UPDATE_CHECK_ENABLED=false to turn the check off (for an air-gapped host, say); the running version is still shown. GET /version returns the same facts as JSON.

There is no in-app update button: updating means replacing the containers, which the app cannot do from inside one without being given control of the host's Docker. Upgrade from the host instead.

  1. Read the release notes. Each release's entry in CHANGELOG.md (also on the GitHub Release) lists what changed. Before 1.0 a minor bump (0.4.x → 0.5.0) marks a breaking change, such as a new required env var; do what its entry says first.

  2. Back up the database. /data/episodic_memory.db is the part you cannot rebuild; see Backups under Operations.

  3. Replace the containers. Your data lives in the executive_data volume, which survives both of these.

    From a checkout, with make docker:

    git fetch --tags
    git checkout vX.Y.Z     # or `git pull` on main to follow unreleased changes
    make docker             # rebuilds the API image and restarts the stack
    

    From the published images: change the image tags to the new release (ghcr.io/sentelabsai/openexecutive-api:X.Y.Z and ghcr.io/sentelabsai/openexecutive-ui:X.Y.Z), then

    docker compose pull
    docker compose up -d
    

    Never run docker compose down -v to upgrade: -v deletes the volume.

  4. Check it came back. curl -s http://localhost:8000/health reports the new version, and Settings → About shows it.

To go back, see Rollback under Operations.


Microsoft 365 credentials

Outlook mail and calendar tools come from @softeria/ms-365-mcp-server, a Node MCP server that — like workspace-mcp — runs co-located inside the API as a stdio child of the MCP gateway. It is baked into the API image (a Node build stage copies the pinned package and the node binary in; there is no npm in the runtime image) and launched by docker/ms365-mcp-launch.sh from the microsoft_365 entry in /data/company/mcp_servers.json (see packages/core/mcp_servers.json.example for the exact block). Both servers can be configured at once; the Executive discovers whichever tools are present.

Auth is the MSAL device-code flow against your own Entra app registration (the server's built-in public client id is refused). Register the app (Entra admin center → App registrations → New; Allow public client flows: Yes; delegated Graph permissions Mail.ReadWrite, Mail.Send, Calendars.ReadWrite, Files.ReadWrite and Files.Read.All (only with MS365_MCP_ONEDRIVE=true, below), plus User.Read and offline_access for the sign-in, with admin consent — ms365-mcp-launch.sh --list-permissions prints exactly what the configured tool list requests), then set:

MS365_MCP_CLIENT_ID=<application (client) id>
MS365_MCP_TENANT_ID=<directory (tenant) id>          # or "common" / "consumers"
[email protected]     # pins the signed-in account
MS365_MCP_CLIENT_SECRET=<only for a confidential app registration>

The API serves no OAuth callback and needs none: sign in once from inside the container and the refresh token lands on the volume.

docker compose exec api /usr/local/bin/ms365-mcp-launch.sh --login          # prints a URL + code; sign in as the exec mailbox
docker compose exec api /usr/local/bin/ms365-mcp-launch.sh --verify-login
docker compose restart api        # the gateway reads config and credentials at startup

Setup is the launcher's --login, never chat: MS365_MCP_EXPECTED_USERNAME is what stops a different account being bound. Run --login again if the refresh token is ever revoked — until then every Microsoft 365 call answers with an error payload and the API keeps serving. The server registers its account tools whatever --enabled-tools says, so the gateway refuses microsoft_365__login, logout, select-account and remove-account itself and leaves them out of search_tools results — a chat turn cannot sign the mailbox out, wipe the seeded token or switch accounts, whatever mcp_servers.json says. The example config denies them too (defense in depth). The read-only verify-login and list-accounts stay callable.

The launcher scrubs $VAR placeholders that extensible-mcp leaves literal for unset variables, refuses to start without MS365_MCP_CLIENT_ID, keeps the token cache under MS365_MCP_CREDENTIALS_DIR (0700), and starts the server with an explicit allow-list of tools (--enabled-tools, an anchored regex in the launcher) rather than the upstream mail,calendar preset: the preset also registers inbox forwarding rules, mailbox settings (external auto-reply), calendar sharing and event forwarding, which can address people the gateway never sees. Exactly the Outlook mail + calendar tools and the OneDrive tools (plus the login tools) are exposed. Egress is gated like Google: send-mail, forward and every draft tool have their recipients roster-checked from the arguments; reply, reply-all and send-draft — whose recipient is whoever the referenced message names — have the gateway read that message first and check the sender / original recipients / draft recipients (reply-all checks replyTo and the sender together); create-/update-calendar-event attendees must be People on the roster. Every mail write's from, sender and replyTo may name only EXEC_EMAIL_ADDRESS (the Outlook twin of the Gmail acting-account pin), and move-mail-message into Deleted Items, Junk Email or Recoverable Items is refused, so the model cannot trash mail through a move. OneDrive gets the surface Google Drive has (search, list, upload and edit, folders, move, rename, copy, share; no delete), but only with MS365_MCP_ONEDRIVE=true and a fresh --login: the server asks for its tools' permissions on every token refresh, so the file tools are off until the sign-in grants them. download-bytes is pinned to mail attachments and OneDrive file content, and a OneDrive file comes back as its text rather than base64. share-drive-item invitees must be on the roster and named by email, and create-drive-item-share-link must be scoped to specific people (scope: "users"); an invite must require sign-in and grant only view or edit. Writes (upload, new folder, move, copy) land only in the Executive's own drives, so nothing is written into a folder someone else shared, and search-onedrive-files takes plain words only (its query goes into the request path unencoded). The same sign-in feeds the optional OneDrive folder sync (onedrive_sync_setup.md), which asks the launcher for a token (--access-token) rather than keeping a credential of its own. Widening the allow-list (MS365_MCP_ENABLED_TOOLS / MS365_MCP_PRESET) is an operator decision that must come with a matching gate change in orchestrator/mcp_gateway.py.

Switching the mailbox and calendar to Microsoft 365

Adding the server only gives the Executive Outlook tools. Three code paths call a fixed backend without the model choosing — the inbound mailbox poller, alert email dispatch and the scheduler's email hint, and the typed create_calendar_event / create_instant_meeting tools with their approval ledger. They follow two switches, both defaulting to google:

EMAIL_PROVIDER=microsoft      # poll the Outlook inbox; reply via microsoft_365__reply-mail-message
CALENDAR_PROVIDER=microsoft   # book on the Outlook calendar with a Teams link

The switches are independent. A chosen backend whose MCP server is missing from mcp_servers.json is logged at startup and the poller skips its cycle; boot never fails. On Microsoft the approval-time conflict check reads only the Executive's own calendar (delegated permissions cannot read attendees' free/busy), so it is advisory in a narrower sense than Google's.


Operations

# Logs
docker compose logs -f api

# Smoke the API directly
curl -s -H "x-api-key: $BACKEND_SHARED_SECRET" https://api.example.com/health

# Same JSON, proxied through the UI (exercises the shared secret end to end)
curl -s https://exec.example.com/api/backend/health

# Inspect state on the volume — SELECT only unless you mean it
docker compose exec api sqlite3 /data/episodic_memory.db \
  "SELECT id, kind, status, run_at FROM scheduled_actions WHERE status='pending' LIMIT 10;"

Rollback is an image-tag rollback: redeploy the previous release tag (see Images). The volume is not versioned with the image, so a release that migrates schema forward is not undone by rolling the image back — check what changed under */store.py before relying on it. Additive column migrations (the common case — every column has a default and older builds name their columns explicitly) are safe to roll back over; a rolled-back build simply ignores the newer columns.

Backups. There is no snapshot cron in this repo. /data/episodic_memory.db is the irreplaceable part (Chroma rebuilds from source documents), so back it up with sqlite3 /data/episodic_memory.db ".backup /tmp/backup.db" and copy it off the host — a plain file copy of a live SQLite database can be torn.


Common failure modes

Symptom Likely cause Fix
Deploy reports success, /health never responds Crash during boot, usually a missing env var Read the API logs; look for a Pydantic ValidationError naming the variable
Container is killed and restarted repeatedly during startup Health-check grace period too short Raise it to ~5 minutes (see above)
API refuses to start: BACKEND_SHARED_SECRET is required OE_PUBLIC_DEPLOYMENT is set with no secret Working as intended — set the secret
Every UI request errors, API is healthy UI proxy can't reach the API, or the shared secret differs between them Check BACKEND_BASE_URL on the UI and that both sides carry the same BACKEND_SHARED_SECRET
Every UI request is 401 with a caller_assertion_* code Signed callers are half set up See auth.md → Debugging
Browser console shows CORS errors UI origin missing from BACKEND_ALLOWED_ORIGINS Add the exact scheme + host
Scheduled actions firing twice More than one API replica Scale the API to exactly 1 (see the warning at the top)
Onboarding wizard says "no company profile" Empty volume on first boot Expected — complete the wizard; output lands at /data/company/profile.yaml

Optional: self-hosted Honcho

Per-person memory can run against hosted Honcho (set HONCHO_API_KEY and HONCHO_BASE_URL) or a self-hosted instance. docker/honcho/ carries the image and configuration for the self-hosted path.