Metadata-Version: 2.4
Name: terok
Version: 0.8.4
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.7,<4.0)
Requires-Dist: jinja2 (>=3.1,<4.0)
Requires-Dist: platformdirs (>=4.10,<5.0)
Requires-Dist: pydantic (>=2.13,<3.0)
Requires-Dist: requests (>=2.34,<3.0)
Requires-Dist: rich (>=15.0,<16.0)
Requires-Dist: ruamel.yaml (==0.19.1)
Requires-Dist: terok-clearance (>=0.7.3,<0.8.0)
Requires-Dist: terok-executor (>=0.3.0,<0.4.0)
Requires-Dist: terok-sandbox (>=0.4.0,<0.5.0)
Requires-Dist: terok-shield (>=0.7.2,<0.8.0)
Requires-Dist: terok-util (>=0.2.1,<0.3.0)
Requires-Dist: textual-serve (>=1.1,<2.0)
Requires-Dist: textual[syntax] (>=8.2.5,<8.3.0)
Requires-Dist: unique-namer (>=1.6,<2.0)
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.github.io/terok/
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/dev/terok-logo-w.svg">
    <img src="https://terok-ai.github.io/terok/dev/terok-logo-b.svg" alt="terok" width="120">
  </picture>
</p>

# terok

[![PyPI](https://img.shields.io/pypi/v/terok)](https://pypi.org/project/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="https://terok-ai.github.io/terok/dev/img/architecture.svg" alt="terok ecosystem at a glance">
</p>

## Acknowledgements

<table border="0" style="border: none;">
<tr style="border: none;">
<td valign="top" style="border: none;">
<a href="https://www.casus.science"><img src="https://terok-ai.github.io/terok/dev/casus-logo.svg" alt="CASUS" width="120"></a>
<br>
<a href="https://www.hzdr.de"><img src="https://terok-ai.github.io/terok/dev/hzdr-logo.svg" alt="HZDR" width="120"></a>
</td>
<td valign="top" style="border: none;">
Terok was started at the
<br><a href="https://www.casus.science/">Center for Advanced Systems Understanding (CASUS)</a>, an institute of
<br><a href="https://www.hzdr.de/">Helmholtz-Zentrum Dresden-Rossendorf (HZDR)</a> at the end of 2025.
<br>
<br>See also
<br><a href="https://helmholtz.software/software/terok">Terok at HELMHOLTZ.software</a> and the
<br><a href="https://www.casus.science/scientific-computing-core-agentic-ai-for-coding/">topic page</a> at the
<br><a href="https://www.casus.science/scientific-computing-core/">Scientific Computing Core (SCC) group</a> of CASUS.
</td>
</tr>
</table>


## 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 six-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 |
| [terok-util](https://github.com/terok-ai/terok-util) | Shared foundations: CLI registry types, XDG paths, config stack |

## 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 — enables the `systemd-creds` vault
  passphrase tier (TPM2-sealed on systemd ≥ 257); the gate / vault /
  clearance services themselves run per container, no systemd units
- **`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 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.

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

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 (unattended)

```bash
# Run an agent headlessly with a prompt (uses default_agent config; falls back to claude)
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
```

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

