mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-29 07:23:25 +08:00
71 lines
6.7 KiB
Plaintext
71 lines
6.7 KiB
Plaintext
---
|
|
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
title: "How OpenShell Works"
|
|
sidebar-title: "How It Works"
|
|
description: "OpenShell architecture overview covering the gateway, sandbox, and policy engine."
|
|
keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Security, Architecture"
|
|
position: 2
|
|
---
|
|
|
|
OpenShell runs sandboxes through a gateway that uses one of four compute platforms: Kubernetes, Docker, Podman, or the experimental MicroVM runtime. Each sandbox is an isolated environment managed through the gateway. Three components work together to keep agents secure.
|
|
|
|
|
|
|
|
## Components
|
|
|
|
The following table describes each component and its role in the system:
|
|
|
|
| Component | Role |
|
|
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| **Gateway** | Control-plane API that coordinates sandbox lifecycle and state, and acts as the auth boundary between clients and sandboxes. |
|
|
| **Sandbox** | Isolated runtime that includes container supervision and policy-enforced egress routing. |
|
|
| **Policy Engine** | Policy definition and enforcement layer for filesystem, network, process, and inference constraints. Defense in depth enforces policies from the application layer down to infrastructure and kernel layers. |
|
|
|
|
## How a Request Flows
|
|
|
|
Every outbound connection from agent code passes through the same decision path:
|
|
|
|
1. The agent process opens an outbound connection (API call, package install, git clone, and so on).
|
|
2. The proxy inside the sandbox intercepts the connection and identifies which binary opened it.
|
|
3. If the target is `https://inference.local`, the proxy handles it as managed inference before policy evaluation. OpenShell strips sandbox-supplied credentials, injects the configured backend credentials, and forwards the request to the managed model endpoint.
|
|
4. For every other destination, the proxy queries the policy engine with the destination, port, and calling binary.
|
|
5. The policy engine returns one of the following decisions. Explicit deny takes precedence over allow, and allow takes precedence over implicit deny.
|
|
|
|
| Decision | When it applies | Outcome |
|
|
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
|
|
| **Explicit Deny** | A deny rule, or a hardening rule such as server-side request forgery (SSRF) protection, a blocked control-plane port, or a Layer 7 (L7) deny, rejects the request even when an allow rule would otherwise permit it. | The connection is blocked and logged. |
|
|
| **Allow** | The destination and binary match a policy block, and no deny rule applies. | Traffic flows directly to the external service. |
|
|
| **Implicit Deny** | No policy block matched. | The connection is blocked and logged. |
|
|
|
|
For REST endpoints, the proxy auto-detects Transport Layer Security (TLS) by peeking the first bytes of each tunnel. When TLS is detected, the proxy terminates it transparently using a per-sandbox ephemeral certificate authority (CA) so each HTTP request can be checked against per-method, per-path rules before forwarding. To trust a corporate or internal CA for upstream traffic, add the PEM-encoded certificate to the sandbox container's trust store at image build time.
|
|
|
|
## Gateway Lifecycle
|
|
|
|
OpenShell preserves gateway state in the configured gateway database. Kubernetes deployments commonly use the Helm chart's persistent volume, while standalone gateway deployments can use local storage or Postgres. Sandbox state depends on the selected compute driver and the storage configured for sandbox workloads.
|
|
|
|
## Observability
|
|
|
|
The sandbox emits operational decisions as Open Cybersecurity Schema Framework (OCSF) v1.7.0 structured logs. The events cover network connections, HTTP requests, SSH sessions, process lifecycle, detection findings, and configuration changes. For event classes and the JSON Lines (JSONL) export format, refer to [OCSF JSON Export](/observability/ocsf-json-export).
|
|
|
|
## Deployment Modes
|
|
|
|
OpenShell supports four deployment modes: Kubernetes, Docker, Podman, and MicroVM. Each mode runs or exposes a gateway, then registers that endpoint with the CLI. The gateway's compute driver determines where sandboxes run.
|
|
|
|
| Mode | Description |
|
|
| -------------- | -------------------------------------------------------------------------------- |
|
|
| **Docker** | The gateway uses Docker to create local sandbox containers. |
|
|
| **Podman** | The gateway uses a Podman-compatible container runtime, commonly rootless. |
|
|
| **Kubernetes** | The Helm chart deploys the gateway and configures the Kubernetes compute driver. |
|
|
| **MicroVM** | The gateway uses the experimental VM compute driver. |
|
|
|
|
You can register multiple gateways and switch between them with `openshell gateway select`. For the full deployment and management workflow, refer to the [Gateways](/sandboxes/manage-gateways) section.
|
|
|
|
## Next Steps
|
|
|
|
Continue with one of the following:
|
|
|
|
- To deploy or register a gateway, refer to [Gateways](/sandboxes/manage-gateways).
|
|
- To create your first sandbox, refer to the [Quickstart](/get-started/quickstart).
|
|
- To learn how OpenShell enforces isolation across all protection layers, refer to [Sandboxes](/sandboxes/about).
|