Metadata-Version: 2.4
Name: terok
Version: 0.8.0
Summary: Sandboxing for AI coding agents, built on Podman.
License-Expression: Apache-2.0
License-File: LICENSE
License-File: LICENSES/Apache-2.0.txt
Keywords: podman,containers,tasks,developer-tools,cli
Author: Jiri Vyskocil
Author-email: jiri@vyskocil.com
Maintainer: Jiri Vyskocil
Maintainer-email: jiri@vyskocil.com
Requires-Python: >=3.12,<3.15
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Dist: argcomplete (>=3.1)
Requires-Dist: jinja2 (>=3.1)
Requires-Dist: platformdirs (>=4.5.1)
Requires-Dist: pydantic (>=2.6)
Requires-Dist: requests (>=2.31)
Requires-Dist: rich (>=13.0)
Requires-Dist: ruamel.yaml (>=0.18)
Requires-Dist: terok-clearance (>=0.7.0,<0.8.0)
Requires-Dist: terok-executor (>=0.1.0,<0.2.0)
Requires-Dist: terok-sandbox (>=0.1.0,<0.2.0)
Requires-Dist: terok-shield (>=0.7.0,<0.8.0)
Requires-Dist: terok-util (>=0.1.0,<0.2.0)
Requires-Dist: textual-serve (>=1.1.0)
Requires-Dist: textual[syntax] (==8.2.5)
Requires-Dist: unique-namer (>=1.3)
Project-URL: Changelog, https://github.com/terok-ai/terok/blob/master/CHANGELOG.md
Project-URL: Documentation, https://terok-ai.github.io/terok/
Project-URL: Homepage, https://terok.ai/
Project-URL: Issues, https://github.com/terok-ai/terok/issues
Project-URL: Repository, https://github.com/terok-ai/terok
Project-URL: Security, https://github.com/terok-ai/terok/security/policy
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://terok-ai.github.io/terok/terok-logo-w.svg">
    <img src="https://terok-ai.github.io/terok/terok-logo-b.svg" alt="terok" width="120">
  </picture>
</p>

# terok

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![REUSE status](https://api.reuse.software/badge/github.com/terok-ai/terok)](https://api.reuse.software/info/github.com/terok-ai/terok)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=terok-ai_terok&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=terok-ai_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.

<p align="center">
  <img src="docs/img/architecture.svg" alt="terok ecosystem at a glance">
</p>

## What you get

### Hardening

- **Rootless Podman** — no daemon, no privileged user namespace
- **Default-deny egress firewall** — via [terok-shield](https://github.com/terok-ai/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 five-package stack

| Package | Role |
|---------|------|
| **terok** (this repo) | Project orchestration, TUI, sickbay |
| [terok-executor](https://github.com/terok-ai/terok-executor) | Per-task agent runner, image factory, auth flows |
| [terok-sandbox](https://github.com/terok-ai/terok-sandbox) | Hardened Podman runtime, credential vault, git gate |
| [terok-shield](https://github.com/terok-ai/terok-shield) | nftables egress firewall + audit |
| [terok-clearance](https://github.com/terok-ai/terok-clearance) | Live allow/deny prompts via D-Bus + varlink |

## 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 — runs the gate / vault / clearance daemons
- **`dnsmasq`** and **`dig`** — DNS plumbing the egress firewall uses
- A desktop **notification daemon** — for the Allow / Deny popups path

### Installation

```bash
pipx install terok
```

### One-time setup

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

`setup` installs the shield OCI hooks, the XDG desktop entry for the TUI, and shell
completions for your detected shell.

To remove everything later:

```bash
terok uninstall                         # reverse of setup; preserves credential DB
```

### First project

Launch the TUI:

```bash
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:

```bash
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](docs/usage.md).

### Headless agent runs (autopilot)

```bash
# 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
```

### Common Commands

```bash
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](docs/usage.md#tips) for details.

## Configuration

### Global Config

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

```yaml
git:
  human_name: "Your Name"
  human_email: "your@email.com"

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`:

```bash
terok agents                            # 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](docs/usage.md#choosing-which-agents-to-bake-in)
for the full mechanics.

## Contributing

See the [Developer Guide](docs/developer.md).

## License

See [LICENSE](LICENSE) file.

