Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/skills/sync-agent-infra/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ Use this map when product behavior, commands, or development workflows change. I
| Sandbox policy schema, presets, or enforcement behavior | `generate-sandbox-policy`, `openshell-cli` |
| Supervisor middleware policy, registrations, runtime, or failure behavior | `generate-sandbox-policy`, `openshell-cli`, `debug-openshell-cluster` |
| Gateway deployment, Helm, runtime drivers, or health checks | `debug-openshell-cluster`, `helm-dev-environment` |
| Inference routing, providers, or `inference.local` behavior | `debug-inference`, `openshell-cli` |
| Inference providers, native inference access, or local model endpoints | `debug-inference`, `openshell-cli` |
| TUI architecture, navigation, data fetching, or UX | `tui-development` |
| Release artifacts or post-publish smoke coverage | `test-release-canary` |
| GitHub Actions workflows, required checks, or CI diagnostics | `watch-github-actions`; also `test-release-canary` for release smoke coverage |
Expand Down
10 changes: 4 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,7 @@ These pipelines connect skills into end-to-end workflows. Individual skill files
| `crates/openshell-conformance-cli/` | Conformance CLI | Distributable `list` and `run` entrypoint for gateway conformance |
| `crates/openshell-server/` | Gateway server | Control-plane API, sandbox lifecycle, auth boundary |
| `crates/openshell-sandbox/` | Sandbox runtime | Container supervision, policy-enforced egress routing |
| `crates/openshell-policy/` | Policy engine | Filesystem, network, process, and inference constraints |
| `crates/openshell-router/` | Privacy router | Privacy-aware LLM routing |
| `crates/openshell-policy/` | Policy engine | Filesystem, network, and process constraints |
| `crates/openshell-bootstrap/` | Gateway metadata | Gateway registration metadata, auth token storage, mTLS bundle storage |
| `crates/openshell-gateway-interceptors/` | Gateway interceptors | Intercepts and transforms configured gRPC requests at the gateway routing boundary |
| `crates/openshell-ocsf/` | OCSF logging | OCSF v1.8.0 event types, builders, shorthand/JSONL formatters, tracing layers |
Expand All @@ -60,12 +59,11 @@ These pipelines connect skills into end-to-end workflows. Individual skill files
| `crates/openshell-driver-mxc/` | MXC compute driver | Windows in-process `ComputeDriver` backend for MXC sandbox execution |
| `crates/openshell-driver-podman/` | Podman compute driver | In-process `ComputeDriver` backend for local Podman sandbox containers |
| `crates/openshell-driver-vm/` | VM compute driver | Standalone libkrun-backed `ComputeDriver` subprocess (embeds its own rootfs + runtime) |
| `crates/openshell-driver-mxc/` | Microsoft MXC compute driver | In-process Windows AppContainer and isolation-session compute backend |
| `crates/openshell-prover/` | Policy prover | Policy verification and proof generation |
| `crates/openshell-server-macros/` | Server macros | Compile-time helpers for gateway RPC authorization |
| `crates/openshell-supervisor-middleware/` | Middleware runtime | Generic middleware registry, remote service integration, and chain execution |
| `crates/openshell-supervisor-middleware-builtins/` | Built-in middleware | First-party in-process middleware implementations |
| `crates/openshell-supervisor-network/` | Network supervisor | Proxying, L7 enforcement, policy evaluation, and inference routing |
| `crates/openshell-supervisor-network/` | Network supervisor | Proxying, L7 enforcement, policy evaluation, and credential injection |
| `crates/openshell-supervisor-process/` | Process supervisor | Process lifecycle, namespace, and bypass monitoring |
| `crates/openshell-vfio/` | VFIO support | PCI and GPU passthrough preparation and lifecycle |
| `python/openshell/` | Python SDK | Python bindings and CLI packaging |
Expand Down Expand Up @@ -116,7 +114,7 @@ Use an OCSF builder + `ocsf_emit!()` for events that represent **observable sand
- SSH authentication (accepted, denied, nonce replay)
- Process lifecycle (start, exit, timeout, signal failure)
- Security findings (unsafe policy, unavailable controls, replay attacks)
- Configuration changes (policy load/reload, TLS setup, inference routes, settings)
- Configuration changes (policy load/reload, TLS setup, settings)
- Application lifecycle (supervisor start, SSH server ready)

### When to use plain tracing
Expand All @@ -138,7 +136,7 @@ Use `info!()`, `debug!()`, `warn!()` for **internal operational plumbing** that
| SSH sessions | `SshActivityBuilder` | Authentication, channel operations |
| Process start/stop | `ProcessActivityBuilder` | Entrypoint lifecycle, signal failures |
| Security alerts | `DetectionFindingBuilder` | Nonce replay, bypass detection, unsafe policy. Dual-emit with the domain event. |
| Policy/config changes | `ConfigStateChangeBuilder` | Policy load, Landlock apply, TLS setup, inference routes, settings |
| Policy/config changes | `ConfigStateChangeBuilder` | Policy load, Landlock apply, TLS setup, settings |
| Supervisor lifecycle | `AppLifecycleBuilder` | Sandbox start, SSH server ready/failed |

