mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-19 05:50:41 +08:00
65 lines
4.4 KiB
Plaintext
65 lines
4.4 KiB
Plaintext
---
|
|
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
title: "About Gateways and Sandboxes"
|
|
sidebar-title: "About Gateways and Sandboxes"
|
|
description: "Understand gateways, gateway types, sandbox lifecycle, supported agents, built-in default policy, and network access rules in OpenShell."
|
|
keywords: "Generative AI, Cybersecurity, Gateway, Sandboxing, AI Agents, Security, Policy, Isolation"
|
|
position: 1
|
|
---
|
|
|
|
Every OpenShell deployment starts with a *gateway* and one or more *sandboxes*. The gateway is the control plane that manages sandbox lifecycle, providers, and policies. A sandbox is the data plane, a safe, private execution environment where an AI agent runs. Each sandbox runs with multiple layers of protection that prevent unauthorized data access, credential exposure, and network exfiltration. Protection layers include filesystem restrictions (Landlock), system call filtering (seccomp), network namespace isolation, and a privacy-enforcing HTTP CONNECT proxy.
|
|
|
|
## Gateway Compute Platforms
|
|
|
|
A gateway provisions sandboxes, brokers CLI requests, enforces policies, and manages provider credentials. OpenShell supports multiple compute platforms, so the gateway can run sandboxes wherever your workload requires.
|
|
|
|
| Platform | Where Sandboxes Run | Best For |
|
|
|---|---|---|
|
|
| Docker | Containers on the gateway host | Solo development, quick iteration, and single-machine gateways. |
|
|
| Podman | Rootless containers on the gateway host | Workstations that avoid a rootful Docker daemon. |
|
|
| Kubernetes | Pods in an operator-managed cluster | Shared clusters and cloud environments. |
|
|
| MicroVM | VM-backed sandboxes | Experimental stronger-isolation workflows. |
|
|
|
|
All compute platforms expose the same gateway API surface. Sandboxes, policies, and providers work the same after the CLI registers the gateway endpoint. The difference is how the gateway creates sandbox workloads and how operators expose the gateway to users.
|
|
|
|
<Tip>
|
|
For local development, start a Docker-backed gateway from a source checkout with `mise run gateway:docker`, then register it with `openshell gateway add http://127.0.0.1:18080 --local --name local`.
|
|
|
|
</Tip>
|
|
|
|
## Sandbox Lifecycle
|
|
|
|
Every sandbox moves through a defined set of phases:
|
|
|
|
| Phase | Description |
|
|
|---|---|
|
|
| Provisioning | The runtime is setting up the sandbox environment, injecting credentials, and applying your policy. |
|
|
| Ready | The sandbox is running. The agent process is active and all isolation layers are enforced. You can connect, sync files, and view logs. |
|
|
| Error | Something went wrong during provisioning or execution. Check logs with `openshell logs` for details. |
|
|
| Deleting | The sandbox is being torn down. The system releases resources and purges credentials. |
|
|
|
|
## Sandbox Policies
|
|
|
|
OpenShell ships a built-in policy that covers common agent workflows out of the box.
|
|
When you create a sandbox without `--policy`, the default policy is applied. It controls three areas.
|
|
|
|
| Layer | What It Controls | How It Works |
|
|
|---|---|---|
|
|
| Filesystem | What the agent can access on disk | Paths are split into read-only and read-write sets. [Landlock LSM](https://docs.kernel.org/security/landlock.html) enforces these restrictions at the kernel level. |
|
|
| Network | What the agent can reach on the network | Each policy block pairs allowed destinations (host and port) with allowed binaries (executable paths). The proxy matches every outbound connection to the binary that opened it. Both must match or the connection is denied. |
|
|
| Process | What privileges the agent has | The agent runs as an unprivileged user with seccomp filters that block dangerous system calls. No `sudo`, no `setuid`, no path to elevated privileges. |
|
|
|
|
For the full breakdown of each default policy block and agent compatibility details, refer to [Default Policy](/reference/default-policy).
|
|
|
|
For the full policy structure with annotated YAML examples, refer to [Policies](/sandboxes/policies).
|
|
|
|
## Next Steps
|
|
|
|
Continue with one of the following:
|
|
|
|
- To create your first sandbox, refer to [Manage Sandboxes](/sandboxes/manage-sandboxes).
|
|
- To supply API keys or tokens, refer to [Manage Providers](/sandboxes/manage-providers).
|
|
- To control what the agent can access, refer to [Policies](/sandboxes/policies).
|
|
- To use a pre-built environment, refer to the [Community Sandboxes](/sandboxes/community-sandboxes) catalog.
|