terok-sandbox

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

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 never sees 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 gate forwards to upstream automatically (online mode) or after operator review (gatekeeping mode).
• Shield firewall — installs the terok-shield OCI hooks at setup time and drives the firewall at runtime.
• Clearance in-supervisor — each container's supervisor hosts the terok-clearance hub, verdict server, and desktop notifier, so the operator can authorise blocked outbound connections live. services.clearance: mute starts each task with those prompts silenced, and off leaves the clearance arm out entirely; either way the shield still refuses every blocked connection, and records the refused destinations in its audit log while shield.audit is on (the default). A change applies at the next start of the task: create, recreate, or a terok restart.
• Setup as one call — idempotent terok-sandbox setup installs the shield + supervisor OCI hooks and provisions the encrypted credentials DB; terok-sandbox uninstall reverses it.

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,
    KrunRuntime,
    NullRuntime,
    ContainerRuntime,
    # Vault + credentials
    CredentialDB,
    SSHManager,
    NoPassphraseError,
    WrongPassphraseError,
    # Gate
    GateServer,
    GitGate,
    mint_gate_token,
    # Shield adapter
    ShieldManager,
    ShieldHooks,
    check_environment,
    # Per-container wiring / setup state
    write_sidecar,
    remove_container_state,
    sandbox_uninstall,
    check_setup,
)

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

CLI

Command	Purpose
terok-sandbox setup	Install shield + supervisor OCI hooks, provision the credentials DB; idempotent
terok-sandbox uninstall	Reverse of setup
terok-sandbox prepare / run / cleanup	Wire a user-owned container into the sandbox services
terok-sandbox doctor	Run host-side sandbox health checks
terok-sandbox vault …	Vault status / unlock / lock / passphrase-tier management
terok-sandbox gate …	Git gate inspection (gate path <project>)
terok-sandbox shield …	Shield hooks install / status / direct control
terok-sandbox ssh …	Per-scope SSH key management in the credentials DB
terok-sandbox credentials encrypt-db	Encrypt (migrate) a plaintext credentials DB

SSH keys

terok-sandbox ssh add myscope
terok-sandbox ssh add myscope -c gitlab-deploy
terok-sandbox ssh list --scope myscope
terok-sandbox ssh pub myscope
terok-sandbox ssh default myscope 2
terok-sandbox ssh pub myscope --key-id 2

ssh add always creates another key. Without -c / --comment, its name is the next unused myscope-N; an interactive terminal prompts to accept or override that suggestion. Imports preserve their original comment unless -c / --comment overrides it.

The first assigned key becomes the scope's default. Adding or renaming keys does not change it. ssh list marks the default with *; ssh default selects another assigned key to offer first through the SSH agent socket. ssh pub prints every assigned public key, one per line with the default first, or just the key selected by --key-id. ssh add --force replaces the scope's existing keys with a fresh default.

Requirements

• Linux with Podman (rootless, ≥ 5.6 recommended)
• systemd ≥ 257 — 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.