Skip to content

Local Operations

Before enabling a backend, verify that the workspace path is explicit, the host Docker socket is absent, resource limits are set, network mode is known, and credentials are not mounted.

Canonical source lives outside disposable sandboxes. Restore from the latest trusted snapshot or Git commit. Resume approval from serialized run state; do not replay the side effect as a new request.

Destroy expired or failed sandboxes after retaining required audit events and published artifacts. Closing a client stream is not cancellation.

Recovery and evidence checklist

Before cleanup or resume, retain:

  • the workflow and selected policy/profile;
  • sandbox/session identifiers and lifecycle state;
  • capability decisions and approval records;
  • command results, verification output, checkpoints, and published artifacts;
  • the exact failure, cancellation, or expiration reason.

Resume from serialized run state when supported. Do not replay a request merely because the client disconnected, and do not repeat an external side effect whose completion is unknown without an explicit reconciliation decision.

Install Youki for the Linux backend

Youki is the preferred first Linux isolation backend. The backend selector automatically falls back to runc when youki is not installed; install and validate Youki from a normal host terminal, not from inside a restricted Codex sandbox, when Youki is the preferred runtime.

Host prerequisites

On Ubuntu or Linux Mint, install the build and runtime dependencies:

sudo apt-get update
sudo apt-get install -y \
  git \
  build-essential \
  pkg-config \
  libsystemd-dev \
  libelf-dev \
  libseccomp-dev \
  libclang-dev \
  libssl-dev \
  systemd \
  dbus-user-session \
  libpam-systemd

Install Rust and just if they are not already available, then build Youki:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
cargo install just --locked

cd /tmp
git clone https://github.com/youki-dev/youki.git
cd youki
just youki-release
sudo install -m 0755 ./youki /usr/local/bin/youki

Verify the installation and host capabilities:

which youki
youki --version
youki info

The host must provide Linux namespaces, cgroups, and a working systemd user manager with a DBus session. Log out and back in after installing the system packages, then verify:

systemctl --user is-system-running
systemctl --user status

If the user manager must remain available without an interactive login, enable lingering for the user:

loginctl enable-linger "$USER"

dbus-run-session alone is not a substitute for a systemd user manager. A Codex sandbox may have systemctl and /run/user/$UID/bus visible while still blocking access to the bus; run the live Youki smoke test from the host terminal in that case.

OCI bundle requirements

The backend requires a prepared bundle containing:

bundle/
├── config.json
└── rootfs/

The project-generated configuration uses a read-only root filesystem, a writable /workspace bind mount, isolated namespaces, dropped capabilities, noNewPrivileges, and bounded resources. The rootfs must contain the command specified by process.args; a minimal static BusyBox rootfs is sufficient for a smoke test.

Smoke-test lifecycle

Run the lifecycle from the host terminal with an explicit state directory:

youki --root "$BUNDLE_ROOT/state" create --bundle "$BUNDLE_ROOT/bundle" smoke-test
youki --root "$BUNDLE_ROOT/state" start smoke-test
youki --root "$BUNDLE_ROOT/state" state smoke-test
youki --root "$BUNDLE_ROOT/state" delete --force smoke-test

Do not configure Youki as Docker’s global default until the direct OCI lifecycle test passes. See the Youki user documentation for runtime requirements and the basic usage guide for rootless OCI bundles.

The selector tries youki first and then runc. To require one runtime, configure preferred: :youki or preferred: :runc; an unavailable required runtime is an error rather than a silent fallback.