### Severity guidelines
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ Public skills live in `skills/` and work without an OpenShell source checkout. I
| --- | --- |
| `openshell-cli` | CLI usage, sandbox lifecycle, provider management, and BYOC workflows |
| `debug-openshell-cluster` | Diagnose gateway deployment and health issues |
| `debug-inference` | Diagnose managed, system, local, and direct external inference issues |
| `debug-inference` | Diagnose provider-native inference and local model endpoint issues |
| `generate-sandbox-policy` | Generate YAML sandbox policies from requirements or API documentation |

Public skills use `openshell --help` for installed command syntax and published OpenShell documentation for product concepts and configuration. They must not depend on repository-relative source or documentation files.
Expand Down
20 changes: 0 additions & 20 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

11 changes: 4 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,33 +105,30 @@ bash examples/sandbox-policy-quickstart/demo.sh

## How It Works

OpenShell isolates each sandbox in its own container with policy-enforced egress routing. A lightweight gateway coordinates sandbox lifecycle, and every outbound connection is intercepted by the policy engine, which does one of three things:
OpenShell isolates each sandbox in its own container with policy-enforced egress routing. A lightweight gateway coordinates sandbox lifecycle, and every outbound connection is intercepted by the policy engine, which either:

- **Allows** — the destination and binary match a policy block.
- **Routes for inference** — strips caller credentials, injects backend credentials, and forwards to the managed model.
- **Denies** — blocks the request and logs it.

| Component | Role |
| ------------------ | -------------------------------------------------------------------------------------------- |
| **Gateway** | Control-plane API that coordinates sandbox lifecycle and acts as the auth boundary. |
| **Sandbox** | Isolated runtime with container supervision and policy-enforced egress routing. |
| **Policy Engine** | Enforces filesystem, network, and process constraints from application layer down to kernel. |
| **Privacy Router** | Privacy-aware LLM routing that keeps sensitive context on sandbox compute. |

OpenShell runs a gateway control plane that manages sandbox lifecycle through a configured compute driver. Supported compute platforms include Docker, Podman, MicroVM, and Kubernetes.

## Protection Layers

OpenShell applies defense in depth across four policy domains:
OpenShell applies defense in depth across three policy domains:

| Layer | What it protects | When it applies |
| ---------- | --------------------------------------------------- | --------------------------- |
| Filesystem | Prevents reads/writes outside allowed paths. | Locked at sandbox creation. |
| Network | Blocks unauthorized outbound connections. | Hot-reloadable at runtime. |
| Process | Blocks privilege escalation and dangerous syscalls. | Locked at sandbox creation. |
| Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. |

Policies are declarative YAML files. Static sections (filesystem, process) are locked at creation; dynamic sections (network, inference) can be hot-reloaded on a running sandbox with `openshell policy set`.
Policies are declarative YAML files. Static sections (filesystem, process) are locked at creation; network policy can be hot-reloaded on a running sandbox with `openshell policy set`.

## Providers

Expand Down Expand Up @@ -174,7 +171,7 @@ Docker-backed GPU sandboxes auto-select CDI when available and otherwise fall ba
| `openshell provider create --type [type] --from-existing` | Create a credential provider from env vars. |
| `openshell policy set <name> --policy file.yaml` | Apply or update a policy on a running sandbox. |
| `openshell policy get <name>` | Show the active policy. |
| `openshell inference set --provider <p> --model <m>` | Configure the `inference.local` endpoint. |
| `openshell sandbox create --provider <p>` | Attach a provider and its endpoint policy. |
| `openshell logs [name] --tail` | Stream sandbox logs. |
| `openshell term` | Launch the real-time terminal UI for debugging. |

Expand Down
2 changes: 0 additions & 2 deletions TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,8 +136,6 @@ def test_multiply(sandbox):
|---|---|---|
| `sandbox_client` | session | gRPC client connected to the active gateway |
| `sandbox` | function | Factory returning a `Sandbox` context manager |
| `inference_client` | session | Client for managing inference routes |
| `mock_inference_route` | session | Creates a mock OpenAI-protocol route for tests |

### Rust CLI E2E (`e2e/rust/`)

Expand Down
26 changes: 11 additions & 15 deletions architecture/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ the **Supervisor**.

