terok-executor 0.2.0

Single-agent task runner for hardened Podman containers

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.

Quick start

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:

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

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 composes many concurrent runs across many projects. Below it, terok-executor delegates the host-side security boundary (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.

License

Apache-2.0