terok

A tool for managing containerized AI coding agent projects using Podman. Provides both a CLI (terokctl) and a Textual TUI (terok).

Note: The documentation is generated by LLM, work is underway to rewrite it.

Documentation

Document	Description
Full Usage Guide	Complete user documentation
Developer Guide	Internal architecture and contributor docs
Container Layers	Docker image architecture
Container Lifecycle	Container and image lifecycle
Shared Directories	Volume mounts and SSH configuration
Security Modes	Online vs gatekeeping modes
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

Basic Workflow

# 1. Create project directory
mkdir -p ~/.config/terok/projects/myproj

# 2. Create project.yml (see docs/usage.md for full schema)
cat > ~/.config/terok/projects/myproj/project.yml << 'EOF'
project:
  id: myproj
  security_class: online
git:
  upstream_url: https://github.com/yourorg/yourrepo.git
  default_branch: main
EOF

# 3. Generate and build images
terokctl generate myproj
terokctl build myproj

# 4. (Optional) Set up SSH for private repos
terokctl ssh-init myproj

# 5. Create and run a task
terokctl task new myproj
terokctl task run-cli myproj 1    # CLI mode
terokctl task start myproj --toad  # Toad multi-agent TUI (browser access)

Headless Agent Runs (Autopilot)

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

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

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

Presets

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

terokctl run myproj "Fix the typo" --preset solo          # single fast agent
terokctl run myproj "Review auth module" --preset review   # read-only analysis
terokctl 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

terokctl projects                          # List projects
terokctl config                            # Show resolved paths
terokctl task list <project>               # List tasks
terokctl task delete <project> <task_id>   # Delete a task
terokctl image list [project]              # List terok images
terokctl image cleanup [--dry-run]         # Remove orphaned images
terokctl project-delete <project>          # Delete a project
terokctl 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"

Environment Overrides

Variable	Purpose
TEROK_CONFIG_DIR	Projects directory
TEROK_STATE_DIR	Writable state root
TEROK_CONFIG_FILE	Global config file path

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.