Metadata-Version: 2.4
Name: terok-executor
Version: 0.1.0
Summary: Single-agent task runner for hardened Podman containers
License-Expression: Apache-2.0
License-File: LICENSE
License-File: LICENSES/Apache-2.0.txt
Keywords: podman,containers,agent,ai,coding-agent
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 :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Dist: Jinja2 (>=3.1)
Requires-Dist: agent-client-protocol (>=0.10.1)
Requires-Dist: prompt-toolkit (>=3.0)
Requires-Dist: pydantic (>=2.9)
Requires-Dist: rich (>=13.0)
Requires-Dist: ruamel.yaml (>=0.18)
Requires-Dist: terok-sandbox (>=0.1.0,<0.2.0)
Requires-Dist: terok-util (>=0.1.0,<0.2.0)
Requires-Dist: tomli-w (>=1.0)
Project-URL: Changelog, https://github.com/terok-ai/terok-executor/blob/master/CHANGELOG.md
Project-URL: Documentation, https://terok-ai.github.io/terok-executor/
Project-URL: Homepage, https://terok.ai/
Project-URL: Issues, https://github.com/terok-ai/terok-executor/issues
Project-URL: Repository, https://github.com/terok-ai/terok-executor
Project-URL: Security, https://github.com/terok-ai/terok-executor/security/policy
Description-Content-Type: text/markdown

# terok-executor

[![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-executor)](https://api.reuse.software/info/github.com/terok-ai/terok-executor)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=terok-ai_terok-executor&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=terok-ai_terok-executor)

One command to run an AI coding agent inside a hardened, rootless
Podman container.

`terok-executor` builds the container, launches the agent against
the directory you point it at, and keeps real credentials on the
host.  Use it on its own as a CLI, or import its `AgentRunner` from
Python when you want library-grade control.

<p align="center">
  <img src="docs/img/architecture.svg" alt="terok ecosystem — terok-executor sits between project orchestration and the hardened runtime">
</p>

## Quick start

```bash
pip install terok-executor
terok-executor run claude ~/my-workspace
```

The first `run` interactively offers any missing prerequisites — sandbox
services, container images, agent credentials.
Mandatory items (services, images) block the launch if
declined; optional ones (SSH key, auth) print the consequence and
proceed.

Individual steps would be:

```bash
terok-executor setup                               # install sandbox services + build base images
terok-executor auth claude                         # authenticate (OAuth or API key)
terok-executor run claude <dir> -p "Fix the bug"   # run the agent with an initial prompt
```

## Use as a library

```python
from terok_executor import AgentRunner

runner = AgentRunner()
runner.run_headless(
    agent="claude",
    repo=".",
    prompt="Fix the failing test in test_auth.py",
    max_turns=25,
)
```

`AgentRunner` exposes four launch methods — `run_headless`,
`run_interactive`, `run_web`, `run_tool` — all with the same
hardening guarantees.

## Supported agents

| Agent | Auth | Description |
|-------|------|-------------|
| Claude Code | OAuth*, API key | Anthropic Claude Code |
| Codex | OAuth*, API key | OpenAI Codex CLI |
| Vibe | API key | Mistral Vibe |
| OpenCode | API key | Generic LLM endpoint driver — bundled defaults for Helmholtz Blablador, KISSKI AcademicCloud, and your own endpoint |
| gh | OAuth, API key | GitHub CLI |
| glab | API key | GitLab CLI |
| CodeRabbit | API key | CodeRabbit (sidecar tool) |
| SonarCloud | API key | SonarCloud scanner (sidecar tool) |

\* Claude and Codex OAuth are experimental, and support must be explicitly allowed in the config file. 

`terok-executor agents` lists the live roster (add `--all` to
include the tool entries).

## Where it sits in the stack

terok-executor is the per-task layer.  Above it,
[terok](https://github.com/terok-ai/terok) composes many concurrent
runs across many projects.  Below it, terok-executor delegates the
host-side security boundary
([terok-sandbox](https://github.com/terok-ai/terok-sandbox)): the
credential vault, the git gate, the egress firewall hooks, the
systemd service lifecycle.

## Commands

| Command | Description |
|---------|-------------|
| `run` | Launch an agent (headless, interactive, or web) |
| `setup` | Bootstrap sandbox services + container images |
| `uninstall` | Remove sandbox services + container images |
| `auth` | Authenticate a provider |
| `agents` | List the agent roster |
| `build` | Build base + agent images explicitly |
| `run-tool` | Run a sidecar tool (CodeRabbit, SonarCloud) |
| `list` | List running containers |
| `stop` | Stop a running container |
| `show-config` | Print the effective `SandboxConfig` as YAML (diffable across orchestrators) |
| `vault` | Vault management (start, stop, status, install, routes) |

### Config override

Two top-level flags (precede the subcommand, like `docker --config`):

- `--config PATH` — read this `config.yml` instead of the layered system/user paths (sets `TEROK_CONFIG_FILE` for the invocation).
- `--raw` — ignore any `config.yml`; use sandbox/executor dataclass defaults only.

Higher-layer orchestrators (such as `terok`) typically construct a `SandboxConfig` from their own resolution chain and pass it into the executor as a library; the public expectation is that, for the fields they own in `config.yml`, the resulting sub-environment matches what standalone `terok-executor` would produce against the same file.  Use `show-config` on both sides to verify.

## Development

See the [Developer Guide](https://terok-ai.github.io/terok-executor/developer/).

## License

[Apache-2.0](LICENSES/Apache-2.0.txt)

