terok-sandbox 0.3.1

Hardened Podman container runner with gate server and shield integration

terok-sandbox

The hardened-Podman runtime — terok-sandbox launches per-task containers with a credential vault, a gated git server.

What it provides

• Hardened container lifecycle — rootless Podman containers.
• Credential vault — long-lived secrets stay in an encrypted database on the host. The container receives short-lived phantom tokens and do not see the real credentials
• Per-task git gate — a token-authenticated HTTP mirror of an arbitrary upstream git repository. Tasks clone and push through the gate, and the operator forwards to upstream after review.
• Shield firewall — installs the terok-shield OCI hooks at setup time and drives the firewall at runtime.
• Clearance install — wires the desktop notifier daemon terok-clearance onto blocked outbound connections, so the operator can authorise destinations live.
• Setup as one call — idempotent sandbox_setup() installs the OCI hooks; sandbox_uninstall() uninstalls.

Where it sits in the stack

terok-sandbox is the boundary layer. Above it, single-task callers (terok-executor) and multi-task orchestrators (terok) treat the sandbox as a black-box "give me a hardened container." Below it, it composes terok-shield for egress filtering and terok-clearance for the operator-in-the-loop verdict path.

Public API

from terok_sandbox import (
    # Lifecycle
    Sandbox, SandboxConfig, RunSpec, VolumeSpec, Sharing,
    # Runtime backends
    PodmanRuntime, NullRuntime, ContainerRuntime,
    # Vault
    VaultManager, CredentialDB, SSHManager,
    start_vault, stop_vault, ensure_vault_reachable,
    # Gate
    GateServerManager, TokenStore, GitGate,
    start_daemon, stop_daemon, create_token,
    # Shield adapter
    ShieldState, make_shield,
    # Setup / teardown
    sandbox_setup, sandbox_uninstall, needs_setup,
)

The full export list lives in src/terok_sandbox/__init__.py.

CLI

Command	Purpose
terok-sandbox setup	Install hooks, vault, gate, notifier; idempotent
terok-sandbox uninstall	Reverse of setup
terok-sandbox doctor	Run health checks against installed services
terok-sandbox vault …	Vault management subcommands
terok-sandbox gate …	Gate management subcommands
terok-sandbox shield …	Shield install / status / direct control
terok-sandbox ssh …	Per-container SSH key provisioning

Requirements

• Linux with Podman (rootless, ≥ 5.6 recommended)
• systemd user session — optional; backs the systemd-creds vault passphrase tier (gate / vault / clearance run inside the per-container supervisor, no systemd units)
• nftables (nft binary) — provided by terok-shield's runtime
• D-Bus session bus — for the clearance notifier path; the system degrades gracefully when D-Bus is absent
• Python 3.12+

Installation

pip install terok-sandbox

For most users this dependency is pulled in transitively by terok-executor or terok. Install it directly only when building a custom orchestrator on top of the sandbox API.

License

Apache-2.0 — see LICENSES/Apache-2.0.txt.