Settings
Every setting is an environment variable. A command-line argument (--ORC_PORT=9000) also works, as does an orchestrator.json or orchestrator.yml in the working directory. Later sources win. The console's Settings page shows the effective value of each and where it came from, with secrets masked.
A missing or invalid required setting stops the Orchestrator at start with exit code 0xBAD (2989, which a shell reports as 173).
Console and landing page
| Variable | Default | Meaning |
|---|---|---|
ORC_ADMIN_PASSWORD |
none, required | Password of the management console, at least 8 characters. Optional when ORC_ROLE=node. |
ORC_ADMIN_USER |
admin |
Console user name. |
ORC_TITLE, ORC_SUBTITLE |
Curiosity, none |
The landing page's heading. |
ORC_HIDE_FROM_SEARCH_ENGINES |
false |
Ask crawlers to leave the server and every workspace out. See Search engines. |
ORC_LANDING_SIGN_IN |
false |
The landing page asks for one of the Accounts before it lists the workspaces, and every workspace opens signed in as it. See Accounts and console users. |
ORC_SESSION_HOURS |
12 |
How long a sign-in lasts: the console's and the landing page's. |
ORC_API_TOKEN |
none | Enables Authorization: Bearer <token> on the management API. At least 24 characters. |
Server
| Variable | Default | Meaning |
|---|---|---|
ORC_STORAGE |
./storage |
The database (db/), the self-signed certificate, Let's Encrypt files and temporary uploads. |
ORC_PORT |
8080, or 443 with a certificate |
Listening port. |
ORC_PORT_LOCAL |
8080 (HTTPS only) |
Extra plain HTTP port. Loopback only, or every address with ORC_REDIRECT_TO_HTTPS. 0 disables it. |
ORC_RESTRICT_LOCALHOST |
false |
Listen on loopback only. |
ORC_PUBLIC_ADDRESS |
none | The public URL. Named in the self-signed certificate, and the redirect target for ORC_MANAGEMENT_HOST. |
ORC_MANAGEMENT_HOST |
none | Serve the console and its API only on this host name. See Security. |
ORC_SUBDOMAIN_ROUTING |
true |
Also serve each workspace at <slug>.<host>/, one subdomain level. |
ORC_WWW_FOLDER |
./wwwroot |
The front-end files. |
ORC_MAX_BODY_SIZE |
512 MB | Largest request body, for uploads into a workspace. |
ORC_LOG_LEVEL |
Information |
The log level. |
HTTPS
| Variable | Default | Meaning |
|---|---|---|
ORC_CERT_FILE |
none | A PFX, a CER or a PEM certificate. |
ORC_CERT_FILE_PRIVATE_KEY |
none | The PEM private key, when ORC_CERT_FILE is a PEM. |
ORC_CERT_PWD |
none | Password of the PFX, or of an encrypted PEM key. |
ORC_CERT_SELF_SIGNED |
false |
Generate a self-signed certificate (5 years, RSA 2048) into ORC_STORAGE/self.pfx and reuse it. |
ORC_REDIRECT_TO_HTTPS |
false |
Redirect HTTP to HTTPS. |
ORC_USE_HSTS |
false |
Send HSTS headers. |
ORC_PORT_HTTP |
80 with Let's Encrypt, otherwise 0 |
Public plain HTTP port next to HTTPS. It answers ACME HTTP-01 challenges and redirects everything else to HTTPS with a 307. |
Let's Encrypt
| Variable | Default | Meaning |
|---|---|---|
ORC_LETSENCRYPT |
false |
Get certificates from Let's Encrypt (or ORC_LETSENCRYPT_SERVER) and renew them. |
ORC_LETSENCRYPT_EMAIL |
none | Required with it. The account address, which gets expiry warnings. |
ORC_LETSENCRYPT_ACCEPT_TERMS |
false |
Required to be true with it. Accepts the subscriber agreement. |
ORC_LETSENCRYPT_DOMAINS |
hosts of ORC_PUBLIC_ADDRESS and ORC_MANAGEMENT_HOST |
The Orchestrator's own host names, comma separated, on one certificate. |
ORC_LETSENCRYPT_WORKSPACES |
true (with ORC_SUBDOMAIN_ROUTING) |
A certificate per workspace for <slug>.<host of ORC_PUBLIC_ADDRESS>. |
ORC_LETSENCRYPT_STAGING |
false |
Let's Encrypt's staging server: untrusted certificates, much higher rate limits. |
ORC_LETSENCRYPT_SERVER |
none | Another ACME directory URL, for a private CA. |
ORC_LETSENCRYPT_ISSUERS |
none | PEM files of that CA's root and intermediates, comma separated. |
Docker and workspaces
| Variable | Default | Meaning |
|---|---|---|
ORC_DOCKER_ENDPOINT |
unix:///var/run/docker.sock (Windows: npipe://./pipe/docker_engine) |
The Docker Engine endpoint. Also tcp://host:2375. |
ORC_DOCKER_NETWORK |
curiosity-orchestrator |
The bridge network the workspaces join. Created if missing. |
ORC_CONTAINER_ACCESS |
auto |
port publishes each workspace on 127.0.0.1:<random>. network reaches it by container name. auto picks network inside a container and port otherwise. |
ORC_CONTAINER_PREFIX |
curiosity- |
Prefix of container and volume names. |
ORC_DEFAULT_IMAGE |
curiosityai/curiosity:latest |
The image for new workspaces. |
ORC_DEFAULT_MEMORY_LIMIT, ORC_DEFAULT_CPU_LIMIT |
0 (none) |
Defaults for new workspaces, in MB and cores. |
ORC_INSTANCE_PORT |
8080 |
The port Studio listens on inside the container. |
ORC_INSTANCE_NOFILE |
0 (daemon default) |
Open-file limit for workspaces. Curiosity's own deployments use 500000. Some hosts do not allow raising it. |
ORC_INSTANCE_ENV_<NAME> |
none | Passed to every workspace as <NAME>, for example ORC_INSTANCE_ENV_MSK_LICENSE. The console's global environment and a workspace's own variables win over it. |
Lifecycle
See Sleep and wake.
| Variable | Default | Meaning |
|---|---|---|
ORC_IDLE_TIMEOUT_MINUTES |
60 |
Stop a workspace after this long without traffic. |
ORC_MAX_KEEP_WARM_DAYS |
7 |
Longest keep warm, 0 to 7 days. |
ORC_ALLOW_ALWAYS_ONLINE |
true |
Whether a workspace may be kept warm for good. false refuses it, and workspaces set earlier sleep again. |
ORC_MAX_RUNNING_INSTANCES |
0 (no limit) |
Most workspaces running at once. |
ORC_MIN_FREE_MEMORY_PERCENT |
10 |
Below this share of free host memory, stop the least recently used workspace. 0 is never. |
ORC_START_TIMEOUT_MINUTES |
15 |
Give up on a start that does not become ready. |
ORC_STOP_TIMEOUT_SECONDS |
600 |
Grace period for a stop: Studio stores its graph on the way down. |
ORC_STATS_INTERVAL_SECONDS |
15 |
Resource sampling interval. The charts keep the last 240 samples. |
Fleet
| Variable | Role | Default | Meaning |
|---|---|---|---|
ORC_ROLE |
all | standalone |
standalone, central or node. |
ORC_FLEET_SECRET |
central, node | none | A shared secret, at least 32 characters, that nodes can join with instead of a join token. |
ORC_FLEET_AUTO_APPROVE |
central | false |
Nodes joining with the shared secret start active. |
ORC_FLEET_PROXY |
central | true |
Visitors reach the nodes' workspaces through the central. |
ORC_FLEET_POLL_SECONDS |
central | 15 |
How often each node's state is read. |
ORC_FLEET_ROTATE_DAYS |
central | 90 |
Rotate each node's secret this often. 0 is never. |
ORC_FLEET_HOST |
central | none | Answer /api/fleet/* only on this host name. |
ORC_CENTRAL_ADDRESS |
node | none | The central to join. |
ORC_CENTRAL_PIN |
node | none | sha256:… key pin of the central. |
ORC_JOIN_TOKEN |
node | none | A join token from the central's Nodes page. Used once. |
ORC_NODE_NAME |
node | host name | The name the central shows. |
ORC_NODE_ADDRESS |
node | guessed | The address the central calls the node on. Also reported on every check-in. |
ORC_NODE_LABELS |
node | none | zone=eu-1,gpu, for placement. |
ORC_NODE_ENROLLMENT_CODE |
node | random | Choose the enrollment code instead of reading it from the log. |
ORC_NODE_ALLOW_DIRECT |
node | true |
false serves the node's workspaces only to traffic the central forwarded. |
Command-line flags
| Flag | Effect |
|---|---|
--leave-fleet |
Run with the Orchestrator stopped. Makes a node forget its central. |
--<NAME>=<value> |
Sets any setting above, for example --ORC_PORT=9000. |
Install script variables
ORC_VERSION, ORC_INSTALL and ORC_NO_MODIFY_PATH belong to the install scripts, not to the server. See Installation.