Enterprise Install

For operators — someone doing a ground-up enterprise install. This is an annotated
variant of Self-hosting Temper, not a standalone guide. The base
playbook covers the core API + MCP deployment; this one adds the enterprise-specific
configuration on top: SAML SSO, group provisioning, and org bootstrap. Start with the base
playbook for the deploy, then follow this one for the enterprise extensions.

By the end you will have a deployed Temper instance behind Okta SAML SSO, with a first
system admin, instance settings, an everyone-team every member auto-joins, and an
org-identity cognitive map — ready for your users to sign in and work.

Primary path: Temper's native Authorization Server fronting your Okta SAML app (see
Self-hosting with SAML). Auth0 and Okta-OAuth are noted
variants — see Self-hosting Temper and
Self-hosting with Okta if your organization uses one of those
instead.

Prerequisites

The base deployment stood up. This playbook assumes you have followed
Self-hosting Temper and have the API + MCP surfaces deployed.

An embed-capable temper binary. Org bootstrap's cogmap create / cogmap reconcile
embed the charter client-side (ONNX). The default install bundles it; if you built from
source, reinstall with cargo install --path crates/temper-cli --locked --force.

psql and DATABASE_URL_UNPOOLED for the DB-only steps — running migrations and the
irreducible SQL root step that promotes the first system admin.

Okta admin access to create the SAML app and configure the AS.

A Vercel project to host the API + MCP surfaces (and, optionally, a second project for
the web UI).

A Neon project (PostgreSQL 17) for the instance database.

Familiarity with the auth-identity contract — see
Auth Identity for the issuer/audience agreement rules the
server enforces at boot.

Familiarity with the trust boundary — see
The Trust Boundary for the two-gate access model every
call crosses.

What you end up with

Outcome	Produced by
Deployed API + MCP behind Okta-SAML SSO	Self-hosting Temper deploy + Self-hosting with SAML
A first system admin	the SQL root step (irreducible)
Instance settings (name, gating, mode)	`temper admin settings`
An everyone-team every member auto-joins	`temper team create … --auto-join-role watcher`
An org-identity telos-charter cognitive map, born + bound	`temper cogmap create` → `temper cogmap reconcile` → `temper cogmap bind`
(optional) The web UI	Self-hosting Temper
(deferred) The Eve steward	deferred — not sequenced in this playbook

Four phases

(A) Install the temper binary — a prerequisite for every phase below; see
Install Temper.

(B) Backend deploy + auth — stand up the API + MCP surfaces on Vercel + Neon, wired to
Okta SAML. See Self-hosting Temper and
Self-hosting with SAML.

(C) Org bootstrap — take the blank-but-stable install to a usable org: first admin,
instance settings, everyone-team, org-identity cognitive map. See
Bootstrap an Org.

(D) Agents [deferred] — deploying an Eve agent (the team-self-cognition steward) against
the instance. Not sequenced in this playbook.

Environment matrix

One consolidated table across all three surfaces. Set the api+mcp and SAML-AS rows
before Phase B; the temper-ui rows only if you deploy the optional UI. The eve column
is deferred — surfaced for completeness, not a step in this playbook.

Sources: Self-hosting Temper,
Self-hosting with SAML.

