Server configuration

cronoq-server reads one TOML file, given with --config <path> (or the CRONOQ_CONFIG environment variable). Without a file it starts with defaults: one default pool, in-memory state, no auth tokens and listeners on 127.0.0.1 only. Unknown keys are rejected and every value is validated at startup, so typos and out-of-range numbers fail fast instead of at runtime.

cronoq-server --config cronoq.toml --check   # validate and exit
cronoq-server --config cronoq.toml           # run
cronoq-server --print-proto                  # print the gRPC API definition

The log level comes from RUST_LOG (default info).

An annotated example lives in deploy/cronoq.example.toml; it is the configuration baked into the container image.

Durations are seconds (floats). They must be finite and between their minimum and one year.

[server]

[server.tls]

Optional. Enables TLS on both the gRPC and the HTTP listener (the optional metrics listener stays plain HTTP). Files are read once at startup; a missing file is reported with its path.

[server.peer_tls]

Optional. How this server verifies other shards' https:// endpoints when it forwards calls (Sharding).

[server.grpc_web]

Optional. Serves gRPC-Web for browser clients on the gRPC listener, alongside native gRPC. Without this table the listener speaks only HTTP/2 gRPC.

The origin list only controls which pages a browser lets call the server; every call still needs credentials with the right role, as over native gRPC.

[auth]

Callers authenticate with authorization: Bearer <token> (gRPC metadata or HTTP header), or with a client certificate mapped to a role. Roles:

/healthz and /readyz never need credentials.

[[auth.tokens]]

[[auth.tokens]]
token_env = "CRONOQ_CLIENT_TOKEN"
role = "client"
pools = ["llm"]            # optional

Exactly one of token / token_env is required. Tokens must be at least 16 characters (the server warns below 32; use 32+ random characters, e.g. openssl rand -hex 24) and unique. Tokens are stored as SHA-256 digests and compared in constant time; Debug output and logs never contain them.

[[auth.certs]]

Map mTLS client certificates to roles by an exact DNS subject alternative name. Requires server.tls.client_ca.

[[auth.certs]]
dns_name = "worker-1.internal"
role = "worker"
pools = ["gpu"]            # optional

A bearer token, when present, takes precedence over the certificate.

[store]

[store]
kind = "postgres"
url_env = "DATABASE_URL"
keep_finished_s = 604800

The server refuses to start if the schema already holds cronoq tables owned by a role other than the one it connects as (or a superuser). Prefer a dedicated schema that only the server's role can create objects in (see Security hardening).

[limits]

Request and resource limits. The defaults are safe for a shared deployment; every key is optional.

Strings in task specs (keys, kinds, tags, resource names, worker messages) must not contain NUL characters; worker failure messages are sanitized (NUL replaced, cut at 8 KiB) instead of rejected.

[[pools]]

Server pools are served by remote workers: a pool's capacity is the number of slots its connected workers registered. Defaults to a single pool named default.

[[pools]]
name = "llm"
max = 200
lease_ttl_s = 120
overflow = "reject"
retry = { max_attempts = 5, initial_backoff_s = 2, max_backoff_s = 120 }

scaler

retry

[[resources]]

Shared limits that tasks request by name (resources = {"openai": 1}).

[[resources]]
kind = "token_bucket"
name = "openai"
rate = 50
burst = 100

[[resources]]
kind = "semaphore"
name = "gpu"
permits = 8

[[shards]]

Optional. Splits the pools between shards, each served by its own leader and standbys with a store of its own (Sharding). Every shard's servers use the same list and pick their own with server.shard.

With shards, each shard keeps its own state: a Postgres store.schema must contain {shard} (default cronoq_{shard}), and a SQLite store.path must contain {shard}; the server fills in its shard's name. Each resource belongs to one shard (its shard key), because shards do not share counts: a resource shared by two shards would have its full capacity in each. [limits] apply to each shard separately.

[outputs]

Recent outputs and task records, used by Wait/Get after a task finished. With a durable store (postgres or sqlite), outputs that are no longer cached are read from the database.

Validation summary

--check (and every startup) rejects:

• unknown keys, duplicate pool or resource names, invalid names;
• non-finite, negative or out-of-range numbers (durations, fractions, multipliers, rates, tenant weights), and a pool min above its max;
• [[auth.tokens]] entries without exactly one of token/token_env, duplicate literal token values, pool allow-lists naming unknown pools;
• [[auth.certs]] without server.tls.client_ca;
• server.grpc_web.allowed_origins that is empty, has more than 64 entries, or holds anything other than exact origins;
• both store.url and store.url_env;
• [[shards]] with duplicate names, numbers or endpoints, unknown pools, pools in no shard or in two, a missing or unknown server.shard, a store namespace without {shard}, or a resource without a known shard.

Startup also rejects the following, which --check does not test because they depend on the environment:

• a token_env variable that is not set;
• tokens shorter than 16 characters, and duplicate tokens (including tokens read from token_env);
• non-loopback listeners with no credentials, unless insecure_no_auth is set.