# Where we're taking Ukai

The aim is straightforward: let developers use capable agents while keeping
control of what those agents can reach. We're starting with a standalone
Linux jail that works around existing tools. Once that foundation is easier
to install and better tested, we'll build shared records and managed workers
around it.

This page describes priorities, not a delivery schedule. **Next** means work
needed for the first usable release. **Research** means a mechanism still
needs to be proved. **Later** means a planned direction with no shipped
implementation. We haven't set release dates.

## Available in the source today

The `ukai-jail` CLI runs commands on Linux x86_64 and aarch64 with file and network
policies, runtime limits, and a receipt for each attempt. It includes HTTP
and SOCKS5 TCP proxying, optional HTTP(S) credential vaulting, event journals,
`tail`, and permission proposals with `learn`.

Native Raspberry Pi validation covers the ARM64 syscall filters and observer.
Host capabilities still decide which profiles can run: the tested Pi kernel
disables memory cgroups and omits Landlock. An exact-kernel
[Unix socket diagnostics module](specs/jail-v1/evidence/2026-10-07-pi-proxy/README.md)
now enables the live proxy path on the Pi, including credential-free production
proxy-redaction checks. Required memory ceilings and requested Landlock domains
still refuse before the command starts. This module needs rebuilding for a new kernel.
The [October 6 Pi catch-up](specs/ledger-v1/evidence/2026-10-06-pi-catch-up/README.md)
also validates the current retention, query, discovery, comparison and signed
bundle features natively, including the installed CLI commands.