Variable	temper-cloud (api+mcp)	temper-ui	eve (deferred)	Notes
Database
`DATABASE_URL`	Yes (pooled, runtime)	—	—	One Neon connection string shared by api/mcp
`DATABASE_URL_UNPOOLED`	Yes (deploy step only)	—	—	Direct Neon connection string; migrations only
Auth (issuer / audience / provider)
`AUTH_ISSUER`	Yes	—	—	Auth0 tenant, or `AS_ISSUER` value in the SAML path
`JWKS_URL`	Yes	—	—	Auth0 JWKS, or `https://<instance>/oauth/jwks` in the SAML path
`AUTH_AUDIENCE`	Yes	—	—	The API/default audience, accepted at both doors; must equal `AS_AUDIENCE` / UI `OIDC_AUDIENCE`
`AUTH_PROVIDER_NAME`	Yes	—	—	`auth0`, or `saml:<idp-key>` in the SAML path (max 32 chars)
`MCP_AUDIENCE`	Yes, to serve MCP clients	—	—	The MCP resource indicator, `https://<instance>/mcp`. Independent of `AS_AUDIENCE` — no equality rule. Unset, it defaults to `AUTH_AUDIENCE`, and strict MCP clients refuse an `/api` resource. Same value on the AS, MCP and API functions: the MCP server relays each call to the API with the caller's token. See Self-hosting with SAML
`MCP_CLIENT_ID`	Yes	—	—	External IdP: the MCP native app's client_id. SAML path: `<mcp-client-id>`, a key you choose that must also appear in `AS_CLIENTS`; dynamic registration answers `503` without it
`MCP_BASE_URL`	Yes	—	—	`https://<instance>` — used in OAuth discovery responses
`TEMPER_API_BASE_URL`	Yes	—	—	The relay's target for every tool act; pin to this deployment's own API URL in the MCP function's environment and never point it elsewhere — the relay presents the bearer plus `TEMPER_MCP_SERVICE_SECRET` to that origin
`TEMPER_MCP_SERVICE_SECRET`	Yes	—	—	One generated secret on both api and mcp functions (`openssl rand -base64 32`); the API trusts the relay's attribution carrier only beside it, refuses to boot on overlap with any other shared secret or on a value under 16 characters. Unset on the API, every relayed act attributes `@web` — the MCP surface still works, the door is simply unarmed
`MCP_PROXY_SECRET`	Yes (external-IdP path)	—	—	≥ 32 chars (`openssl rand -base64 48`); encrypts the loopback redirect proxy's state token, derived from this secret alone. New — an upgraded deployment will not have it. Until it is set, a loopback sign-in (MCP CLI clients) answers `503` naming this variable; browser clients with an HTTPS callback are unaffected. Set it and redeploy — a Vercel function's environment is bound to its deployment. Rotating it fails sign-ins already in flight for up to 10 minutes; they succeed on retry. n/a in the SAML path — the Temper AS runs the whole flow and the relay answers `404` there
SAML Authorization Server (AS) block
`AS_ISSUER`	Yes (SAML path)	—	—	Setting this flips the instance into AS mode
`AS_AUDIENCE`	Yes (SAML path)	—	—	Must equal `AUTH_AUDIENCE`
`AS_SIGNING_KEY_PKCS8`	Yes (SAML path)	—	—	Ed25519 signing key, PKCS#8 PEM — secret
`AS_SIGNING_KID`	Yes (SAML path)	—	—	Key id published in the JWKS
`AS_CLIENTS`	Yes (SAML path)	—	—	JSON `client_id → [redirect_uris]` allowlist; unset = fail-closed. The whole registry — edit it, never replace it from an example. Remote callbacks match exactly
`AS_ACCESS_TTL_SECONDS`	Optional (default `900`)	—	—	Access-token lifetime
`AS_REFRESH_TTL_SECONDS`	Optional (default `2592000`, 30d)	—	—	Refresh-token lifetime (slides on rotation)
`AS_REFRESH_CHAIN_MAX_SECONDS`	Optional (default `7776000`, 90d)	—	—	Absolute refresh-chain lifetime from the last full login — the real bound on IdP-removed reach
`AS_REFRESH_REPLAY_GRACE_SECONDS`	Optional (default `10`)	—	—	How soon after a rotation a spent refresh token may be presented again and be read as a client retry rather than a stolen chain. Later, the chain is ended. `0` = strictest; max `3600`, and out-of-range or non-numeric values fall back to the default. Not emitted by `temper admin saml provision`; set it only to move the default
`AS_SAML_ASSERTION_MAX_SECONDS`	Optional (default `3600`, 1h)	—	—	The widest assertion validity window your IdP issues. The retention sweep will not delete a consumed assertion id until this long after the row's `expires_at`, so it must not sit below your IdP's `NotOnOrAfter`. A present-but-unusable value fails the sweep rather than substituting; unset or blank uses the default. Read by `temper-api`, unlike the `AS_*` rows above. Not emitted by `temper admin saml provision`
Group provisioning / reconcile channel (SAML Phase 2)
`INTERNAL_RECONCILE_SECRET`	Yes (SAML path; shared AS+API)	—	—	Same value on both; unset disables reconcile (auth still works)
`INTERNAL_RECONCILE_URL`	Yes (SAML path; AS side)	—	—	Full URL of the API's `/internal/saml/reconcile`
`INTERNAL_RESOLVE_URL`	Yes (SAML path; AS side)	—	—	Full URL of the API's `/internal/principal/resolve`; same secret. New — an upgraded deployment will not have it. Unset ⇒ refresh chains carry no owner, an admin revoke ends none of them, and every request still returns `200`. See the upgrade note in Self-hosting with SAML
Slack account link (optional; needed only to run the @temper mention agent)
`SLACK_LINK_CLIENT_ID`	Yes (Slack path)	—	—	OAuth client the link flow authorizes as. Auth0: a native/PKCE app's client_id. SAML path: a `client_id` present in `AS_CLIENTS`
`SLACK_LINK_SECRET`	Yes (Slack path; shared API+agent)	—	—	Shared secret gating `/internal/slack/link-state`; same value on the mention agent. Unset ⇒ the endpoint is disabled (auth still works)
`PUBLIC_BASE_URL`	Yes (Slack path)	—	—	`https://<instance>` — the origin the link `redirect_uri` is built from³. All four unset together is the supported "no Slack" state
`SLACK_VAULT_ENC_KEY`	Yes (Slack path)	—	—	32-byte base64 AEAD key (`openssl rand -base64 32`) encrypting each stored per-user refresh token. Malformed ⇒ the whole Slack flow disables. Rotation is flag-day (users re-link). Declare it in `SLACK_VAULT_RETIRED_KEY_FINGERPRINTS`, or every mint answers 500
`SLACK_VAULT_RETIRED_KEY_FINGERPRINTS`	Optional	—	—	Fingerprints of deliberately retired vault keys (16 hex characters each, comma-separated, plus optionally `unstamped`). Copy them from the boot log line `slack vault key fingerprint: …` before rotating. Not secret
Storage / build
`BLOB_READ_WRITE_TOKEN`	Yes	—	—	Vercel Blob token for the binary-blob flow (`temper blob …`, `/api/blobs`, the MCP blob tools) and the upload/extract/embed pipeline. Unset, the blob endpoints answer a disabled refusal; `BLOB_STORE_ID` (OIDC) is the alternative credential. A deployment that does not want the flow at all sets `BLOB_ENABLED=false` — an explicit opt-out winning even with credentials present: the endpoints refuse naming the knob and the MCP tools are not advertised
`SQLX_OFFLINE`	Yes (build)	—	—	Must be `true`
Optional / situational (api+mcp)
`ENABLE_SWAGGER`	Optional	—	—	Exposes `/swagger-ui` in non-production
`PORT`	Optional	—	—	Platform-injected by Vercel
`CORS_ORIGINS`	Situational	—	—	Only for a separate cross-origin browser client — the bundled UI same-origin-proxies and does not need it
UI connectivity
`API_BASE_URL`	—	Yes	—	The API's own origin, not the UI's public origin (loop-detection warning in the base playbook)
`APP_URL`	—	Yes	—	The UI's own public origin
UI OIDC client
`OIDC_ISSUER`	—	Yes¹	—	Must resolve the same issuer as `AUTH_ISSUER` / `AS_ISSUER`
`OIDC_CLIENT_ID`	—	Yes¹	—	`temper-ui` in the SAML AS path
`OIDC_CLIENT_SECRET`	—	Yes¹ (omit in the SAML AS path)	—	The AS registers `temper-ui` as a public PKCE client — no secret
`OIDC_AUDIENCE`	—	Situational	—	Required for Auth0; omit for Okta custom AS / the SAML AS (carried implicitly)
`OIDC_PUBLIC_CLIENT`	—	Yes (SAML AS path)	—	Declares the secret-less PKCE path; without it the UI fails fast at startup
`OIDC_DISCOVERY_URL`²	—	Yes (SAML AS path)	—	Points the UI at the AS's RFC 8414 metadata — the AS has no `/.well-known/openid-configuration`
Session / storefront
`SESSION_SECRET`	—	Yes	—	≥32 bytes of entropy (64-char hex or 44-char base64)
`STOREFRONT_ENABLED`	—	Optional	—	Set falsy to disable the public marketing route group on app-only installs
Eve (DEFERRED — not a step in this playbook)
`TEMPER_MCP_URL`	—	—	Yes	The temper-mcp endpoint, e.g. `https://<instance>/mcp`
`TEMPER_API_URL`	—	—	Yes	The temper REST base, e.g. `https://<instance>`
`TEMPER_M2M_CLIENT_ID`	—	—	Production	The agent's machine-principal client id. Register it first — authentication is fail-closed, with no just-in-time create. On this (AS-mode) install, mint it with `temper admin machine issue`, which returns a `tmpr_…` id
`TEMPER_M2M_CLIENT_SECRET`	—	—	Production	The one-time secret from `issue`. Never in code; rotate with `rotate-secret`
`TEMPER_M2M_TOKEN_URL`	—	—	Production	The issuer's token endpoint. On this install that is your own instance's `/oauth/token` — Temper is the Authorization Server (`AS_ISSUER` set)
`TEMPER_M2M_AUDIENCE`	—	—	External IdP only	Omit it here. Auth0 requires an audience; Temper's own AS ignores a request-supplied one entirely and mints with `AS_AUDIENCE`
`TEMPER_CONNECT_CONNECTOR`	—	—	Fallback	Vercel Connect connector id. Used only when `TEMPER_M2M_CLIENT_ID` is unset, and it cannot mint an app token against an Auth0-fronted instance
`TEMPER_TOKEN`	—	—	Dev only	Pre-obtained token; drives `eve dev`. Not for production
`STEWARD_MODEL`	—	—	Optional	The agent's primary model (default `minimax/minimax-m3`). Resolved at build time, so a change needs a redeploy; an unknown id fails the build
`STEWARD_MODEL_FALLBACKS`	—	—	Optional	Comma-separated, tried in order after the primary fails. Covers availability (5xx, rate limit), never quality

