Governed execution

An agent that runs for a long time proposes its next action with a language model, so you cannot check that action in advance. Governed execution puts every such action through one action broker, under a policy the task declares, and sends any tool that runs code to an executor the policy chooses. This page explains the model, the policy, how an executor is chosen, what is refused, and what has been measured.

Why agent actions need governance#

A decision from the Decision Runtime is chosen from a legal set that the rules check before anything happens. A playbook move in a digital worker is chosen the same way. Neither needs isolation: the set of possible outcomes is known and checked in advance.

A long-running agent is different. A model proposes each next step: read this file, fetch this URL, run this command. You cannot list those steps ahead of time, and a command can do more than its name says. A package install can run a post-install script, and a test run can execute code the model wrote. So the control has to sit at the moment of action. It checks each action against a declared policy, records it, and contains any code the action runs.

Isolation here is a governance control. It is what lets you let an agent act without trusting each step it proposes.

The layered model#

There is one path. Every action goes through the broker. File and network actions run inside the broker, and no code runs for them. A tool that runs code goes to an executor, and the policy chooses the executor, never the caller.

The action broker#

The agent never gets raw file or network access. It asks the broker to read_file, write_file, list_dir, http_fetch or run_tool. The broker checks each request against the task policy and runs it only if the policy allows it.

• Paths. Reads and writes are limited to workspace-relative prefixes. Absolute paths, .., symlinks at any depth, hard links and denied names (.git, .env, .netrc, .ssh by default) are refused.
• Egress. http_fetch reaches only hosts or CIDR ranges on the allow-list, on the listed ports and schemes. Every resolved address is checked. A host rule admits only globally routable addresses unless allow_private is set. The connection is pinned to the checked address, and redirects are not followed.
• Limits. Read, write and response sizes, a fetch timeout, and actions per minute.
• Tools. Only declared tools run. A tool has a fixed program prefix, and the agent may add arguments only when the tool allows it.

The executors#

The task policy#

Each task declares a policy. The contract is helixor.task_execution_policy.v1. A task policy overrides the worker's default policy, which overrides the built-in default. Unknown keys are refused.

The built-in default is the safe one: a trusted toolchain, one tenant, the executor chosen automatically, no broker egress, no network for code, and one declared shell tool.

This policy runs a project's tests on a trusted toolchain. It lets the broker fetch from one API over HTTPS and write back only src and reports:

{
  "schema_version": "helixor.task_execution_policy.v1",
  "workspace": "/srv/agent/tasks/t-1042",
  "workload": "trusted_toolchain",
  "tenancy": "single_tenant",
  "executor": "auto",
  "code_network": { "mode": "off" },
  "egress": [
    { "host": "api.example.com", "ports": [443], "schemes": ["https"] }
  ],
  "readable": ["src", "tests", "docs"],
  "write_back_paths": ["src", "reports"],
  "tools": [
    { "name": "tests", "argv": ["python", "-m", "pytest", "-q"], "allow_args": true, "timeout_seconds": 300 }
  ],
  "limits": {
    "memory_mb": 1024,
    "command_timeout_seconds": 300,
    "session_budget_seconds": 1800,
    "max_actions_per_minute": 120
  },
  "task_id": "t-1042"
}

This example validates against the schema. It was also passed to the companion's executor selection. On Linux, as an unprivileged user with no delegated cgroup, it selected the OS sandbox, landlock tier. On macOS it was refused, as described below.

How the executor is chosen#

With executor: auto, the workload, tenancy and code network decide:

An explicit executor may add isolation. It may never remove isolation the workload needs. For example, executor: os-sandbox with workload: untrusted_code is refused with HELIXOR_EXECUTION_ISOLATION_POLICY_INVALID, because the task needs a VM.

Each session record and each receipt names the executor, its tier and the reason it was chosen.

Refusal behaviour#

If the executor the policy needs cannot start, the task is refused with HELIXOR_EXECUTOR_UNAVAILABLE and the facts that explain why. The task is never downgraded to a weaker executor. An unavailable OS sandbox is not swapped for a VM either: the policy says which executor it wants. The production profile has no host executor, so production never falls back to the host.

helixor doctor lists each executor, whether it can run on this host and why, and what the default task policy does here. This is its execution section on a macOS arm64 development machine, run on 2026-09-29 against the merged companion code:

