Run Programs

Choose foreground execution for one program or a resident host for repeated submissions. These examples run from the OS checkout using its fixed transfer deck.

One Shot

culsma-os run examples/transfer/transfer.culs \
  --station-id transfer-once \
  --host-db run-artifacts/once/os.sqlite3 \
  --driver-config examples/transfer/deck.json \
  --artifacts-dir run-artifacts/once

The command waits for its execution path and exits. It does not discover an existing serve process automatically. Use a separate station identity for an independent simulation.

Start a Resident Host

In terminal 1:

export CULSMA_OS_STATION_ROOT="$PWD/run-artifacts/stations"
culsma-os serve \
  --station-id transfer-service \
  --socket /tmp/culsma-transfer.sock \
  --host-db run-artifacts/service/os.sqlite3 \
  --driver-config examples/transfer/deck.json \
  --artifacts-dir run-artifacts/service

In terminal 2, from the same checkout and activated environment:

culsma-os host-status --socket /tmp/culsma-transfer.sock

Wait until the response contains "status": "ready". Startup can take a few seconds; repeat the check while initialization is in progress. If submit returns HOST_NOT_READY, submit again after the host becomes ready.

culsma-os submit examples/transfer/transfer.culs --socket /tmp/culsma-transfer.sock
culsma-os runs --socket /tmp/culsma-transfer.sock

submit returns admission information and a run_id; acceptance does not mean completion. Replace RUN_ID below with that returned identifier:

culsma-os status RUN_ID --socket /tmp/culsma-transfer.sock
culsma-os device-status --socket /tmp/culsma-transfer.sock

Device configuration belongs to the host. submit does not accept a replacement deck. Requests identify local files that must be accessible to the same-machine host.

Pause, Resume and Cancel

culsma-os pause RUN_ID --socket /tmp/culsma-transfer.sock
culsma-os resume RUN_ID --socket /tmp/culsma-transfer.sock
culsma-os cancel RUN_ID --socket /tmp/culsma-transfer.sock

Control requests are coordinated with execution. Pause or cancel does not reverse completed device effects and is not a hardware emergency stop. Check status after a request; unresolved effects or finalization may retain isolation.

For a saved one-shot run, use --host-db instead of --socket and supply the matching station and driver configuration when resuming. Do not open a resident host database through a competing one-shot controller.

Stop the Host

culsma-os host-stop --socket /tmp/culsma-transfer.sock

This requests shutdown; it does not erase saved runs or station state. Restart with the same socket, database, station identity and matching configuration. Do not start two owners for the same station.