terok

Orchestration and instrumentation platform for containerized AI coding agents. Provides both a CLI (terok) and a Textual TUI (terok-tui).

terok manages the what — which agents run, how they're configured, and what code they work on. The hardened container runtime (terok-sandbox) manages the how — Podman isolation, egress firewalling, gated git access, and credential proxying.

Note: Parts of the documentation in this repo were initially generated by LLM and may still be inaccurate. Work is underway to rewrite it.

Documentation

Document	Description
Concepts	Architecture, security model, and design rationale
Full Usage Guide	Complete user documentation
Developer Guide	Internal architecture and contributor docs
Container Layers	Container image architecture
Container Lifecycle	Container and image lifecycle
Shared Directories	Volume mounts and vault
Security Modes	Online vs gatekeeping modes
Shield	Egress firewall (terok-shield)
Agent Compatibility	Per-agent feature support matrix
Login Design	Login session architecture
Docker	Running terok inside Docker (experimental)

Quick Start

Prerequisites

• Podman installed and configured
• Python 3.12+
• OpenSSH client (for private git repos)

No Podman? A Docker-based setup is available for evaluation, but native Podman is recommended for regular use.

Installation

# Install the latest release wheel (download from GitHub Releases page)
pipx install ./terok-*.whl

One-time setup

One command installs everything — shield OCI hooks, vault, git gate, D-Bus clearance bridge, and an XDG desktop entry for the TUI:

terok setup                             # idempotent; safe to re-run after upgrades
terok completions install               # (optional) tab completion

To remove everything later:

terok uninstall                         # reverse of setup; preserves credential DB
terok uninstall --purge-credentials     # also delete stored tokens + SSH keys

First project

Launch the TUI and create your first project from there:

terok 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 (no project needed)
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 --no-attach       # start it detached; print login instructions
terok task run myproj --mode toad       # Toad multi-agent TUI (browser access)
terok login myproj a3                   # re-attach later by hex ID prefix
terok auth claude --project myproj      # project-scoped escape hatch (uses its L2 image)

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

Headless Agent Runs (Autopilot)

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

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

# Use a specific provider
terok task run myproj "Fix the bug" --provider codex

Presets

Three presets work out of the box — no config needed:

terok task run myproj "Fix the typo" --preset solo          # single fast agent
terok task run myproj "Review auth module" --preset review   # read-only analysis
terok task run myproj "Add pagination" --preset team         # multi-agent team

Create your own in ~/.config/terok/presets/ (shared across projects) or per-project in <project>/presets/. See the Presets Guide for details.

Common Commands

terok project list                          # List projects
terok config paths                      # Show resolved paths and config
terok task list <project>               # List tasks (hex IDs)
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               # Install shell completions

Tips

• 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: "your@email.com"

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

Per-project overrides live in project.yml under image: — base_image, family (deb/rpm, auto-detected for ubuntu/fedora/podman/nvcr.io/nvidia), and agents (which roster entries to bake into L1). See docs/usage.md for the full precedence and selection mechanics.

Environment Overrides

Variable	Purpose
TEROK_CONFIG_DIR	Configuration directory (~/.config/terok)
TEROK_CONFIG_FILE	Global config file path
TEROK_ROOT	Shared namespace root for all ecosystem packages
TEROK_STATE_DIR	Host-only state (builds, metadata)
TEROK_VAULT_DIR	Vault store (vault database, routes, key registry)

Requirements

• Podman is required for build/run commands

Contributing

# Setup
git clone git@github.com:terok-ai/terok.git && cd terok
make install-dev

# Before committing
make lint      # Run linter (required)
make format    # Auto-fix issues if lint fails

# Before pushing
make check     # Run all checks (lint + test + tach + docstrings + deadcode + reuse)

See Developer Guide for full details.

License

See LICENSE file.