process family installs it, changes its desired state, reads its log, and removes it. It also records Project process definitions.
Processes and schedules describes owners, runtimes, environment, presets, locks, and definitions. Hibernation describes idle stop and wake for development Processes.
Choose the owner
process:create and process:list need exactly one selector. The CLI refuses two selectors, and --for without --project, before it sends a request.
process:show, process:update, and process:destroy with --project select a definition by name. process:update, process:start, process:stop, process:restart, process:logs, and process:destroy without --project take the numeric Process ID from process:list. An installed Process update uses that record’s owner; it takes no --instance or --node selector.
Commands
Every command accepts
--json, and every result includes the request ID. Lists and details show the lifecycle status, failed step, and error code. JSON lists also carry cpu and memory_bytes, which are null when no sample exists. JSON also carries user, null when the Process uses the derived account. Definition lists omit the command. Environment values show as [REDACTED]. process:destroy asks for confirmation, and the default is No.
orbit process:create
Install one systemd service or Docker container, stopped or started, or record a Project definition.
A preset owns the runtime, command, working directory, and environment, and refuses those options. It refuses
--keep-alive for annotator and the two Agentation presets. It also refuses --user.
--user is accepted only with --node and a systemd runtime. An Instance, Docker, a preset, or a Project definition returns process.option_invalid and sends no request. A name that fails the pattern returns process.user_invalid and sends no request. The API field is user, and CreateProcessRequest takes the same argument. root is refused as process.user_invalid. The Gateway checks the named account with getent passwd over SSH and returns process.user_unavailable when it is absent or its home is invalid. The default working directory is that account’s home; --working-directory overrides it. Processes and schedules describes the option.
annotator preset installs the Gateway’s annotation server on the Node, runs it through systemd with restart on failure, and publishes /__orbit/annotator on the Instance Route. An identical create returns the existing Process and keeps its desired state. Another name for the same preset fails with process.preset_exists. Annotator Process describes its port, private store, environment, and wake behavior.
Install a Vite development server on an Instance and start it:
instance:deploy selects a release. Starting a Process uses the release selected by current; changing current does not restart an already running Process.
orbit process:list
List the Processes of one Instance or Node with their desired and observed states andkeep_alive, or the definitions of one Project.
orbit process:show
Show one Project process definition by name, with its UUID and complete specification.orbit process:update
Replace the complete specification of an installed Process, keeping its ID, name, owner, and desired state. A running Process restarts in place; a stopped Process stays stopped. This is not destroy followed by create. It can interrupt a running service and discard a replaced Docker container’s writable layer. It does not delete named volumes or require destructive consent. Back up and migrate container-layer data before updating a stateful container; see Move data before removing an override.
The command uses the runtime fields and validation of
process:create. It accepts no --instance, --node, --preset, or --start. The runtime options must form a valid complete specification before mutation. A Docker update needs its image and command arguments again. Omitted working directory keeps the image’s WORKDIR, not /app. The Gateway API is PATCH /api/v1/processes/{process}; the SDK sends the same fields and environment map. See Update in place for locks, ownership checks, and runtime failures.
Existing Docker Processes keep their stored working directory across upgrades and unchanged convergence. Include an existing --working-directory=/app when retaining that override; omitting it is an explicit change to the image default. For example, after verifying that all cache data is in the mounted /data volume or completing the linked migration procedure, retain the cache mount and binding while choosing the image default:
Process selector (process.update.target) populated by the read-only Process list, with choices labeled by ID, name, and owner and no default. Selection returns the numeric ID. With --project, use a Process definition selector populated by that Project’s definitions and return the name. An empty list reports No Processes found. (or No Process definitions found.) and returns process.id_invalid (or process.name_required) without mutation. A slow lookup shows indeterminate waiting feedback. A missing required Docker image uses a text prompt Docker image (process.update.image, source --image, no default). A missing command collects literal argv items through text prompts (process.update.command, source repeated --command, no default), never through shell evaluation. Validate each answer and prompt again when it is invalid. Ctrl-C or EOF returns input.cancelled before mutation. JSON and noninteractive calls never prompt: an omitted or invalid installed target returns process.id_invalid (an omitted definition name returns process.name_required), and invalid runtime fields use the create validation codes, including process.command_invalid, process.environment_invalid, and process.option_invalid.
The synchronous Gateway request shows one indeterminate operation with labels Update Process, Updating Process, and Updated Process. It does not invent separate remote stop, install, or start progress stages. Human success uses the Process detail renderer with ID, Name, owner, runtime, desired state, runtime status, working directory, restart policy, and keep-alive; it never prints environment values. JSON success uses the existing Process response shape with the same ID, lifecycle fields, redacted runtime_config.environment map, and request ID. Failure uses the standard failure renderer or JSON error envelope, returns nonzero, and prints no success result. Success returns zero. process.operation_busy and process.runtime_lock_failed retain their existing meanings.
After the Gateway accepts an update, the new specification remains stored even if runtime convergence fails. A lost response or Gateway crash can leave convergence incomplete. Inspect the Process and retry the identical request after the lock is available; equality with the stored specification must not skip stale or unfinished runtime work. An already completed identical retry does not restart an unchanged runtime. If someone has since changed the specification, resolve that newer intent before replaying an old update. See Persisted intent and retry recovery for the guarantees and limits.
With --project, the existing form replaces one Project definition with a complete specification. It requires --for and takes the same definition runtime options as create. It keeps the definition UUID and affects later copies only; it does not restart existing Instance copies. Progress labels remain Update Process definition, Updating Process definition, and Updated Process definition, and the response remains the Project definition response.
orbit process:start
Start an installed Process and store the running desired state.process.operation_busy. A competing operation on the same Process returns process.runtime_lock_failed.
orbit process:stop
Stop an installed Process and store the stopped desired state. A hibernation wake leaves a stopped Process stopped.orbit process:restart
Restart an installed Process and store the running desired state.orbit process:logs
Return one log tail for a Process, or follow new lines as they are written. Docker environment values and credential-shaped data are redacted.
Without
--follow, the Gateway reads the tail once over SSH. With --follow, the CLI opens a live log stream: the Node agent reads the log, and the Gateway relays new lines to this CLI only. The CLI prints [orbit] N lines dropped or [orbit] N MiB skipped where the stream reports them.
When the Gateway cannot open a stream, for example because realtime is not configured or the agent has not joined its log channel yet, the CLI prints a notice on stderr and polls the one-shot read every 5 seconds. It does the same when it cannot connect to Reverb within 15 seconds, with reason realtime_unreachable, for example on a host that does not resolve reverb.orbit. When a live stream ends because the agent stopped, the source became unreadable, or the Gateway fell behind, the CLI switches to polling in the same way. It prints a part the Gateway sends again, with a sequence it already has, only once.
While it polls, the CLI prints only the lines after the last line it printed:
- The first poll reads
--lineslines. Every later poll reads 1,000 lines, so the last printed line is still in the read even with--lines=1. - When a read does not hold the last printed line, because more than 1,000 lines were written in 5 seconds or the log was rotated, the CLI prints
[orbit] lines may be missingand then the newest--lineslines. - While a log is shorter than 1,000 lines, the CLI counts new lines by position, so it prints repeated identical lines too. In a longer log it finds its place by the text of the last lines it printed, so a new line identical to those lines can be missed.
- One failed read, for example a 502 while the Gateway restarts, does not end the command. The third failed read in a row does.
- For a systemd Process, the one-shot read and the live stream give each journal line the same text, as
journalctl --output short-iso --utcprints it, blob data included, so a switch between them neither repeats nor skips a line. - The live stream cuts a line longer than 8 KiB and ends it with
[truncated], while the one-shot read returns it whole. The CLI counts the two as the same line. - A one-shot read returns at most 4 MiB of whole lines, so with very long lines the 1,000-line read holds fewer lines. It cuts each journal entry at 256 KiB, as the live stream does.
- For a Docker Process, both reads return standard output and standard error together, in the order the container wrote them.
agent_not_joined during a websocket move, the CLI tries to open a stream again every 30 seconds. A stream it opens after it printed lines asks for 1,000 earlier lines and prints only the ones after the last printed line, or [orbit] lines may be missing and the newest --lines lines. Live logs lists the reasons. The CLI prints the notice again only when the reason changes or after a stream ran.
The CLI redacts credential-shaped text before it prints a line and writes [redacted]. A value that the agent or the Gateway already redacted shows as [REDACTED], so one line can show both.
With --json and --follow, the CLI prints one JSON object on each line: {"type":"lines","lines":[...],"dropped":0,"skipped":0} for new lines, {"type":"notice","code":"logs.live_unavailable","reason":"agent_not_joined"} when it switches to polling, and {"type":"missing"} where it prints [orbit] lines may be missing. Ctrl-C ends the command with exit code 0 and closes the stream.
orbit process:destroy
Stop and remove the unit or container of one Process, then delete its record. With--project, destroy one definition by name.
Related
schedulerecords recurring commands. Process commands do not operate on Schedules.instance:destroyremoves every Process of the Instance. Node Processes stay.doctorwith--family=processcompares desired and observed state.database:server:createruns a MySQL server as a Docker Node Process.