Run the control plane

Safe local first success#

Prerequisites: macOS or Linux; `git`, `make`, and `curl`; the Rust toolchain version pinned by the `Dockerfile` builder image; access to the private wisent-ai/most repository; a free loopback address and port, which `MOST_BIND_ADDR` names as host:port. No local onboarding path requires production credentials.

git clone https://github.com/wisent-ai/most.git
cd most
export MOST_BIND_ADDR=<loopback host>:<free port>
AUTH_BYPASS=1 MOST_COMPOSITION=none make run-dev
# expected log: most-server listening on http://<MOST_BIND_ADDR>

Observe the result#

In `none` composition, messaging mutation routes have no executable transport and return a capability error rather than contacting a provider. Do not interpret liveness as message-delivery readiness. Stopping with Ctrl-C leaves no background service and no Most database or provider resource. A supervisor's SIGTERM (launchd or systemd) drains the server the same way Ctrl-C does: its backends are stopped and its secret caches cleared. A signal listener the server cannot install is logged at error naming that signal and is never taken for it; the server keeps serving until the other signal arrives or its process is ended.

export MOST_BASE_URL=http://<the address terminal 1 listens on>
curl --fail --silent "$MOST_BASE_URL/healthz"
# answer of a source build (no revision stamped):
# {"status":"ok","version":"0.1.1","source_revision":null,
#  "backends":"none","unavailable":[],"composition":"none"}

Configuration and state#

• Configuration comes from process environment and finite Skarbiec capability IDs; `.env.example` documents inputs. Unknown compositions are invalid and must be corrected, never silently downgraded.
• PostgreSQL is required by the `prod` composition; migrations live in `migrations/` and are applied by `most-migrate` under one owner.
• Runtime code receives scoped capability handles, not committed secret values. API, database, attachment-signing, remote-worker, wisent-integrations and Apple-identity credentials are separate contracts.
• Skarbiec capability redemption consumes its newline-delimited JSON control record and the exact secret length declared by the broker, followed by EOF. Most adds no guessed control-line, signing-key-file, request or secret-size ceiling. Lengths that cannot fit the platform or be allocated, incomplete bodies and trailing data fail explicitly. Workload identifiers follow the broker's exact-token contract: nonempty and free of NUL, CR and LF.
• `MOST_BIND_ADDR` is required: no native listen address is assumed, and a missing one stops `most-server` before any backend starts. The container image declares it itself, on every interface at the port its `Dockerfile` names, and requires deployment-owned network controls. `most-cli` and `most-mcp` require `MOST_BASE_URL` and refuse with `MOST_BASE_URL is not set` without it.
• Optional integration startup failures degrade that integration; authoritative-storage failure prevents production startup.
• Production database initialization uses MOST_DATABASE_URL when explicitly supplied, otherwise the Stado fleet database most. A present empty, whitespace-only or non-Unicode URL refuses by setting name instead of selecting another database; only absence selects the fleet. Connection or fleet-resolution failures stop production startup with their actual cause.
• Deployment supplies `PUBLIC_BASE_URL`, network placement, storage, and capability identifiers. Production topology, credentials, provider accounts, DNS, and database projects stay outside the repository.

Observability and release discipline#

`/healthz` exposes version, source revision, composition, and registered backends; structured logs record routing and dependency classifications without secret material.

Most signs Skarbiec redemption requests over the capability id, nonce, workload id, redeem operation and empty authorization id. A finite capability is consumed at process startup; issue a fresh unbound capability for a new process. An incorrect API bearer returns 401, while a credential the server failed to redeem produces 503. Connection errors name the socket and failed operation in the startup log; a broker denial requires its audit record.

Schema changes require explicit forward, recovery, and rollback analysis. Once a release exists, production uses the immutable artifact and digest — never main, a moving image tag, or an uncommitted checkout.

Database migrations#

Run most-migrate apply --migrations-dir migrations from the immutable release. It uses the same database selector as the server: an explicit MOST_DATABASE_URL for standalone PostgreSQL, otherwise the Stado/Skarbiec fleet route. The retired --dsn and --adopt-legacy-public options are not supported.

Each file runs in a runner-owned transaction with SET LOCAL search_path and its migration-history record, so that file and record commit together or neither does. Repeating the command skips recorded names. --schema selects an isolated target schema; the server reads most. Use release migration files without their own BEGIN/COMMIT or fixed schema.

Invalid schema names and unknown or incomplete arguments refuse before connecting. Migration directory enumeration and SQL-file metadata failures name the path and filesystem cause before database selection; unreadable entries and nonregular .sql paths are not silently skipped. Invalid explicit database declarations do not fall through to the fleet. Reading a SQL file names its path and cause. A migration execution error states that the failed file was not committed and earlier successful files remain committed.

The standalone database journey is node tests/migrations/cli.mjs. Declare MOST_DATABASE_URL for a dedicated qualification database, MOST_TEST_DATABASE_PURPOSE=isolated-qualification, MOST_TEST_MIGRATE_BIN, MOST_TEST_PSQL_BIN, MOST_TEST_SOURCE_REVISION, MOST_TEST_SUCCESS_EXIT and MOST_TEST_FAILURE_EXIT. It checks the candidate stamp, applies release migrations into a unique schema, reads persisted history, repeats application, exercises invalid configuration and SQL-file refusals, and verifies per-file rollback without erasing earlier commits. Cleanup removes only that schema and checks its absence; command/output/exit evidence remains under .build/migrations. This is not fleet, provider or Desktop qualification.

Candidate build contract#

make release-quality runs Clippy with warnings denied and the Rust formatting check. It does not run a migration journey or provider qualification. make release-build requires WISENT_SOURCE_COMMIT or STADO_SOURCE_REVISION, stamps that revision into the executables, and stages all five binaries plus migrations/ under WISENT_OUTPUT_DIR, or the checkout's .wisent-output directory when no output is declared.

A successful source gate or staged package does not prove database migration, bootstrap provisioning, Apple activation, provider delivery or desktop behavior. Qualify the candidate through those real interfaces and retain their observed state and command results separately.

The private source dependencies require their declared read-only source credentials. The release-quality target itself does not fetch or configure those credentials.

Submit an immutable commit with stado release submit --source . --commit FULL_SHA --version VERSION --channel candidate, VERSION being the one `[workspace.package]` of `most-rs/Cargo.toml` declares. A candidate package is not a running service. Production qualification still needs real authenticated API access, PostgreSQL persistence, provider sends and receipts, webhook delivery and the desktop journey.