execution isolation (profile=development):
  ✓ broker in-process: available — file and network actions run in-process under the task policy; no code runs
  ✗ os-sandbox namespaces: unavailable — the OS sandbox is Linux-only (this host: darwin)
  ✗ os-sandbox landlock: unavailable — the OS sandbox is Linux-only (this host: darwin)
  ✓ smolvm qemu: available — smolvm 0.0.34 on darwin-arm64 (escape suite verified)
  ✓ host (no isolation): available — development profile only, and only when a task policy names executor 'host'; recorded as mode=host
  ! default task policy (broker + os-sandbox, no egress): code-running tools refused here — HELIXOR_EXECUTOR_UNAVAILABLE
    the task needs the OS sandbox (trusted toolchain, single tenant, no code network) and no allowed tier is available here (namespaces: the OS sandbox is Linux-only (this host: darwin); landlock: the OS sandbox is Linux-only (this host: darwin)). Not downgrading to the host; declare executor 'smolvm' to use a VM.
  - entitlement hooks: exec.brokered.v1=not_enforced, exec.sandboxed.v1=not_enforced, exec.isolated.v1=not_enforced

The default task is refused on macOS, which is the intended fail-closed result. A task that declares workload: untrusted_code or executor: smolvm runs in a SmolVM guest on this machine. The last line shows that every entitlement hook is a no-op that records enforced: false. Its three ids come from an earlier draft; the current draft replaces them with one entitlement with levels, described below. The companion also serves the same report at GET /api/v1/companion/execution_isolation/executors.

Receipts and the kill switch#

The broker appends a receipt (helixor.action_receipt.v1) for every decision, allowed or denied. The first receipt, session.open, records the executor selection and the entitlement decisions.

The kill switch ends a session at once. Every later action is refused with HELIXOR_ACTION_SESSION_KILLED, a running tool's executor is closed, and nothing is written back. A spent session budget triggers the kill switch too. In the Linux tests, a kill stopped a running sleep 300 in under 10 seconds and left no process behind.

In the companion, task sessions are opened with POST /api/v1/companion/execution_isolation/sessions and a task_policy body. The actions run, run_tool, read_file, write_file, list_dir, http_fetch, receipts, close and kill are posted to .../sessions/{id}/{action}. No endpoint runs code outside the broker.

Measured comparison#

These numbers come from Helixor's evaluation on 2026-09-29. It ran on a macOS arm64 development machine, with Linux runs inside a local container VM (aarch64, Landlock ABI 8). They are a development baseline. They were not measured on x86_64 or on production hosts.

The escape suite tries ten breaches: reading host files, writing outside declared paths, planting symlinks through write-back, reading host credentials, reaching the network, seeing or signalling host processes, persisting after destroy, and exceeding memory, time and CPU limits. Run with no isolation, the host fails all ten, which proves the tests detect a breach. A plain container baseline passed 9 of 10.

The OS sandbox passed 10/10 in both tiers, including as an unprivileged user with no capabilities. The broker column is a separate suite of eleven attacks expressed as tool calls. The broker contains only actions that go through it. When the same calls were run through plain file and network APIs, they breached 8 of 8.

Platform notes#

• The broker is pure Python and runs anywhere the companion runs.
• The OS sandbox is Linux-only. The namespaces tier needs unprivileged user namespaces and a writable, delegated cgroup v2 subtree. In the evaluation, a default container security profile blocked it. The landlock tier needs Landlock ABI 6 or later and seccomp, and no privileges. It has no aggregate process or memory limit, so pair it with the container's own limits and one sandbox per container. The x86_64 system-call table has not been run yet; only aarch64 was measured.
• SmolVM guests need hardware virtualization. Guest execution is enabled only on platforms where the escape suite has passed against a real guest. Today that is macOS arm64, with the SmolVM runtime version the suite passed with. Every other platform and runtime version refuses.
• The production SmolVM pool Planned needs Linux KVM hosts. A serverless container platform without nested virtualization cannot host it. It needs VMs with nested virtualization, Kubernetes node pools that allow it, or bare-metal hosts, and each needs its own escape-suite run before it is claimed.
• macOS process sandboxing is not a governed executor. It passed 8 of 10 escape tests, with no memory or CPU limit, so the policy never selects it.

Status#

Entitlement levels#

Governed execution is licensed as one entitlement, exec.governed.v1, with a level. The levels are cumulative. This is a draft under review: it is not in any licence yet, and nothing checks it.

Each level is issuable only on its own evidence: its escape suite, run on the target platform. A run on a developer laptop does not count. A licence never names more isolation than was built and measured, so a shared-kernel sandbox is never sold as VM isolation. See the capability and licensing table.

Related#