oz0 server start
Start the server.
For: Operators and developers looking up a command.
Start the server. With --dev, management, edge and an embedded Temporal run in one process on SQLite, which is meant for development and tests. Without it the server joins the cluster that server init created in PostgreSQL.
Usage
oz0 server start [flags]
Common flags
| Flag | Type | Default | Description |
|---|---|---|---|
--dev | bool | run in dev mode: one process, embedded Temporal on SQLite | |
--data-dir | string | ~/.local/share/orchestrator-zero | server data directory (with --dev: keep dev state here instead of a temporary directory) |
--db-file | file | a file (- for stdin) holding the PostgreSQL URL of the management database, such as postgres://oz0:PASSWORD@db:5432/oz0 (or set OZ0_DB); the URL can carry a password, so it never goes on the command line | |
--master-key-file | string | <data-dir>/master.key | master key file written by server init |
--advertise | string | first non-loopback IPv4 | address other servers and nodes reach this server on |
--san | strings | extra host name or IP for the edge certificate, such as a load balancer; repeatable | |
--name | string | host name | server name in the cluster |
--roles | string | manager,edge,temporal | the roles this server runs, comma-separated: manager, edge, temporal; all three run as one server, any other set runs them apart (see the docs on running the roles separately) |
--public-url | string | the address each browser used | how browsers reach the management port, such as https://oz0.acme.se, for identity providers' callback URL |
--oidc-config | string | a YAML file of identity providers for signing in to the web UI, saved at start (see the sign-in docs) | |
--temporal-backend | string | embedded | Temporal backend: embedded (in this server), external (a Temporal cluster you run) or cloud (Temporal Cloud) |
--temporal-address | string | the frontend's host:port: external or cloud, where {namespace} stands for a namespace's backend name (cloud default {namespace}.tmprl.cloud:7233), or with embedded, for an edge-only process, a temporal-role server's frontend | |
--dist-dir | folder | the dist folder next to this binary's folder | the folder make dist built, which the edge serves to new nodes |
Other flags
| Flag | Type | Default | Description |
|---|---|---|---|
--advertise-to-management | string | with --roles=edge: the HOST:PORT management dials for this edge's API (plugin builds, the web UI's calls, artifacts) when it is not the address nodes use, as behind NAT, a load balancer or a tunnel; default: the edge API address nodes get | |
--advisory-feed-every | duration | 24h | how often the advisory feed is fetched |
--advisory-feed-file | file | a file (- for stdin) holding the URL of an advisory feed the edge fetches for the vulnerability scan of installed plugins: an https URL of OSV entries (a JSON array or OSV's zip) or of the hub's advisory format; off by default (or set OZ0_ADVISORY_FEED); the URL can carry a token, so it never goes on the command line | |
--artifact-gc | mode | on | what the manager role does each hour with plugin artifacts that no installed version, rollout, gate or retained job references and that are older than 7 days: on (delete them), dry-run (log what it would delete) or off; one pass at a time across the cluster |
--ca-signer-command | command | a command that signs with the cluster CA's key outside the server, such as in an HSM or a KMS: "COMMAND public-key" prints the key as PEM, "COMMAND sign sha256" signs the digest on stdin (with --dev: when the dev cluster is created, too) | |
--call-binding | string | auto | how the edge treats a node's model call, admit or connection token that names a job without a call binding: required refuses it; when-present checks a binding only when a call carries one, and takes one without it only for a job whose task it handed that node lately; auto is when-present for a node that reports a runtime without call bindings and never showed them, required for every other node, and required for all by itself once none does (oz0 doctor warns while the edge takes calls without one) |
--cloud-endpoint | stringArray | replace a cloud's token endpoint for federated credentials, <name>=<URL> with name aws-sts, gcp-sts, gcp-iam or entra, such as a sovereign cloud's (https; http only to this machine); gcp-models or entra-models names a host that answers as the cloud's model API, which a federated provider's token may go to beside the cloud's own (a sovereign cloud's, a private endpoint's); entra-resources names one of your own Azure resources: an Entra provider needs its host named here or with entra-models, on the management servers and the edges, since any Azure customer can register a name on Azure's model hosts; repeatable | |
--codec-account-claim | string | a claim of the UI's access tokens that must hold --temporal-cloud-account; it binds them to this cluster, and is the binding to use with Temporal Cloud's keys: unbound, no access token is taken | |
--codec-allow-origin | strings | https://cloud.temporal.io | a browser origin that may call the edge's codec endpoint; repeatable |
--codec-assume-email-verified | bool | with --codec-jwks-url, take a UI access token without an email_verified claim as naming a verified address, for an identity provider that verifies or sets every address itself, such as Microsoft Entra ID; a claim that says anything but true is refused all the same | |
--codec-email-claim | string | email | the claim of the UI's access tokens that holds the user's email |
--codec-jwks-url | string | Temporal Cloud's, https://login.tmprl.cloud/.well-known/jwks.json | where the keys of the UI's access tokens are |
--codec-jwt-audience | string | an audience the UI's access tokens must name in aud; it binds them to this cluster only with --codec-jwks-url (an identity provider's own keys), since Temporal Cloud's tokens for every account can name the same one: unbound, no access token is taken | |
--codec-jwt-issuer | string | the issuer the UI's access tokens must name (needed with --codec-jwks-url; default with Temporal Cloud's keys: any they sign for) | |
--codec-jwt-max-age | duration | 12h0m0s | the longest time after its issue that a UI access token is taken |
--codec-jwt-unbound | bool | take any unexpired UI access token of a linked user that nothing binds to this cluster: another codec server the user's token reaches could replay it here | |
--connect-allow-net | strings | a network, such as 10.20.0.0/16, that connections' exchanges and token requests may reach, over http too, such as a GitHub Enterprise Server; public addresses over https are always allowed, others only in dev mode or when listed; repeatable | |
--edge-api-port | int | 7443 | edge HTTPS port for join, renew and the control stream |
--edge-temporal-port | int | 7233 | port where nodes reach Temporal through the edge |
--encrypt-payloads | bool | encrypt every payload with its tenant's key before it reaches Temporal: on by default in a cluster (=false turns it off, and oz0 doctor warns), off by default with --dev, always on with cloud | |
--erasure-ledger | file | <data-dir>/erasure-ledger.jsonl; off for none | the file management records every erasure in, outside the database, for server restore --erasure-ledger |
--eval-canary-period | duration | how often model canaries check their models (default 24h); a finding needs two periods in a row that differ | |
--ip | string | 127.0.0.1 with --dev, else 0.0.0.0 | IP address to bind listeners to |
--llm-anthropic-url | string | https://api.anthropic.com | Anthropic API address for the LLM gateway |
--llm-openai-url | string | https://api.openai.com | OpenAI-compatible API address for the LLM gateway |
--management-port | int | 8443 | management HTTPS port for the admin API |
--management-url | strings | with --roles=edge: management's address, such as https://mgmt.internal:8443, which the edge follows the registry from and reaches management's tables through; repeatable | |
--master-key-command | command | a command that unwraps the master key from --master-key-file when the file holds it wrapped, such as with an HSM or a KMS: "COMMAND unwrap" prints the key from the wrapped document on stdin, "COMMAND wrap" wraps one, "COMMAND describe" says what holds the wrapping key (see the docs on key commands) (or set OZ0_MASTER_KEY_COMMAND) | |
--metrics-listen | string | serve /metrics for Prometheus on this address over plain HTTP, such as 127.0.0.1:9464 (not authenticated: keep it private) | |
--notify-allow-net | strings | a private network, such as 10.20.0.0/16, that webhook notifications may post to; public addresses are always allowed, private ones only in dev mode or when listed; repeatable | |
--offline-dir | folder | an offline folder the edge serves its PyPI and npm mirrors from, and installs plugins only from (or set OZ0_OFFLINE_DIR); needs --dist-dir, which server dist pull --from fills with the folder's release | |
--otlp-endpoint | string | send traces over OTLP/HTTP to this URL, such as http://collector:4318: the server's own, and the nodes', which the edge relays | |
--otlp-header-file | stringToString | [] | a header for every trace export, as NAME=FILE: the header's value is what the file holds, such as a Kubernetes Secret's key mounted as a file (repeatable; or set OZ0_OTLP_HEADERS to name=value,name=value) |
--payload-db-file | file | with --roles=edge: a file holding the edge's own PostgreSQL URL for payloads and plugin artifacts (tables payloads, blobs and file_scopes; a role with grants on those is enough; optional with --payload-store) (or set OZ0_PAYLOAD_DB); the URL can carry a password, so it never goes on the command line | |
--payload-store | string | keep payloads and plugin artifacts in an S3-compatible bucket instead of PostgreSQL: s3://bucket[/prefix][?endpoint=https://host:port®ion=R&path-style=true&sse=AES256|aws:kms&kms-key-id=ID&ca-file=PATH] (for the edge role; every edge of a region must name the same bucket, and each region its own; see the docs on payload storage and on regions) | |
--payload-store-credentials-file | string | an AWS shared credentials file for --payload-store (read again when it changes); without it AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or ~/.aws/credentials | |
--plugin-source-allow-net | strings | a private network, such as 10.20.0.0/16, that the edge's fetches for plugin sources may reach: Git servers, OCI registries, forges, plugin indexes and package mirrors inside your network; public addresses over https are always allowed, private ones only in dev mode or when listed, and this machine's own addresses (inside a listed network too), its link and metadata services never; repeatable | |
--pprof | bool | also serve Go's runtime profiles at /debug/pprof/ on the --metrics-listen address, such as for load tests (not authenticated: profiles and goroutine dumps reveal internals, so keep the address private; the command line is not served) | |
--public-edge-url | string | https:// and the advertised edge API address | how browsers and other systems reach the edge's HTTPS port, such as https://oz0-edge.acme.se, for connections' callbacks and the webhook URLs they register |
--public-origin | strings | another address this cluster's edge API is reached at, such as https://agents.acme.se: nodes mark their agents' calls to it with the job they come from, so a call that loops back into the cluster is refused; repeatable | |
--queue-pools | shared | shared | how the task queues of a tenant's agents and flows are pooled: shared (one per node selector and label set across the tenant's plugins, which a node polls only while it runs every plugin of it) or plugin (one per plugin and label set: the fallback for a fleet whose nodes cannot poll shared pools yet, such as nodes whose supervisor predates them); management puts it in force at start, a change drains the jobs left on the old names, and every management server should get the same value |
--region | string | for the edge role: the region this edge belongs to, such as eu or us-east (lowercase letters, digits and dashes). It serves only the tenants pinned to that region and admits only nodes that joined through that region's edges; every edge of a region names the same Temporal backends and payload store. Empty is the unnamed region, as in a cluster that uses no regions | |
--release-channel | channel | its dist folder's release's, else stable | with --dev, the release channel a new dev cluster follows |
--role-sets-command | string | a command, run without a shell, that prints the role set on stdout; if it fails, the last valid set stays in force | |
--role-sets-file | string | a role set (JSON or YAML, version oz0-roles/v1) whose roles join the built-in ones; read at start and every --role-sets-refresh | |
--role-sets-refresh | duration | 5m, at least 10s | how often the role set is read again |
--role-sets-timeout | duration | 10s, at most 5m | how long --role-sets-command may take |
--routine-output-allow-net | strings | a private network, such as 10.20.0.0/16, that routines' outputs may post to; public addresses are always allowed, private ones only in dev mode or when listed; repeatable | |
--sandbox-floor | bool | with --dev: run shell and write harness sessions only on sandbox tier-1 nodes or a node a tenant admin opted out, as a cluster does (a dev server otherwise runs them on any node, without a sandbox where it has no tier 1, and says so) | |
--secret-stores | string | for the edge role: a YAML file of secret store processes that tenant secrets may reference (store:<store>/<path>), with the tenants and path prefixes each offers; see the docs on secrets | |
--secrets-key-command | command | a command that unwraps the secrets key from --secrets-key-file when the file holds it wrapped: "COMMAND unwrap" prints the key from the wrapped document on stdin, "COMMAND wrap" wraps one, "COMMAND describe" says what holds the wrapping key (see the docs on key commands) (or set OZ0_SECRETS_KEY_COMMAND) | |
--secrets-key-file | string | the edge role's private key that tenant secrets are sealed to, so that management cannot open them (make one with: oz0 server secrets-key create) | |
--smtp-addr | string | the SMTP relay notifications are mailed through, host:port such as smtp.acme.se:587; email is off without it | |
--smtp-ca-file | string | the system's roots | a PEM file of the CA the SMTP relay's certificate chains to, for a relay with a private CA |
--smtp-from | string | the address notifications are mailed from, such as [email protected] | |
--smtp-password-file | string | a file with the SMTP relay's password (never a flag's value) | |
--smtp-sender-domains | strings | a tenant and a mail domain, such as acme=acme.se, that this tenant's agents' mail may be From through the relay when its sender is in that domain; any other goes From --smtp-from with the tenant's sender as Reply-To; repeatable | |
--smtp-tls | string | starttls | how mail to the relay is encrypted: starttls (port 587) or tls (port 465); the relay's certificate is always verified |
--smtp-user | string | the SMTP relay's user name, with --smtp-password-file; sent over TLS only | |
--temporal-api-key-dir | string | directory with one API key file per backend namespace, named like it (such as acme.a1b2c), read again when they change | |
--temporal-api-key-env | string | environment variable holding an API key for every namespace | |
--temporal-api-key-file | string | file holding an API key for every namespace, read again when it changes | |
--temporal-backends-file | string | YAML file naming more Temporal backends (external or cloud) that tenants can be on or move to; the backend the flags above name is then called default | |
--temporal-cloud-account | string | cloud: the account ID; a tenant's namespace is <namespace>.<account> unless an admin mapped it (tenant temporal-namespace) | |
--temporal-create-namespaces | bool | external: create missing namespaces and search attributes instead of only checking them | |
--temporal-frontend-membership-port | int | 6933 | Temporal frontend membership port |
--temporal-frontend-port | int | 7234 | Temporal frontend gRPC port |
--temporal-history-membership-port | int | 6934 | Temporal history membership port |
--temporal-history-port | int | 7235 | Temporal history gRPC port |
--temporal-log-level | string | WARN | log level for Temporal's own logs |
--temporal-matching-membership-port | int | 6935 | Temporal matching membership port |
--temporal-matching-port | int | 7236 | Temporal matching gRPC port |
--temporal-port | int | 7234 | dev mode: port of the embedded Temporal frontend |
--temporal-tls | bool | external: TLS to the frontend (always on with cloud) | |
--temporal-tls-ca-file | string | PEM file of the CAs to trust for the frontend instead of the system's | |
--temporal-tls-cert-file | string | client certificate for mTLS to the frontend, read again when it changes | |
--temporal-tls-key-file | string | the client certificate's key, read again when it changes | |
--temporal-tls-server-name | string | the address's host | name to check in the frontend's certificate |
--temporal-ui-port | int | 8233 | dev mode: port of the Temporal web UI (0 disables it) |
--temporal-ui-url | string | https://cloud.temporal.io with cloud | where Temporal's UI is, for links to jobs |
--temporal-worker-membership-port | int | 6939 | Temporal worker membership port |
--temporal-worker-port | int | 7239 | Temporal worker gRPC port |
--trusted-proxy | strings | a reverse proxy in front of this server, such as a Kubernetes Ingress controller, by its address or a network only proxies hold (10.42.7.0/28, never the pods' whole network, where any pod could then name its own client): a request from it counts as the client X-Forwarded-For names, read from the right past the trusted proxies, for what is held back per address (failed sign-ins, device sign-ins started, unknown API keys) and the sessions page; without it, every client behind a proxy counts as the proxy's one address; repeatable |
Inherited flags
| Flag | Type | Default | Description |
|---|---|---|---|
--context | string | $OZ0_CONTEXT or <config dir>/orchestrator-zero/context.json | CLI context file written by server init |
--log-level | string | info | log level: debug, info, warn or error |
See all oz0 commands and the global flags.