Skip to main content

Code deployment

Most of this page is the hosted-deployment code-repository surface: the local daemon builds its system from module:factory specs (topology mount + workflow load), not from a managed code repository. So module *, worktree *, runtime reload, and the push forms below only apply to a cloud deployment. The typed reads (topology get, workflow get, method get) and runtime status work against both backends.

Cloud deployments back their code with a git-managed worktree (deployment_package/). These verbs read what's there and push changes to it. After every push the runtime rebuilds automatically.

Running local-only, the cloud-only verbs (module *, worktree *, runtime reload, and the push forms) are hidden from --help but still invokable; they exit non-zero with a clean redirect to --backend cloud.

Read what's deployed​

Two views — at HEAD (the committed/built state) vs worktree (what's on disk, which may differ if you've dropped files but not yet reloaded):

orca module list                            # everything at git HEAD
orca module get <kind> <name>               # source of one module at HEAD
orca worktree list                          # what's currently on disk
orca worktree get <path>                    # one file from disk

module get takes the kind and name as two separate positional arguments (e.g. orca module get workflow smc_assay), not a kind/name slash path. Both module get and worktree get accept --out <path> (-o) to write the source to a file instead of stdout.

Typed reads for specific module kinds:

orca topology get                           # current topology source
orca workflow get <name>                    # one workflow's registry summary
orca method get <name>                      # one method's registry summary

Pitfalls​

  • module list shows what's at git HEAD. worktree list shows what's on disk. They'll diverge if someone wrote a file via SSH/SFTP without going through a submission. Use runtime reload to import the worktree state into a fresh runtime.
  • module get returns the SOURCE bytes. workflow get and method get return a registry summary, not source; read the source with module get <kind> <name>. For "what does this workflow do" use describe workflow <name> instead.

Push changes​

orca workflow load   <path> --name <name> --message <m>   # submit workflows/<name>.py source
orca topology mount  <path> --message <m>                 # submit topology.py source
orca workflow delete <name> --message <m>                 # remove a workflow file
orca topology delete        --message <m>                 # remove topology.py
orca module delete   <kind> <name> --message <m>          # generic delete, cascades unregister

On the cloud backend the push verbs are workflow load and topology mount — the same verbs used locally with module:factory specs, dispatched on the active backend. Against Swarm they take a source-file PATH (not a factory spec): workflow load requires --name (matching @orca.workflow(name=...)) and --message; topology mount requires --message. module delete takes the kind and name as two positional arguments plus --message.

Submission flow on every push:

  1. CLI sends the file content to swarm.
  2. Swarm runs an AST validator against an allow-list.
  3. If validation passes, the file is written to the worktree.
  4. Swarm rebuilds the running SystemRuntime.
  5. On rebuild failure: the broken file STAYS on disk; the operator fixes it with another submission or deletes it.

There is no automatic git commit anywhere. The git history is the operator's tool for snapshotting and revert (see Swarm overview), not part of the submission flow.

Pitfalls​

  • A submission with active executions exits CONFLICT (30). The runtime refuses to rebuild while executions are non-terminal. Close + drain them first.
  • AST validation rejects imports outside the allow-list. If your workflow needs a non-standard import, the swarm side has to ship the allowance — the submission won't pass otherwise.
  • workflow delete cascades a runtime unregister of the workflow template. Future submissions referring to it will fail with NOT_FOUND.

Runtime control​

After a manual filesystem drop (e.g. SSH'd in and edited deployment_package/system.py directly), the running runtime won't reflect the change until you tell it to:

orca runtime reload                       # full reload from HEAD: reimport + rebuild
orca runtime reload --workflows-only      # reconcile only workflows/ against the registry
orca runtime status                       # diagnostic snapshot of the lifecycle

reload​

Full reload (default) shuts down, re-imports deployment_package.* from HEAD, and constructs a fresh SystemRuntime. --workflows-only does a lighter reconcile of just the workflows/ directory against the running registry. --reason annotates the operation. Both forms refuse with CONFLICT (30) if any execution is non-terminal. runtime status works against both backends; runtime reload is cloud-only.

status​

A diagnostic dump — when the runtime was built, what sinks are attached, what the active execution count is, when the worktree was last modified. Use this when something feels wrong but orca status is showing healthy.

runtime:        built 2026-05-26 14:00:00 (12 minutes ago)
worktree:       deployment_package/ (last write 0:08:14 ago, 3 files changed)
sinks:          DiskAndIndexEventSink, WsFanoutSink
executions:     2 running, 0 paused, 47 terminal
last submission: 7a3f1c0e at 14:04:22

Pitfalls​

  • runtime reload is unload + build in one step, but it preserves the daemon process. Active executions block it.
  • A filesystem drop without reload will not take effect. The runtime's sys.modules cache holds the old version; new submissions still see the pre-drop state.
  • Cold start on an empty deployment_package/ is expected to fail with ModuleNotFoundError: deployment_package.system. Either drop system.py and reload, or push topology via topology mount (which requires system.py to already be in place).