Skip to main content

Lifecycle

These verbs bracket every session: stand the daemon up, mount a topology, register a workflow, confirm it's healthy, and tear it back down.

orca version                            # sanity check (no daemon needed)
orca start                              # spawn the daemon, no system loaded
orca topology mount <spec>              # build a SystemRuntime from a topology factory
orca workflow load  <spec>              # register a workflow on the mounted runtime
orca status                             # daemon + runtime health
orca unload                             # drop the runtime, keep the daemon
orca shutdown                           # unload (if needed) and exit the daemon

There is no single orca load verb. Bringing a system up is two steps: topology mount builds the instrument/config foundation, then workflow load registers a workflow on it. On the local daemon both take a module:factory spec (module:build_topology / module:build_workflow); against a Swarm deployment they take a source-file path and a --message (see Code deployment).

orca version​

Print the installed framework version. No side effects, no daemon required.

$ orca version
orca 1.0.0

--json form:

{"version": "1.0.0"}

orca start​

Spawn the daemon as a detached subprocess. Polls /health until ready, prints the PID and port, writes ~/.orca/<pid-file>.

$ orca start
daemon started (pid=43821, port=51724). No system loaded -- run `orca topology mount <spec>` next.

What happens:

  1. Pick a free port.
  2. Spawn python -m orca.daemon --port <port> detached (CREATE_NO_WINDOW on Windows, start_new_session on POSIX).
  3. Capture stderr to ~/.orca/daemon_startup.err until the daemon's own logging takes over.
  4. Poll GET /health for up to 10 seconds.
  5. Write the PID file.

If the health probe times out the CLI surfaces the tail of daemon_startup.err so you can see the import error or crash.

Pitfalls:

  • start doesn't load a system. The daemon is up but idle. Run orca topology mount <spec> next to build a runtime before submitting work.
  • Stale PID files: if the daemon was killed without shutdown, the file may point at a dead process. start detects this and re-spawns; status reports daemon: not running and refuses to operate.
  • Port conflict: rare, but if every probed port is busy the spawn fails with EXIT_GENERIC.

orca topology mount <spec>​

Builds the runtime foundation. On the local daemon, <spec> is a module:build_topology factory; the daemon imports the module, calls the factory, and builds an empty SystemRuntime from the returned topology.

$ orca topology mount examples.hamilton_smc.topology:build_topology
mounted topology 'examples.hamilton_smc.topology:build_topology' (sim=False); runtime is BUILT

Pass --sim to start the mounted runtime in simulation mode. The spec must be importable from the daemon's working directory: if you launched orca start from /lab, then examples.hamilton_smc.topology resolves against /lab.

Against a Swarm deployment, <spec> is a topology.py source-file path and --message is required; the submission triggers a full rebuild. See Code deployment.

orca workflow load <spec>​

Registers a workflow on the mounted runtime. Validates and registers; does NOT run it. On the local daemon, <spec> is a module:build_workflow factory; against Swarm it's a workflow source-file path plus --name and --message.

$ orca workflow load examples.hamilton_smc.workflow:build_workflow
loaded workflow 'smc_assay'

Refused while any execution is active (paused included) — re-importing would swap definitions out from under live threads. To add a single method or action to a running workflow instead, use execution thread insert-method.

orca status​

One-shot health view: daemon liveness plus a loaded-system summary.

$ orca status
daemon:         running (pid=43821, port=51724)
uptime:         0:12:34
system_loaded:  true
spec:           examples.hamilton_smc.topology:build_topology
runtime_state:  STARTED
sim:            false

--json form returns a _StatusPayload (pid, port, started_at, uptime_seconds, health_reachable, system_loaded, spec, runtime_state, sim). For live execution counts and sink details use orca runtime status, which returns the richer RuntimeStatusResponse.

Exit codes from status are informational only:

  • 0 = daemon up + system loaded
  • 10 = no daemon running
  • 31 = daemon running but no system loaded (still exits 0; the line in stdout tells you)

orca unload​

Tears down the loaded SystemRuntime. Daemon keeps running, ready for another topology mount.

$ orca unload
topology unloaded; daemon still running

If active executions exist, unload refuses unless you pass --force. With --force it aborts every non-terminal execution first.

Pitfalls:

  • --force triggers a hard abort, not a graceful drain. To drain gracefully: execution close each ACCEPTING execution, wait for them to terminate, then unload cleanly.
  • The daemon does NOT auto-unload on shutdown; shutdown calls unload internally first.

orca shutdown​

Full stop. Unloads the system (if any), then exits the daemon.

$ orca shutdown
daemon stopped (pid=43821)

If you want to leave the daemon up but drop the system, use unload instead. If you want to stop a stuck daemon that isn't responding to HTTP, kill the PID from status directly.