autonomy run

Run a subprocess under policy governance

Synopsis

Starts an in-process policy-gated runtime on a random localhost port,
exports AUTONOMY_RUNTIME_URL to the subprocess environment, then exec's
<command> with any additional arguments.

When --policy is omitted the embedded demo policy is used (allows tool.echo
and tool.http_get at the policy layer; denies everything else). tool.http_get
still requires an allowlisted endpoint at runtime and is fail-closed by default.
Pass --policy <oci-ref> to use a custom bundle already present in the local
managed cache.

The runtime server shuts down gracefully when the subprocess exits.

WAL audit trail:

  Every tool decision the agent makes is recorded in a local WAL — including
  the layered-governance trail (policy.allow + runtime.deny under the same
  audit_id when a runtime-enforcement layer rejects, e.g. AllowedDomains for
  tool.http_get). By default the WAL is written to a temp directory and
  removed on exit. A "System footprint" panel is printed to stderr at exit
  naming the WAL path.

  Three ways to preserve the WAL:
    --dir <path>                 pin the WAL to <path> (CLI flag form)
    AUTONOMY_RUN_WAL_DIR=<path>  same effect, env-var form (--dir wins)
    --keep                       keep the auto-generated $TMPDIR path

  IMPORTANT: --dir and --keep MUST appear BEFORE the subprocess command.
  Anything after the subprocess command is forwarded to the subprocess
  (cobra's --no-interspersed mode), e.g.:
    autonomy run --dir ~/wal python3 agent.py            ✓ pinned
    autonomy run python3 agent.py --dir ~/wal            ✗ --dir → python3
  The footprint panel detects this exact mistake and prints a corrected
  invocation. Inspect a preserved WAL with: autonomy wal inspect --dir <path>.

ROS2 governed launch (ros2.launch dispatch):

  When the first argument is "ros2.launch", execution is dispatched through
  runtime/ros2.RunGoverned instead of starting a subprocess.  Use --image to
  select the container path; native path is used as a fallback when Docker is
  unavailable and ros2 is in PATH.

  autonomy run [--image <img>] [--workspace <dir>] [--runtime-url <url>] \
      ros2.launch launch <pkg> <launch_file> [ros2-args...]

  autonomy run ros2.launch topic list

Usage

autonomy run <command> [args...] [flags]

Options

      --dir path             path to pin the WAL directory to (created if missing; never auto-removed; alias for AUTONOMY_RUN_WAL_DIR, flag wins on disagreement). MUST appear BEFORE the subprocess command — autonomy run uses --no-interspersed, so flags after the subprocess command are forwarded to the subprocess.
      --image string         [ros2.launch] OCI image for container-path execution (must include the ROS2 toolchain, e.g. ghcr.io/autonomyops/adk-ros2-runtime:v1.0.0)
      --keep                 preserve the auto-generated WAL directory on exit (default: remove it; ignored when --dir or AUTONOMY_RUN_WAL_DIR is set, since named directories are always preserved)
      --policy string        OCI reference of the policy bundle from the local managed cache (default: embedded demo policy); for ros2.launch: forwarded as the ros2 policy ref
      --runtime-url string   [ros2.launch] AutonomyOps runtime HTTP address for governance callbacks (e.g. http://localhost:8080; default: local-only evaluation)
      --workspace string     [ros2.launch] ROS2 workspace directory forwarded as AUTONOMY_ROS2_WORKSPACE (native path only)