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 -p "Fix the bug"

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

* Claude and Codex OAuth are experimental.

terok-executor agents list lists the live roster (add --all to include tools and harness-driven providers).

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 per-container supervisor lifecycle (OCI createRuntime/poststop hooks).

Commands

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