Flags are written --name value or --name=value. Where a flag names an environment variable, the variable is read when the flag is not given.

Listening

Where the API is served. An empty --http runs a worker-only node.

--http

string · default :8448

HTTP listen address ($GENROC_HTTP; empty to disable)

--pprof

string

pprof listen address, e.g. localhost:6060 (empty to disable)

Database

SQLite by default; --pg switches to PostgreSQL.

--db

string · default genroc.db

SQLite database file path ($GENROC_DB)

--pg

string

PostgreSQL DSN, e.g. postgres://user:pass@host/db ($GENROC_PG). When set, --db is ignored.

--pg-max-open-conns

int · default 50

PostgreSQL connection pool size, and with it the group-commit batch-width ceiling: only transactions in flight together coalesce into one WAL flush, so the pool bounds how many ever do. Size a worker fleet so workers*pg-max-open-conns stays under the server's max_connections. Ignored for SQLite.

Durability

What is flushed to disk before a write is acknowledged.

--durability

string · default essential

How much of the write path is flushed to disk before it is acknowledged. essential (default) flushes what cannot be replayed - work handed in from outside, and only_once tasks - and lets ordinary task progress replay after a power cut, which the at-least-once contract already allows. terminal additionally flushes process ends, so a finished process cannot rewind to running. strict flushes every commit, so no completed task ever repeats. none flushes nothing: a crash of the process loses nothing, a power cut can lose the last moments of any work, only_once included - for tests and throwaway environments. Below strict, a client polling an instance can see a state it already passed after an unclean shutdown.

--sqlite-fullfsync

boolean

Use F_FULLFSYNC on macOS, where plain fsync(2) returns before the drive flushes its write cache, so a write is not power-loss durable without it. On by default on macOS; costs ~4ms per flushed commit on an M1. No effect on other platforms or for PostgreSQL.

--pg-commit-delay

int

Hold each PostgreSQL WAL flush back by this many microseconds so more commits coalesce into it (PostgreSQL commit_delay, set per session). Costs no durability - every commit is still flushed before it is acknowledged - and Postgres skips the delay unless commit_siblings (default 5) transactions are open, so narrow workloads are unaffected. Throughput peaks well below the flush latency and drops past it: on a 4ms F_FULLFSYNC disk 500us was the best value measured and 10000us was 26% worse than doing nothing. The gain itself is workload- and load-dependent (measured between +3% and +33% for the same 500us on the same machine), and shows up mainly as steadier throughput under contention rather than a higher ceiling. Measure on your own storage; 0 (the default) disables. Requires a superuser connection. Ignored for SQLite.

Authentication

Off by default; --auth turns it on. Machines use tokens; people reach the API through genroc-ui.

--auth

boolean

Require a credential on every API request ($GENROC_AUTH=true): a genroc_sk_* token in Authorization: Bearer, or a JWT when --jwt-secret-file is set. Off by default, where every request is treated as an operator.

--seed-tokens-file

path

In token mode, credentials to store, from the file at path ($GENROC_SEED_TOKENS_FILE): one label=perms=secret per line, e.g. "ci=deploy,read=genroc_sk_..." (secrets from genctl token generate); lines starting with # are comments. Each is stored if absent and ignored if present, so a restart is a no-op and rotation is additive.

--jwt-secret-file

string

Path to the HMAC key genroc-ui signs with ($GENROC_JWT_SECRET_FILE); $GENROC_JWT_SECRET holds it inline instead. With --auth, JWTs signed with it are accepted beside genroc_sk_* tokens: people reach the API through genroc-ui, which resolves their permissions and mints a token carrying them.

--jwt-issuer

string

The iss claim a token must carry ($GENROC_JWT_ISSUER); defaults to genroc-ui. Pinned: unpinned, any issuer holding the secret is accepted.

--jwt-audience

string

The aud claim a token must carry ($GENROC_JWT_AUDIENCE); defaults to genroc. Pinned: unpinned, a token minted for another application verifies here too.

--jwt-leeway

string

Clock skew allowed on exp/nbf ($GENROC_JWT_LEEWAY); default 30s. A fixed zero fails on real clusters.

Engine

How instances are claimed and advanced.

--poll

int · default 500

Engine poll interval in milliseconds

--max-concurrent

int · default 200

Max instances advanced concurrently. Too high overwhelms the DB/lease renewer and in-flight work starts losing its leases (lease_lost audit entries); raise --lease-duration or the DB connection pool before raising this much further.

--lease-duration

duration · default 10s

How long a claimed instance is leased to a worker before another worker may reclaim it on crash

--lease-renew-interval

duration · default 3s

How often a worker re-stamps its leases; must be comfortably shorter than --lease-duration

--shutdown-grace

duration · default 15s

On SIGTERM, how long work already running may finish before it is abandoned; new work stops being claimed at once. Abandoned work is written nowhere and re-runs elsewhere once its lease lapses, as after a crash. Give the container at least this long to stop.

--immediate-retries

boolean

Disable retry backoff (retries fire instantly); for testing only

Logging

Console output and the per-instance audit trail.

--log

string · default info

Log level: debug, info, warn, error

--log-mode

string · default basic

Console output: basic (no data body), detail (+ data body), or json (one JSON object per line); same modes as genctl logs. Times are UTC, so a fleet's logs collate; genctl renders the reader's local zone

--log-payloads

boolean · default true

Record the payload an audit event is about (process/task input and output, request/response bodies) on its log row. Stored whole: a large value moves into the object store like any other, never cut short.

--log-payload-max

int · default 1048576

Largest payload a log row records, in bytes. A larger one is left out, not cut short, and the row's meta says so with payload_omitted_bytes. 0 = no limit.

--log-retention

duration · default 168h0m0s

Delete per-instance audit logs older than this; 0 = keep forever

--instance-retention

duration

Delete a process, with its children and logs, once it concluded (completed, failed or cancelled) longer ago than this; 0 (default) = keep forever. A deleted instance answers 404, so read results and retry failures within it.

Objects

Large values kept out of the instance row.

--object-grace

duration · default 1h0m0s

How long a released large value stays fetchable by a reference already handed out. A read hands out references and fetching them is a second call, so the data can move on in between; this is the window in which that cannot lose. Raise it for slow consumers, lower it for processes that churn big values in a loop.

Other

--version

boolean

Print the version and exit.

genroc token

genroc token — credential management against the database.

  genroc token create --perms <list> [--label <name>] [--db path | --pg dsn]
  genroc token list                                   [--db path | --pg dsn]
  genroc token revoke <id>...                         [--db path | --pg dsn]

Permissions: admin, deploy, operate, read, worker.

This works without the server running and without a credential — it needs only access to the
database, which is the correct root of trust for a break-glass path. Day to day, use
`genctl token`, which goes over the API.