¹ Back-compat fallback: if OIDC_* are unset, the UI falls back to the canonical deployment's
AUTH0_* variables — see Self-hosting Temper. Self-hosters on the
SAML-primary path should set OIDC_* directly.

² OIDC_DISCOVERY_URL is required for the UI on the SAML-AS path — the AS has no
/.well-known/openid-configuration, so the UI needs the explicit discovery URL.

³ The link client's redirect_uri must be registered, or the IdP refuses the authorize request
before temper ever sees it. The flow derives it as <PUBLIC_BASE_URL>/api/auth/slack/callback.
On this (AS-mode) install, add that exact URL to SLACK_LINK_CLIENT_ID's entry in AS_CLIENTS
— unset AS_CLIENTS is fail-closed. On an Auth0-fronted install, add it to the application's
Allowed Callback URLs. It is an exact-match allowlist on both: a trailing slash or an http://
scheme is a different URL.

Must-match by construction

The audience and issuer joins are enforced at boot. Temper parses them once and refuses to
start if they disagree, naming the offending variable and the relation it must satisfy. You do
not have to hold this table in your head — but the values below are what it checks, and
JWKS_URL must be $AS_ISSUER/oauth/jwks on an AS instance.

Join	Values that must be equal
Audience	`AS_AUDIENCE` = `AUTH_AUDIENCE` = UI `OIDC_AUDIENCE` (where set). `MCP_AUDIENCE` is not in this join — it is a second, independent member of the accepted set, required only to be a URI
Issuer	`AS_ISSUER` = `AUTH_ISSUER`; UI `OIDC_ISSUER` resolves the same issuer
Provider label	`AUTH_PROVIDER_NAME` = `saml:<idp-key>`
Reconcile secret	`INTERNAL_RECONCILE_SECRET` identical on the AS and API env (same Vercel project)
Database	`DATABASE_URL` (pooled) shared api/mcp; `DATABASE_URL_UNPOOLED` migrations only