Fourteen starter launch profiles are embedded. OpenCode has recorded live
runs, but a bundled profile is not a promise that every version of that agent
works. The [compatibility records](https://github.com/monocursive/ukai/blob/dev/docs/specs/jail-v1/agent-compatibility.md)
name the tested combinations. Native macOS `ukai-jail` supports inspection
commands and refuses execution.

You can [build the jail and try a small command](https://github.com/monocursive/ukai/blob/dev/docs/guide.md#build-and-check-your-host)
today. [Signed Linux developer-preview packages](https://github.com/monocursive/ukai/releases/tag/ouro-jail-v0.1.0-rc.2)
are also available; a Homebrew tap remains unconfigured.

The separate [Ukai VM preview for Apple Silicon](https://ukai.sh/guide/#macos-vm-preview)
is now available as a signed, notarized DMG through the same Bash installer.
It runs offline Linux ARM64 `tool` and `build` commands in a disposable VM on
macOS 27+. Inputs are copied and outputs returned for review. Native Mac
programs, online agents and host directory sharing are outside this preview.
The [qualification record](https://github.com/monocursive/ukai/blob/dev/docs/benchmarks/jail/macos-vm-preview-package-2026-10-11.md)
documents the 14 measured teardown cases and the remaining fault-model limits.

## Next: make the first run easier

A new user should be able to install the jail, check their host, and run a
command without having to understand the whole implementation first.

The packaging and signature-verification tools work locally. A
[clean Ubuntu 26.04.1 VM](benchmarks/jail/onboarding-2026-09-30.md), with no Rust
toolchain, completed signed installation, a sandboxed command and a real
OpenCode run in 67.32 seconds. The record names the exact build and host and
preserves the unsuccessful Ubuntu 22 and stock Ubuntu 24 attempts. This local
package test does not establish public release availability or wider support.

The [October 8 validation](benchmarks/jail/validation-2026-10-08.md) repeated
this against the frozen Jail inputs: provisioning ripgrep made the real
OpenCode glob/read/write workflow pass in 82.85 seconds, stock Ubuntu 24 still
refuses contained execution, and signed-package checks passed on both releases.
The newer [October 8 follow-up](benchmarks/jail/followup-2026-10-08.md)
prepares signed native x86_64 and ARM64 packages and passes full reference
conformance; production signing and publication remain pending.

The first signed developer preview is `ouro-jail-v0.1.0-rc.1` in
`monocursive/ukai`, with Linux x86_64 and ARM64 packages and a dedicated
release identity. The [guide](guide.md#install-the-developer-preview) provides
the verified Bash installer and current host requirements. Wider host and agent
compatibility remain ongoing work; a Homebrew tap is still unconfigured.

## Next: test the workflows people will use

We need current results for real agent versions, alongside the underlying
containment tests. Each compatibility record should say which agent, version,
jail build, host, and policy were used, what worked, and what remains unknown.
A launch profile stays experimental until that combination has evidence.

Performance measurements need the same care. The newest
[October 8 follow-up record](benchmarks/jail/followup-2026-10-08.md) measures
the observation cost on file-heavy work directly: with observation on,
file-operation work takes about four times as long as with it off. We'll keep
reporting startup and workload overhead separately, refresh the measurements
against a committed build, and add results from actual agent workflows.

The [October 1 working-tree follow-up](benchmarks/sandboxes/observation-and-limits-2026-10-01.md)
reduces read workload time from 24.53 ms to 6.10 ms on the reference VPS;
write workload cost remains high. The
[write and disk-quota follow-up](benchmarks/sandboxes/write-observation-and-disk-quotas-2026-10-01.md)
reduces paired write workload time by 3.6% and verifies ext4/XFS user hard
quotas with 41 live checks. Explicit swap and bounded tmpfs ceilings also have
live checks. The [October 2 baseline](specs/jail-v1/evidence/2026-10-02-final/README.md)
records a passing conformance run and current tested freeze. Project quotas and
automatic volume provisioning remain pending.

Both October 8 records pass K17 with 540 measured samples and no exclusions.
The validation record's figures are post-start measures: worst added startup
131.3 ms p95, and file post-start overhead of 34.9%–37.9% with observation
off. The follow-up record measures file-work time directly: +25.3% plain and
+28.1% delegated against direct with observation off, and +319.6% plain and
+324.5% delegated with observation on. Real-agent matrices retain deadline
failures and provider rate limits, so their successful cases are not general
compatibility claims. The new runner checks dependencies first and stops on a
provider rate limit.

The release checks also include the full test suite, Linux conformance,
security review, and unresolved findings. Documentation and a successful
demo help people evaluate the tool; they do not replace those checks.

## Research: run natively on macOS

We want the same local workflow on a Mac. The current blocker is making sure
the entire process tree stops when its supervisor or privileged helper dies,
including children that have detached from their parent.

The first Endpoint Security prototype cleans up while its custodian stays alive;
killing that custodian left workloads running. A
[reciprocal-custody prototype](https://github.com/monocursive/ukai/blob/dev/docs/benchmarks/jail/macos-reciprocal-custody.md) now
uses two independent clients. In 200 development VM trials, either one could
fail and the surviving client cleaned up the known fixture. Killing both left
every known fixture process running, and fail-closed exec authorization did
not prevent new execution after both clients disappeared. Apple's entitlement
approval is also pending; approval alone will not fix that lifetime gap.

Native execution will stay disabled until cleanup works under normal macOS
security settings and passes the failure tests. Inspection commands remain
useful in the meantime. The released VM preview provides a local Linux guest
while this native lifetime question remains open with Apple.

## Available in source: durable records across runs

The local `ukai-ledger` now reserves attempts, durably admits them
before execution, ingests the jail's source events and records settlement.
It includes inspection, local consistency verification, orphan reconciliation,
bounded opt-in output capture, paginated evidence queries for one run, and
export of the exact canonical NDJSON records. Query results retain their
provenance and report coverage and protection separately from local consistency.
The jail still works independently.

Detached batch runs now use separate Linux user services for the writer and
launch owner. They require an already provisioned lingering user manager.
[Live lifecycle checks](specs/ledger-v1/evidence/2026-10-02-detached/README.md)
cover SSH disconnect/reconnect, duplicate submission, bounded output,
cancellation, owner death and writer loss. `wait` reads the durable outcome;
`cancel` requests a stop and leaves final settlement to the owner.

The [ledger specification](specs/ledger-v1.md) names its current acceptance and
limits. Bounded run catalogs, filtered cross-run queries, event-count comparisons
and comparisons of recorded target labels are implemented. Unsigned portable
bundles export canonical records, embedded receipts and selected captures with
offline verification. Explicit Ed25519 signing and separately pinned public-key
verification are also implemented. Best-effort writer-outage recovery retains
bounded pending evidence for already admitted runs, with explicit degraded
coverage and conservative missing-exit handling. The scripted durability audit
now includes vendor-state cleanup after unknown outcomes. Transcript display,
opt-in argv capture, foreground JSON control and structured redaction are also
implemented and validated on Pi/VPS. The
[milestone-2 closeout](specs/ledger-v1/milestone-2-acceptance.md) freezes the
ledger schemas and fixtures. Historical custody at the legacy cut and managed
project authorization remain separate requirements.
A plain local export does not establish external custody.
The [durability acceptance map](specs/ledger-v1/durability-acceptance.md) tracks
lifecycle and pending-journal crash coverage, the completed acceptance cross-check
and the completed CLI/privacy contracts.

The storage/recovery slice adds durable segment and replay anchors, a rebuildable
SQLite run index and reader cursors that survive writer restart. Canonical
segments now rotate at 64 MiB while preserving global record ordering, exact
exports and restartable reader snapshots. The
[rotation checks](specs/ledger-v1/evidence/2026-10-05-rotation/README.md) cover
interrupted rotation and damaged segments. Durable operator holds and
`gc --dry-run` now explain retention candidates while preserving active runs,
unknown outcomes and reader snapshots. Whole-run `gc` now verifies canonical
history, persists replay identities and chain anchors, then removes inventoried
segments and captures with restart recovery. The
[pruning checks](specs/ledger-v1/evidence/2026-10-05-pruning/README.md) record its
failure boundaries and platform evidence. The writer now loads persistent retention settings at startup. Captures can
expire earlier than canonical history through explicit GC, with independent
inventories, restart recovery and preserved event queries.
Independent operator intents now have replay-safe effect decisions and protect
pending effects from retention. Live tail follows bounded canonical fragments
across rotation and writer restart without changing launch-owner authority.

## In progress: place trusted-operator batch jobs

The Rust `ukai fleet` front door and separate Elixir coordinator now connect
provisioned Linux workers, preserve request identities through retries, and route
execution to the independent Rust launch owner. The
[two-node validation](specs/fleet-v1/evidence/2026-10-07-two-node/README.md)
uses the VPS and Raspberry Pi. This source slice requires explicit private TLS
configuration; membership provisioning and packaged installation remain work.
Connected peers have operator authority over each other. It is not a managed
team service or project authorization boundary.

## Later: submit work to a team worker

A managed worker would let a developer submit a task to a company-controlled
Linux machine under project policy, then receive artifacts and test results
to review. The first target is one worker with a submission client, including
for developers on Macs.

The [pilot preparation record](benchmarks/managed/pilot-plan-2026-09-30.md)
names the repository, team, model-service and deployment decisions still needed,
and the implementation gates that follow the ledger prerequisites.

After the single-worker workflow is proved, the managed service can use fleet
placement across multiple workers. Both managed stages remain planned; the
trusted-operator fleet slice does not supply their authorization or artifact flow.

## Help us make the next run better

Useful feedback is often small and specific: the command you tried, the
agent and jail versions, your OS and kernel, the relevant profile, and the
error you saw. Include a minimal reproduction and the relevant receipt fields
when you can. Review them for private paths, prompts, and credentials before
sharing; a report rarely needs your entire project or agent state.

Documentation corrections and reproducible compatibility failures are
especially helpful while installation and support are still taking shape.
An agent preparing a report should collect those details for its user to
review before posting anything.

For the full acceptance criteria, see the
[jail specification](https://github.com/monocursive/ukai/blob/dev/docs/specs/jail-v2.md).
The [north star](https://github.com/monocursive/ukai/blob/dev/north-star.md)
and [managed-teams specification](https://github.com/monocursive/ukai/blob/dev/docs/specs/managed-teams-v1.md)
cover the later work. Ukai will continue to run other teams' agents;
an agent loop, chat UI, vendor session protocol, and automatic merging or
deployment are outside the current plan.