terok 0.8.5

Sandboxing for AI coding agents, built on Podman.

terok

[!WARNING] Terok is in alpha development phase. It is under active development and until version 1.0.0 is released, APIs, internals, and security boundaries may change without deprecation notice. Not recommended for production deployment.

An open, Podman-native runtime for sandboxing AI coding agents in YOLO mode.

Terok runs each agent task inside a hardened, rootless container with default-deny outbound networking, a credential vault that keeps real keys on the host, a per-task git checkpoint, and a desktop notification path for live allow/deny decisions. It ships a CLI and a Textual TUI on top of a stack of independently-released Python packages.

Acknowledgements

Terok was started at the Center for Advanced Systems Understanding (CASUS), an institute of Helmholtz-Zentrum Dresden-Rossendorf (HZDR) at the end of 2025. See also Terok at HELMHOLTZ.software and the topic page at the Scientific Computing Core (SCC) group of CASUS.

What you get

Hardening

• Rootless Podman — no daemon, no privileged user namespace
• Default-deny egress firewall — via terok-shield
• Credential vault — secrets stay on the host
• Per-task git gate — a git mirror that the agent pushes through; a human-review point before changes leave your machine
• Live Allow / Deny prompts — desktop notifications on blocked outbound traffic

Features

• Projects ⊃ Tasks — long-lived project config, ephemeral task containers; many tasks per project.
• Headless / interactive / web interface — pick the launch mode per task; same agents, same hardening.
• Layered images — base distro · agent CLIs · per-project snippet, cached and reused across projects; Ubuntu / Debian / Fedora / nvidia/cuda out of the box, GPU passthrough for projects whose base image supports it.
• Multi-vendor agents — Claude Code, Codex, Copilot, Vibe, plus custom LLM endpoints via OpenCode.

The six-package stack

Package	Role
terok (this repo)	Project orchestration, TUI, sickbay
terok-executor	Per-task agent runner, image factory, auth flows
terok-sandbox	Hardened Podman runtime, credential vault, git gate
terok-shield	nftables egress firewall + audit
terok-clearance	Live allow/deny prompts via D-Bus + varlink
terok-util	Shared foundations: CLI registry types, XDG paths, config stack

Quick Start

Prerequisites

Hard dependencies:

• Podman (rootless)
• nft (nftables CLI)
• Python 3.12+
• OpenSSH client — for private git repos

Optional but recommended:

• systemd user session — enables the systemd-creds vault passphrase tier (TPM2-sealed on systemd ≥ 257); the gate / vault / clearance services themselves run per container, no systemd units
• dnsmasq and dig — DNS plumbing the egress firewall uses
• A desktop notification daemon — for the Allow / Deny popups path

Installation

pipx install terok

One-time setup

terok setup                             # idempotent; safe to re-run after upgrades

setup installs the supervisor + shield OCI hooks, sets up the encrypted credential store and its vault routes, and adds the XDG desktop entry for the TUI plus shell completions for your detected shell.

Interactive runs prompt for where the credentials-DB passphrase is stored; non-interactive hosts without systemd-creds must choose with terok setup --passphrase-tier <keyring|session-file|config>.

To remove everything later:

terok uninstall                         # reverse of setup; preserves credential DB

First project

Launch the TUI:

terok                                   # bare `terok` runs the TUI

• Press n to run the project wizard (creates config, builds images, sets up SSH + gate)
• Select your new project, press a to authenticate your agent
• Tab to the task list, press c to start a CLI task

Or do the same from the command line:

terok auth claude                       # authenticate host-wide
terok auth                              # interactive menu — pick multiple providers
terok project wizard                    # interactive project setup
terok task run myproj                   # create a CLI task and attach (default on TTY)
terok task run myproj --mode toad       # web interface (browser access)
terok login myproj t3x                  # re-attach later by task ID prefix

For manual project configuration or CI, see the User Guide.

Headless agent runs (unattended)

# Run an agent headlessly with a prompt (uses default_agent config; falls back to claude)
terok task run myproj --mode headless --prompt "Fix the authentication bug"

# With model override and timeout
terok task run myproj --mode headless --prompt "Add tests" --model opus --timeout 3600

# Use a specific agent
terok task run myproj --mode headless --prompt "Fix the bug" --agent codex

Common Commands

terok project list                      # List projects
terok config paths                      # Show resolved paths and config
terok task list <project>               # List tasks
terok task delete <project> <task_id>   # Delete a task
terok login <project> <id_prefix>       # Attach to running task
terok project init <project>            # Full setup: ssh + generate + build + gate
terok project wizard                    # Interactive project creation
terok image usage                       # Disk usage across projects and images
terok sickbay                           # In-container health checks
terok panic                             # Emergency kill-switch
terok image list [project]              # List terok images
terok image cleanup [--dry-run]         # Remove orphaned images
terok completions install               # Re-install shell completions

Notes

• SELinux hosts: install the policy module before terok setup, otherwise the shield + clearance services bind sockets as unconfined_t and podman will refuse to talk to them. The exact install command (a sudo bash over the script terok-sandbox ships) is printed by terok setup when the policy is missing — run it once, then re-run terok setup.
• AppArmor hosts: install the policy otherwise the shield's dnsmasq won't be able to read its confguration. The exact install command (a sudo bash over the script terok-sandbox ships) is printed by terok setup when the policy is missing — run it once, then re-run terok setup.
• Clipboard: If mouse selection doesn't copy to your clipboard, hold Shift while selecting, then Shift+Ctrl+C to copy. See Tips for details.

Configuration

Global Config

Location: ~/.config/terok/config.yml

git:
  human_name: "Your Name"
  human_email: "[e-mail]"

image:
  agents: "all"   # default roster selection for every project

If git.human_name and git.human_email are omitted, terok falls through to your host git config. Setting them in config.yml is the way to override the host-level identity for container commits.

To see what you can pick from for image.agents:

terok agents list                       # list available AI coding agents

Officially-tested base images for image.base_image: ubuntu:24.04, fedora:44, quay.io/podman/stable, nvcr.io/nvidia/nvhpc. Other images in the same family (ubuntu:*, debian:*, fedora:*, nvcr.io/nvidia/*, quay.io/podman/*) work via auto-detection; anything else needs an explicit image.family: deb|rpm override. See docs/usage.md for the full mechanics.

Contributing

See the Developer Guide.

License

See LICENSE file.