temper admin saml provision renders the AS_* + reconcile block so these are consistent by
construction — it is the reason the SAML env is emitted, not hand-written.

The timeline

temper admin saml provision is an inert emitter — it never touches a running instance. It
runs early (step 3, before the deploy) only because it generates the Ed25519 AS signing key and
the INTERNAL_RECONCILE_SECRET that must already be in the env when the backend deploys. Emitting
early does not mean applying early: provision produces two artifacts that land at different
points in the timeline. The env bundle (--env-out) is consumed pre-deploy, at step 4 (Vercel
env). The kb_saml_idp INSERT (--sql-out) can only be applied post-migrate, at step 6 —
kb_saml_idp is a table created by the migrations run at step 5, so applying it any earlier is
impossible, not just out of order.

#	Step	Owner	Detail link
1	Provision Neon (PG17, `vector` + `pg_uuidv7`, pooled/unpooled)	manual	Self-hosting Temper
2	Register Okta SAML app; capture cert / SSO URL / entity ids / group attribute statement	manual	Self-hosting with SAML + Okta SAML app below
3	`temper admin saml provision` → generate keys, `--env-out` bundle, `--sql-out` kb_saml_idp SQL (inert; early for the env keys)	`saml-setup.sh` (emit)	Self-hosting with SAML
4	Set Vercel env (matrix + emitted bundle) on api + mcp	manual	Environment matrix
5	Deploy backend; `sqlx migrate run` against `DATABASE_URL_UNPOOLED`	manual	Self-hosting Temper
6	Apply the `kb_saml_idp` row (`saml-setup.sh --apply-db`, or `psql` the `--sql-out` file by hand)	`saml-setup.sh` (`--apply-db`)	Self-hosting with SAML
7	First admin signs in via SAML → JIT `kb_profiles` row	manual	Self-hosting with SAML
8	SQL root step: gating team + first admin; VERIFY `has_system_access(<uuid>)` AND `is_system_admin(<uuid>)` both true	`system-bootstrap.sh --run-root`	Bootstrap an Org
9	`temper admin settings` (instance name, gating team)	`system-bootstrap.sh`	Bootstrap an Org
10	`temper team create everyone --auto-join-role watcher`	`system-bootstrap.sh`	Bootstrap an Org
11	`temper admin saml map-group` (after teams exist)	`saml-setup.sh` (emit / `--apply-db`)	Self-hosting with SAML
12	`temper admin saml verify`	`saml-setup.sh`	Self-hosting with SAML
13	Telos-charter: `temper cogmap create` → `temper cogmap reconcile` → bind `+everyone`	`system-bootstrap.sh`	Bootstrap an Org
14	(optional) UI deploy: confidential OIDC client, `API_BASE_URL`, `SESSION_SECRET`	manual	Self-hosting Temper
15	Verify: health, `temper auth login`, resource round-trip	manual	Self-hosting Temper
16	MCP readiness checkpoint (below) — before inviting MCP clients	manual	Self-hosting with SAML
—	→ team-self-cognition + Eve steward: DEFERRED	—	deferred

