opschain server start

Included from Basic tier

Start the OpsChain server in the foreground: HTTP(S) API, data store, scheduler, runner protocol and log streaming, as one process. The command prints the listen URL once the socket is open —

opschain server start
opschain server listening on http://127.0.0.1:8443

— then serves until SIGTERM or SIGINT. The first signal begins a graceful shutdown (drain runners and parked polls, stop the scheduler, close the store) with a 30-second grace period; a second signal abandons the grace period and stops hard.

Configuration layering

Configuration resolves lowest-to-highest:

1. $OPSCHAIN_HOME/server/config.yaml and server/keys.env — written by opschain server configure. Print the annotated key catalog with opschain server configure and its template flag (see opschain docs cli/server-configure) rather than guessing key names; the running server also serves the same catalog at GET /api/admin/config.
2. Environment variables — the keys.env names (OPSCHAIN_TOKEN_SECRET_KEY, OPSCHAIN_PRIMARY_KEY, OPSCHAIN_KEY_DERIVATION_SALT), OPSCHAIN_LDAP_PASSWORD, OPSCHAIN_SERVER_ADMIN_TOKEN, OPSCHAIN_ENABLE_BASIC_AUTH, OPSCHAIN_CLUSTER_NAME, the OPSCHAIN_LDAP_* overlay and any OPSCHAIN_VAULT_* values.
3. Flags — a flag explicitly passed on this invocation wins over the file value even when the flag's value equals its default.

Flags

Flag	Meaning
--listen <host:port>	Listen address; port 0 picks a free one. Default 127.0.0.1:8443 (the config file's listen when set).
--store <path or DSN>	The data store: a SQLite database path, or a postgres:// DSN. Parameters left out of the DSN fall back to the standard PG* environment variables. Default: <opschain home>/opschain.db.
--tls-cert <file>	TLS certificate file. Set both TLS flags to serve HTTPS; without them the server speaks plain HTTP (loopback/dev).
--tls-key <file>	TLS private key file.
--admin-token <token>	Static admin bearer token admitted to the admin service on a store WITHOUT the auth stack, where it is the sole guard (default off). On PostgreSQL with a resolvable token secret the lane is retired: the token is refused with the typed ERROR_REASON_ADMIN_TOKEN_RETIRED answer, a boot notice says so, and admin surfaces authenticate user sessions and API keys through the /admin RBAC gate. Falls back to OPSCHAIN_SERVER_ADMIN_TOKEN when the flag is empty.
--confirm-eula	Accept the LimePoint EULA on a fresh installation's first start (read it with opschain eula). Recorded once, then inert.
--dev-run-seam	Mount the admin-gated run-creation seam under /admin/e2e/runs (interim, superseded by the v1 API).
--lease-ttl <d>	Job lease TTL before a silent runner's step fails as runner_lost (default 3m).
--poll-window <d>	Long-poll park window for runner job acquisition (default 50s).
--replica-retention <d>	How long a dead scheduler replica's membership row stays visible before the leader reaps it (default 24h).

Global flags that matter here: --home picks the server home the configuration is read from; --log-file <path> writes JSON log lines to a rotated file instead of stderr. When the config file's logging: block names a file, file logging engages without the flag; the flag overrides the path while the rotation settings (size, age, backup count) always come from the logging: block.

The EULA gate

A fresh installation refuses to start until the LimePoint EULA is accepted: interactively (on a terminal the agreement is printed and the word accept is required), with --confirm-eula, or with the config file's eula: accepted: true. Acceptance is recorded once per installation and a later EULA revision never re-gates.

Exit codes

Code	Meaning
0	Clean shutdown after a signal.
1	The server failed to configure, listen or serve (the error is printed).
2	Usage error — unknown flag or stray argument.

See also

• opschain docs cli/server-configure — write the configuration this command reads.
• opschain docs cli/server-backup and opschain docs cli/server-restore — embedded-deployment backups.
• opschain docs cli/eula — read the agreement the first start requires.
• opschain learn 0.1 — install and first contact.