The CLI, SDK, and TUI provide user-facing access. The gateway is the
authenticated control plane: it owns API access, durable state, policy and
settings delivery, provider and inference configuration, and relay
coordination. The supervisor runs inside every sandbox workload and is the local
settings delivery, provider configuration, and relay coordination. The
supervisor runs inside every sandbox workload and is the local
security boundary. It launches the agent as a restricted child process and
enforces policy where process identity, filesystem access, network egress, and
runtime credentials are visible.
Expand Down Expand Up @@ -50,7 +50,6 @@ flowchart TB
subgraph DP["Sandbox Data Plane"]
SUP["Supervisor"]
PROXY["Policy proxy"]
ROUTER["Inference router"]
POLICY["OPA policy engine"]
AGENT["Restricted agent process"]
end
Expand Down Expand Up @@ -81,23 +80,20 @@ flowchart TB
AGENT -->|"all ordinary egress"| PROXY
PROXY -->|"evaluate"| POLICY
PROXY -->|"allowed traffic"| EXT["External services"]
PROXY -->|"inference.local"| ROUTER
ROUTER -->|"managed inference"| MODEL["Inference backends"]
```

## Core Boundaries

| Component | Boundary |
|---|---|
| CLI, SDK, TUI | User-facing management surfaces. They talk to the gateway and do not need to know which infrastructure drivers are active. |
| Gateway | Authenticated control plane, API server, durable state, policy and settings delivery, provider and inference config, supervisor session ownership, and relay coordination. |
| Gateway | Authenticated control plane, API server, durable state, policy and settings delivery, provider config, supervisor session ownership, and relay coordination. |
| Compute subsystem | Sandbox lifecycle semantics: creation, deletion, watching, reconciliation, and state transitions. Platform provisioning details belong to the compute driver. |
| Credentials subsystem | Logical provider and credential resolution. Secret storage and platform-native credential access belong to credentials drivers. |
| Control-plane identity | Authentication and authorization for users, operators, and API clients. External identity verification belongs to identity drivers. |
| Sandbox identity | Workload identity for supervisors and sandbox-to-sandbox authorization. Identity issuance or verification belongs to sandbox identity drivers. |
| Supervisor | Sandbox-local security boundary. It prepares isolation, fetches config, injects credentials, runs relay endpoints, starts the proxy, and launches restricted agent processes. |
| Policy proxy | Mandatory egress path for agent traffic. It enforces destination, binary identity, SSRF, TLS/L7, credential injection, and inference interception rules. |
| Inference router | Sandbox-local forwarding for `https://inference.local` to configured model backends. |
| Policy proxy | Mandatory egress path for agent traffic. It enforces destination, binary identity, SSRF, TLS/L7, and credential injection rules. |

## Integrating with the Ecosystem

Expand All @@ -109,14 +105,14 @@ platforms that already provide them.

The gateway owns OpenShell control-plane semantics: sandbox state, lifecycle
ordering, policy and settings resolution, credential mapping, authorization,
inference configuration, and relay coordination. Drivers translate those
and relay coordination. Drivers translate those
semantics into platform-native operations. They should stay thin, preserve
native behavior by default, and report platform lifecycle events back through
the shared contracts.

The supervisor owns OpenShell sandbox semantics. Filesystem policy, process
privilege reduction, network proxying, inference interception, credential
injection, security logging, and gateway relay behavior should remain
privilege reduction, network proxying, credential injection, security logging,
and gateway relay behavior should remain
consistent across runtimes.

This keeps OpenShell usable in local single-player setups, Kubernetes
Expand All @@ -128,8 +124,8 @@ ecosystem.

The gateway and sandbox split control-plane authority from runtime enforcement.
The gateway owns durable platform state: sandboxes, policy revisions, runtime
settings, provider records, inference configuration, session records, and
authorization decisions. A sandbox owns the local execution boundary: process
settings, provider records, session records, and authorization decisions. A
sandbox owns the local execution boundary: process
identity, filesystem access, network egress, credential injection, local logs,
and the agent child process.

Expand All @@ -150,7 +146,7 @@ sandbox configuration API for later revisions. The Windows MXC driver reports
its own readiness and does not expose interactive connect or governed egress.

The gateway delivers desired state; the sandbox applies it locally. Policy,
settings, credentials, and inference routes flow from the gateway to the
settings and credentials flow from the gateway to the
supervisor. The supervisor validates and applies what can change at runtime,
keeps last-known-good config when refresh fails, and leaves static isolation
controls in place until the sandbox is recreated.
Expand All @@ -170,7 +166,7 @@ that crate's `README.md`.
| Document | Purpose |
|---|---|
| [Gateway](gateway.md) | Gateway control plane, auth, APIs, persistence, settings, and relay coordination. |
| [Sandbox](sandbox.md) | Sandbox supervisor, child process isolation, proxy, credentials, inference, connect, and logs. |
| [Sandbox](sandbox.md) | Sandbox supervisor, child process isolation, proxy, credentials, connect, and logs. |
| [Sandbox Limits](sandbox-limits.md) | Sandbox supervisor and egress safety ceilings, ownership rules, current enforcement, and known gaps. |
| [Security Policy](security-policy.md) | Policy model, enforcement layers, policy updates, policy advisor, and security logging. |
| [Compute Runtimes](compute-runtimes.md) | Docker, Podman, Kubernetes, VM, sandbox images, and runtime-specific responsibilities. |
Expand Down
Loading
Loading