The expected path. The happy path is: run saml-setup.sh (step 3, default emit — writes the
env bundle consumed at step 4 and holds the kb_saml_idp SQL for step 6), do the two platform
steps by hand (4–5, Vercel env + deploy/migrate), then run system-bootstrap.sh --run-root
(steps 8–10 and 13) and re-run saml-setup.sh --apply-db (steps 6, 11, and 12 — applies the
kb_saml_idp row, maps the now-existing teams' IdP groups, and verifies against the live DB).
The numbered breakdown above is the reference an operator reads to understand what each script
does, or falls back to when running by hand. The two scripts are kept separate so
system-bootstrap.sh (steps 8–10, 13) works unchanged for Auth0/Okta-OAuth installs, which swap
steps 2–3, 6, and 11–12 for the Auth0 app registration documented in
Self-hosting Temper instead.

MCP readiness checkpoint

Do not declare MCP ready on a clean CLI login — the CLI uses the API audience and its own
callback, so it passes while every MCP client fails. Confirm, in order:

The MCP resource indicator is configured. MCP_AUDIENCE=https://<instance>/mcp wherever
/oauth/*, /mcp and /api are served, and redeployed.

Remote-client callbacks are registered under <mcp-client-id> in AS_CLIENTS — exactly
for an HTTPS callback, by path for a loopback one — with every existing entry preserved.

Protected-resource metadata and the unauthenticated challenge agree: the metadata's
resource is the MCP URL, and a bare POST /mcp answers 401 pointing at that document.

Dynamic registration echoes the intended callback rather than an empty list, and the
authorization server accepts a sign-in request for the MCP resource.

Login and one read-only tool call succeed from the MCP client itself, by a user with
approved system access (step 8).

Checks 3 and 4 are the four commands in
Self-hosting with SAML; 1 and 2 are
the configuration they verify.

Okta SAML app

In Okta, create a SAML 2.0 app and capture four values off it:
the SSO URL → idp_sso_url / --idp-sso-url
the signing certificate (PEM) → idp_cert_file / --idp-cert-file
the IdP entity id → idp_entity_id / --idp-entity-id
a group attribute statement exposing the user's groups → groups_attr / --groups-attr
(e.g. groups)
This note covers only what to pull out of Okta's app screen. The generic SAML-IdP side — the SP
ACS URL and entity id Temper's AS expects the IdP to send assertions to — is documented in
Self-hosting with SAML, and is the same regardless of which IdP you use.

Traps

Five ways this install silently misbehaves instead of failing loudly. Each has bitten a real
install; read this before step 8.

Admission and admin-ness are two independent rows, and each reads exactly one table.
has_system_access reads kb_principal_standing (an approved row); is_system_admin reads
kb_principal_governance. Neither reads team membership, and a fresh instance has neither row,
so it denies everyone — silently, as 403s rather than a startup failure. Write both rows
at step 8 and verify both predicates — has_system_access(<uuid>) and
is_system_admin(<uuid>) each returning true — before moving on, not just that the SQL ran.
One without the other is a silent half-state.
API_BASE_URL pointed at the UI's own public origin creates a self-proxy loop → 508 Loop Detected. It must be the API backend's own distinct origin — its *.vercel.app URL or a
dedicated api. subdomain — never the shared public domain the UI also serves
(Self-hosting Temper).
AS_CLIENTS unset rejects every /oauth/authorize call (fail-closed); INTERNAL_RECONCILE_SECRET
unset silently disables group provisioning while auth still works. The first fails loud, the
second doesn't — nothing errors, groups just never sync, so verify reconcile explicitly rather
than trusting a clean login (Self-hosting with SAML).
cogmap create / cogmap reconcile require an embed-feature temper binary. A
non-embed build fails with a clear requires the 'embed' feature error rather than a cryptic
one, but only at step 13, well after the rest of the install has succeeded — check this
up front instead (Bootstrap an Org).
Migrations are a deploy step, not a startup step — the API never auto-migrates. Run
sqlx migrate run against DATABASE_URL_UNPOOLED (step 5) yourself, and back up the database
first — there is no automatic rollback if a migration fails partway
(Self-hosting Temper).

Scripted vs. manual, and what's deferred

The expected path is the two scripts, not the numbered table read step-by-step — the table
is the reference an operator falls back to when a script needs debugging or the install deviates
from the happy path (SAML variant swaps, a failed step to re-run by hand, etc.).

Steps	Automated by	Status
8–10, 13	`system-bootstrap.sh --run-root`	Exists today
3, 6, 11, 12	`saml-setup.sh` (`--apply-db` for 6, 11, 12)	Exists today
1–2, 4–5, 7, 14–16	— (manual)	Platform-console and human-in-the-loop steps: provisioning Neon and the Okta app, setting Vercel env, deploying, the first SAML login, and the optional UI deploy/verify — none of these are things a script can safely do on an operator's behalf

Enterprise Install

Prerequisites#

What you end up with#

Four phases#

Environment matrix#

Must-match by construction#

The timeline#

MCP readiness checkpoint#

Okta SAML app#

Traps#

Scripted vs. manual, and what's deferred#

Further reading#