Metadata-Version: 2.4
Name: terok-sandbox
Version: 0.1.0
Summary: Hardened Podman container runner with gate server and shield integration
License-Expression: Apache-2.0
License-File: LICENSE
License-File: LICENSES/Apache-2.0.txt
Keywords: podman,containers,sandbox,security,isolation
Author: Jiri Vyskocil
Author-email: jiri@vyskocil.com
Maintainer: Jiri Vyskocil
Maintainer-email: jiri@vyskocil.com
Requires-Python: >=3.12,<4.0
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 :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Dist: aiohttp (>=3.9)
Requires-Dist: cryptography (>=46.0.7)
Requires-Dist: jinja2 (>=3.1)
Requires-Dist: keyring (>=25.0)
Requires-Dist: packaging (>=24)
Requires-Dist: platformdirs (>=4.10.0)
Requires-Dist: prompt-toolkit (>=3.0)
Requires-Dist: pydantic (>=2.9)
Requires-Dist: ruamel.yaml (>=0.18)
Requires-Dist: sqlcipher3 (>=0.6.2)
Requires-Dist: terok-clearance (>=0.7.0,<0.8.0)
Requires-Dist: terok-shield (>=0.7.0,<0.8.0)
Requires-Dist: terok-util (>=0.1.0,<0.2.0)
Project-URL: Changelog, https://github.com/terok-ai/terok-sandbox/blob/master/CHANGELOG.md
Project-URL: Documentation, https://terok-ai.github.io/terok-sandbox/
Project-URL: Homepage, https://terok.ai/
Project-URL: Issues, https://github.com/terok-ai/terok-sandbox/issues
Project-URL: Repository, https://github.com/terok-ai/terok-sandbox
Project-URL: Security, https://github.com/terok-ai/terok-sandbox/security/policy
Description-Content-Type: text/markdown

# terok-sandbox

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

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

<p align="center">
  <img src="docs/architecture.svg" alt="terok ecosystem — terok-sandbox sits between the per-task launcher and the firewall it installs">
</p>

## 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](https://github.com/terok-ai/terok-shield) OCI hooks at setup time and drives the firewall at runtime.
- **Clearance install** — wires the desktop notifier daemon
  [terok-clearance](https://github.com/terok-ai/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](https://github.com/terok-ai/terok-executor)) and
multi-task orchestrators
([terok](https://github.com/terok-ai/terok)) treat the sandbox as a
black-box "give me a hardened container."  Below it, it composes
[terok-shield](https://github.com/terok-ai/terok-shield) for egress
filtering and [terok-clearance](https://github.com/terok-ai/terok-clearance)
for the operator-in-the-loop verdict path.

## Public API

```python
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`](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 |
| `terok-gate` | Long-running gate daemon (systemd unit entry point) |
| `terok-vault` | Long-running vault token broker (systemd unit entry point) |

## Requirements

- Linux with **Podman** (rootless, ≥ 5.6 recommended)
- **systemd** user session (for gate / vault / clearance services)
- **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

```bash
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](LICENSES/Apache-2.0.txt).

