Runs

A Run is Axern’s one-shot workload: it executes a command inside an isolated sandbox, streams output, propagates the command’s exit code, and leaves a durable control-plane record. Detached Runs also provide the allocation lifecycle used by SDK Sandboxes and interactive tools.

Run a command

axern run python:3.12-slim -- python -c 'print("hello from axern")'

The CLI attaches to stdout/stderr and exits with the remote command’s real exit code. Every execution also creates a durable Run record:

axern run list
axern run get <run-id>
axern run logs <run-id> --follow
axern run cancel <run-id>

run list filters by --namespace, --status (placed, starting, running, succeeded, failed, cancelled), and --label. run logs supports --follow and resumable --cursor output; a single read is truncated at 64 MiB.

Define a Run with a spec

Use a strict axern/v1 spec when the definition should be reviewed or reused:

run.yaml

api_version: axern/v1
kind: Run
metadata:
  namespace: default
  labels:
    example: docs
spec:
  source:
    image: docker.io/library/python:3.12-slim
  command:
    argv: [python, -c, "print('ok')"]
  resources:
    requests:
      cpu: 500m
      memory: 512Mi
  env:
    MODE: demo

axern run --file run.yaml

spec.source selects exactly one of image or environment (an existing environment ID). Private registries use registry_credential_id; credentials are referenced by ID and never embedded in the spec. The parser rejects unknown fields and conflicting sources.

The equivalent flags cover the same surface: --env, --secret-env, --secret-file, --image-mount, --cwd, --label, --environment, and the four resource flags (--request-cpu, --request-memory, --limit-cpu, --limit-memory). The positional image and --environment are mutually exclusive; --file cannot be combined with definition flags.

Detached and long-running Runs

--detach creates the Run without following output; --wait-timeout bounds how long the CLI waits for the Run to become active (0 disables the wait). Detaching does not detach the workload from the platform — the Run continues to a terminal state under the control plane and remains inspectable.

Run status is durable. Allocation-local stdout/stderr and explicitly declared files or directory-as-tar outputs remain readable for 15 minutes after cleanup begins. The node quiesces the Allocation and atomically publishes the manifest before runtime deletion. Node-process restart preserves sealed bytes; node-disk loss does not. Declared-output limits are 16 paths, 64 MiB per file, 256 MiB per tar, and 256 MiB total. Missing, rejected, capture-failed, and node-unavailable states are explicit. Durable publication remains the caller’s responsibility.

Reuse a successfully prepared rootfs

Use --snapshot-rootfs on a finite Run when later Runs must start from its complete post-workload writable rootfs:

axern run --snapshot-rootfs --environment <base-environment-id> -- /bin/sh -lc './compile.sh'

The attached CLI waits for the separate snapshot finalization and prints the new Environment ID. A detached caller can inspect axern run get <run-id> or use the SDK wait helper. The result is a normal immutable Environment, not a Snapshot resource. Every later Run receives an independent copy-on-write Allocation. Bind and image mounts, Secret projections, kernel filesystems, active processes, sockets, Terminal, SSH, and Tunnel state are excluded. Failed or cancelled Runs produce no Environment.

Isolation and resources

Packaged nodes use runsc as the fixed isolation boundary. Resource requests and limits interact with namespace quota and admission; see Runtime and Resources for the model and Environments, Namespaces, and Quota for inspecting admission rejections.

The CLI help is authoritative for the complete flag surface: axern run --help.