Skip to content

terok

[!WARNING] This documentation was written by an AI agent and might be inaccurate.

An open, Podman-native runtime for AI coding agents you can let off the leash — without giving them the leash to your machine.

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 focused stack of independently-released Python packages.

terok ecosystem at a glance

Acknowledgements

CASUS
HZDR 		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 with curated allowlist profiles and per-container audit logs (via terok-shield)
  • Credential vault — secrets stay on the host
  • Per-task git gate — a git mirror that the agent pushes through, giving you a human-review point before changes leave your machine
  • Live Allow / Deny prompts — desktop notifications on blocked outbound traffic, turned into immediate firewall rules

Workflow

  • 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
  • Sickbay + panic — health checks with auto-remediation and an emergency kill-switch
  • Multi-vendor agents — Claude Code, Codex, Copilot, Vibe, plus custom LLM endpoints via OpenCode (Helmholtz, university, or your own endpoint — bundled defaults included)

Quick Start

Prerequisites

  • Podman (rootless) and nft (nftables CLI) — the two hard dependencies
  • Python 3.12+
  • OpenSSH client — for private git repos
  • Optional but recommended: systemd user session, dnsmasq and dig (DNS plumbing for the egress firewall), a desktop notification daemon

Installation

pipx install terok

One-time setup

terok setup

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. The per-container services (vault, gate, clearance) are started on demand by the supervisor at task launch. Idempotent — safe to re-run.

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>.

First project

Launch the TUI:

terok                                   # bare `terok` on a TTY 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
  • Press t to start a task (CLI, Toad, or unattended)

Or do the same from the command line:

terok auth claude                       # authenticate host-wide
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 v9k                  # 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
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

Documentation

License

See LICENSE file.