Sleep and wake

The Orchestrator stops a workspace that nobody uses and starts it again when somebody opens it. This page describes when each happens and the settings that change it.

Readiness

A start is ready when GET /api/graph/ready answers true. Until then the proxy forwards nothing. GET /api/public/instances/<slug>/status reports each step for the starting page. ORC_START_TIMEOUT_MINUTES (15) is how long the Orchestrator waits before it gives up on a start.

Waking up

A browser navigation to a stopped workspace (a GET with Sec-Fetch-Mode: navigate or Accept: text/html) goes to /#/start/<slug>. That page wakes the workspace, polls until it is ready, and then opens the address the visitor asked for, with its path, query and fragment. /acme/#/search?query=engines wakes Acme and opens that search.

Any other request to a stopped workspace gets 503 and does not wake it. A stale tab polling in the background therefore cannot keep a workspace alive or restart it. This is deliberate. Do not start workspaces from your own scripts by calling a workspace URL; call the start endpoint instead.

On a subdomain, a navigation to a sleeping workspace goes to the starting page on the Orchestrator (ORC_PUBLIC_ADDRESS when set, otherwise the parent host) and comes back to the original URL when the workspace is ready. The starting page returns only to its own <slug>. host or its parent host, so it cannot be used as an open redirect.

Going to sleep

• Every proxied request counts as activity.
• A request still in flight (an upload, a download, a streamed response) postpones the shutdown.
• The push channel that Studio's front-end keeps open per tab (/api/websocket and its SSE fallback) counts only when it opens. A forgotten tab does not keep a workspace awake.
• A running workspace that has been idle for ORC_IDLE_TIMEOUT_MINUTES (60), with nothing in flight and not kept warm, is stopped.
• After an Orchestrator restart, running workspaces keep their idle time. Reconnecting is not activity.

To watch it happen, start the Orchestrator with ORC_IDLE_TIMEOUT_MINUTES=1.

Keep warm

Keep warm sets a "keep running until" time, capped at ORC_MAX_KEEP_WARM_DAYS (7).

• The workspace is started if needed and is never stopped for idleness before that time.
• It is a guarantee, not a hint. A kept-warm workspace found stopped (a crash, a host reboot, a failed start) is started again. Retries back off from 1 minute to at most an hour.
• Stopping the workspace from the console clears keep warm.

Always online

The last choice of the Keep warm menu is Always online, until stopped from here. It keeps the workspace running with no end, until you clear it or stop the workspace from the console, which asks first.

It promises everything keep warm does, for good: the workspace is never stopped for idleness, for room (ORC_MAX_RUNNING_INSTANCES) or for memory, and it is started again when found stopped. It is not capped by ORC_MAX_KEEP_WARM_DAYS.

ORC_ALLOW_ALWAYS_ONLINE=false turns it off. The console stops offering it, the API refuses it with 409, and workspaces set earlier are treated like any other.

From a script:

# keep warm for 48 hours
curl -X POST -H "Authorization: Bearer $ORC_API_TOKEN" -H 'Content-Type: application/json' \
     -d '{"Hours": 48}' https://example.com/api/admin/instances/acme/keep-warm

# always online
curl -X POST -H "Authorization: Bearer $ORC_API_TOKEN" -H 'Content-Type: application/json' \
     -d '{"AlwaysOnline": true}' https://example.com/api/admin/instances/acme/keep-warm

# clear it
curl -X POST -H "Authorization: Bearer $ORC_API_TOKEN" -H 'Content-Type: application/json' \
     -d '{"Hours": 0}' https://example.com/api/admin/instances/acme/keep-warm

Always online is open to a workspace's owners, so a console user can keep workspaces running for good. There is no per-user setting for it.

Capacity

With ORC_MAX_RUNNING_INSTANCES set, waking one more workspace on a full server stops the least recently used one that nobody is using: not kept warm, no request in flight, and idle for at least 5 minutes. When every running workspace is in use, the start is refused and the starting page says so. The refused workspace stays stopped, not in error.

Low memory

Every 15 seconds the Orchestrator reads the host's free memory: MemAvailable in /proc/meminfo, or elsewhere Docker's total less what the workspaces use. After two readings in a row below ORC_MIN_FREE_MEMORY_PERCENT (10), it stops one workspace, chosen as in Capacity. Below half the threshold, the 5 minute idle rule no longer applies.

• A kept-warm workspace is never stopped for memory.
• It stops one workspace at a time, and waits a minute after each stop finishes.
• When nothing can be stopped, the activity log says so once.
• 0 turns the monitor off.

Settings