A tool for managing containerized AI coding agent projects using Podman. Provides both a CLI (terok) and a Textual TUI (terok-tui).
Updates: Releases 0.6.2 and newer us a different config directory layout. THere's an unofficial config migration helper script, but untested. I tired it on my 3 dev machines where it produced the correct results, but there might be cases where it fails. If you used the default config and state folder locations, it should work for you too.
Note: The "documentation" in this repo is generated by LLM, and is inaccurate. Work is underway to rewrite it.
| 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) |
- 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.
# Install the latest release wheel (download from GitHub Releases page)
pipx install ./terok-*.whl# 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
terok generate myproj
terok build myproj
# 4. (Optional) Set up SSH for private repos
terok ssh-init myproj
# 5. Create and run a task
terok task new myproj
terok task run-cli myproj 1 # CLI mode
terok task start myproj --toad # Toad multi-agent TUI (browser access)# Run an agent headlessly with a prompt (uses default_agent config; falls back to claude)
terok run myproj "Fix the authentication bug"
# With model override and timeout
terok run myproj "Add tests" --model opus --timeout 3600
# Use a specific provider
terok run myproj "Fix the bug" --provider codexThree presets work out of the box — no config needed:
terok run myproj "Fix the typo" --preset solo # single fast agent
terok run myproj "Review auth module" --preset review # read-only analysis
terok run myproj "Add pagination" --preset team # multi-agent teamCreate your own in ~/.config/terok/presets/ (shared across projects) or
per-project in <project>/presets/. See the
Presets Guide for details.
terok projects # List projects
terok config # Show resolved paths
terok task list <project> # List tasks
terok task delete <project> <task_id> # Delete a task
terok image list [project] # List terok images
terok image cleanup [--dry-run] # Remove orphaned images
terok project-delete <project> # Delete a project
terok completions install # Install shell completions- Clipboard: If mouse selection doesn't copy to your clipboard, hold Shift while selecting, then Shift+Ctrl+C to copy. See Tips for details.
Location: ~/.config/terok/config.yml
git:
human_name: "Your Name"
human_email: "your@email.com"| Variable | Purpose |
|---|---|
TEROK_CONFIG_DIR |
Projects directory |
TEROK_STATE_DIR |
Writable state root |
TEROK_CONFIG_FILE |
Global config file path |
- Podman is required for build/run commands
# 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.
See LICENSE file.