kirit93 · Mar 10, 2026 · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026 · Mar 10, 2026
diff --git a/docs/about/architecture.md b/docs/about/architecture.md
@@ -1,9 +1,9 @@
 ---
 title:
-  page: "Architecture Overview"
-  nav: "Architecture"
-description: "High-level overview of the OpenShell architecture: gateway, sandboxes, policy engine, and privacy router."
-keywords: ["openshell architecture", "sandbox architecture", "agent isolation", "k3s", "policy engine"]
+  page: "How OpenShell Works"
+  nav: "How It Works"
+description: "OpenShell architecture: gateway, sandbox, policy engine, and privacy router."
+keywords: ["nemoclaw architecture", "sandbox architecture", "agent isolation", "k3s", "policy engine"]
 topics: ["generative_ai", "cybersecurity"]
 tags: ["ai_agents", "sandboxing", "security", "architecture"]
 content:
@@ -19,63 +19,48 @@ content:
 
 # How OpenShell Works
 
-OpenShell runs as a [k3s](https://k3s.io/) Kubernetes cluster inside a Docker container.
-Each sandbox is an isolated Kubernetes pod managed by the OpenShell control plane.
-Four components work together to keep agents secure.
+OpenShell runs as a [k3s](https://k3s.io/) Kubernetes cluster inside a Docker container. Each sandbox is an isolated Kubernetes pod managed through the gateway. Four components work together to keep agents secure.
 
-```{mermaid}
-flowchart LR
-    CLI["CLI"] -->|gRPC| GW["Gateway"]
-    GW --> SBX["Sandbox"]
-
-    subgraph SBX["Sandbox"]
-        direction TB
-        AGENT["Agent Process"] -->|All traffic| PROXY["Network Proxy"]
-        PROXY -->|Evaluate| OPA["Policy Engine"]
-    end
-
-    PROXY -->|Allowed traffic| EXT["External Services"]
-
-    style CLI fill:#ffffff,stroke:#000000,color:#000000
-    style GW fill:#76b900,stroke:#000000,color:#000000
-    style SBX fill:#f5f5f5,stroke:#000000,color:#000000
-    style AGENT fill:#ffffff,stroke:#000000,color:#000000
-    style PROXY fill:#76b900,stroke:#000000,color:#000000
-    style OPA fill:#76b900,stroke:#000000,color:#000000
-    style EXT fill:#ffffff,stroke:#000000,color:#000000
-
-    linkStyle default stroke:#76b900,stroke-width:2px
+```{image} architecture.svg
+:alt: OpenShell architecture diagram showing the NemoClaw component layout
+:align: center
 ```
 
 ## Components
 
-OpenShell consists of the following components.
-
-Gateway
-: The control-plane API that manages sandbox lifecycle, stores encrypted credentials, distributes policies, and terminates SSH tunnels. The CLI communicates exclusively with the gateway—it never talks to sandbox pods directly.
+| Component | Role |
+|---|---|
+| **Gateway** | Control-plane API that coordinates sandbox lifecycle and state, acts as the auth boundary, and brokers requests across the platform. |
+| **Sandbox** | Isolated runtime that includes container supervision and policy-enforced egress routing. |
+| **Policy Engine** | Policy definition and enforcement layer for filesystem, network, and process constraints. Defense in depth enforces policies from the application layer down to infrastructure and kernel layers. |
+| **Privacy Router** | Privacy-aware LLM routing layer that keeps sensitive context on sandbox compute and routes based on cost and privacy policy. |
 
-Sandbox
-: An isolated pod that runs your agent. Each sandbox contains a **supervisor** (sets up isolation and starts the agent), an **L7 proxy** (intercepts and evaluates every outbound connection), and the agent process itself.
-
-Policy Engine
-: Evaluates declarative YAML policies that define filesystem, network, and process constraints. The proxy queries the engine on every outbound connection. Policies can be hot-reloaded without restarting the agent.
+## How a Request Flows
 
-Privacy Router
-: Intercepts LLM API calls and routes them to local or self-hosted backends based on your routing policy. Sensitive prompts and completions stay on infrastructure you control.
+Every outbound connection from agent code passes through the same decision path:
 
-## How a Request Flows
+1. The agent process opens an outbound connection (API call, package install, git clone, etc.).
+2. The proxy inside the sandbox intercepts the connection and identifies which binary opened it.
+3. The proxy queries the policy engine with the destination, port, and calling binary.
+4. The policy engine returns one of three decisions:
+   - **Allow** — the destination and binary match a policy block. Traffic flows directly to the external service.
+   - **Route for inference** — no policy block matched, but inference routing is configured. The privacy router intercepts the request, strips the original credentials, injects the configured backend credentials, and forwards to the managed model endpoint.
+   - **Deny** — no match and no inference route. The connection is blocked and logged.
 
-OpenShell works in the following way:
+For REST endpoints with TLS termination enabled, the proxy also decrypts TLS and checks each HTTP request against per-method, per-path rules before allowing it through.
 
-1. The agent makes an outbound connection (for example, an API call).
-2. The L7 proxy intercepts the connection and identifies the calling process.
-3. The proxy queries the policy engine with the destination and process identity.
-4. Based on the policy decision, the proxy either allows the connection, routes it through the privacy router for inference, or denies it.
+## Deployment Modes
 
-## Remote Deployment
+OpenShell can run locally or on a remote host. The architecture is identical in both cases — only the Docker container location changes.
 
-OpenShell can also run on a remote host. Deploy with `openshell gateway start --remote user@host`, then set up a tunnel with `openshell gateway tunnel`. The architecture is identical—only the Docker container location changes.
+- **Local**: the k3s cluster runs inside Docker on your workstation. The CLI provisions it automatically on first use.
+- **Remote**: the cluster runs on a remote host. Deploy with `nemoclaw gateway start --remote user@host`. For example, connect to your DGX Spark
+  ```console
+  $ nemoclaw gateway start --remote <username>@<spark-SSID>.local
+  $ nemoclaw status
+  ```
 
----
+## Next Steps
 
-For detailed component internals, refer to the [Architecture Reference](../reference/architecture.md).
+- [Quickstart](get-started.md): Create your first sandbox.
+- [Sandboxes](../sandboxes/index.md): Learn how OpenShell enforces isolation across all protection layers.
diff --git a/docs/about/architecture.svg b/docs/about/architecture.svg
diff --git a/docs/about/get-started.md b/docs/about/get-started.md
@@ -0,0 +1,132 @@
+---
+title:
+  page: "Quickstart"
+  nav: "Quickstart"
+description: "Install the OpenShell CLI and create your first sandboxed AI agent in two commands."
+keywords: ["nemoclaw install", "quickstart", "sandbox create", "getting started"]
+topics: ["generative_ai", "cybersecurity"]
+tags: ["ai_agents", "sandboxing", "installation", "quickstart"]
+content:
+  type: get_started
+  difficulty: technical_beginner
+  audience: [engineer, data_scientist]
+---
+
+<!--
+  SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+# Quickstart
+
+This page gets you from zero to a running, policy-enforced sandbox in two commands.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- Python 3.12 or later
+- [uv](https://docs.astral.sh/uv/) installed
+- Docker Desktop running on your machine <!-- TODO: add compatible version -->
+
+## Install the OpenShell CLI
+
+Activate your virtual environment:
+
+```bash
+uv venv && source .venv/bin/activate
+```
+
+Install the CLI:
+
+```bash
+uv pip install nemoclaw
+```
+
+## Connect to a Remote Gateway (Optional)
+
+If you're running locally, skip this step — the CLI creates a gateway automatically when you create your first sandbox.
+
+:::::{tab-set}
+
+::::{tab-item} Brev
+
+:::{note}
+Deploy an OpenShell gateway on Brev by hitting **Deploy** on the [OpenShell Launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3AaK9NmCzWp3pVyUDNNFBt805FT).
+:::
+
+Once the instance is running, find the gateway URL in the Brev console under **Using Secure Links**. Copy the shareable URL for **port 8080** — this is the gateway endpoint.
+
+```console
+$ nemoclaw gateway add https://<your-port-8080-url>.brevlab.com
+$ nemoclaw status
+```
+
+::::
+
+::::{tab-item} DGX Spark
+
+:::{note}
+Set up your Spark with NVIDIA Sync first, or make sure SSH access is configured (e.g., SSH keys added to the host).
+:::
+
+Deploy to a DGX Spark machine over SSH:
+
+```console
+$ nemoclaw gateway start --remote <username>@<spark-ssid>.local
+$ nemoclaw status
+```
+
+Once `nemoclaw status` shows the gateway as healthy, all subsequent commands route through the SSH tunnel.
+
+::::
+
+:::::
+
+## Create Your First OpenShell Sandbox
+
+Choose the tab that matches your agent:
+
+::::{tab-set}
+
+:::{tab-item} Claude Code
+```console
+$ nemoclaw sandbox create -- claude
+```
+
+The CLI prompts you to create a provider from local credentials — type `yes` to continue. If `ANTHROPIC_API_KEY` is set in your environment, it is picked up automatically. If not, you can configure it from inside the sandbox after it launches.
+:::
+
+:::{tab-item} OpenCode
+```console
+$ nemoclaw sandbox create -- opencode
+```
+
+The CLI prompts you to create a provider from local credentials — type `yes` to continue. If `OPENAI_API_KEY` or `OPENROUTER_API_KEY` is set in your environment, it is picked up automatically. If not, you can configure it from inside the sandbox after it launches.
+:::
+
+:::{tab-item} Codex
+```console
+$ nemoclaw sandbox create -- codex
+```
+
+The CLI prompts you to create a provider from local credentials — type `yes` to continue. If `OPENAI_API_KEY` is set in your environment, it is picked up automatically. If not, you can configure it from inside the sandbox after it launches.
+:::
+
+:::{tab-item} Community Sandbox
+```console
+$ nemoclaw sandbox create --from openclaw
+```
+
+The `--from` flag pulls a pre-built sandbox definition from the [NemoClaw Community](https://github.com/NVIDIA/NemoClaw-Community) catalog. Each definition bundles a container image, a tailored policy, and optional skills into a single package.
+:::
+
+::::
+
+## Next Steps
+
+You now have a working sandbox! From here, you can:
+
+- **Follow a guided tutorial** — set up scoped GitHub repo access in {doc}`/tutorials/github-sandbox`.
+- **Learn how sandboxes work** — see {doc}`/sandboxes/create-and-manage` for the full lifecycle.
+- **Write your own policies** — see {doc}`/sandboxes/policies` for custom access rules.
diff --git a/docs/about/overview.md b/docs/about/overview.md
@@ -2,8 +2,8 @@
 title:
   page: "Overview of NVIDIA OpenShell"
   nav: "Overview"
-description: "OpenShell is the safe, private runtime for autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure."
-keywords: ["openshell", "ai agent sandbox", "agent security", "agent isolation", "inference routing"]
+description: "NemoClaw is the safe, private runtime for autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure."
+keywords: ["nemoclaw", "ai agent sandbox", "agent security", "agent isolation", "inference routing"]
 topics: ["generative_ai", "cybersecurity"]
 tags: ["ai_agents", "sandboxing", "security", "privacy", "inference_routing"]
 content:
@@ -19,62 +19,47 @@ content:
 
 # Overview of NVIDIA OpenShell
 
-NVIDIA OpenShell is an open-source runtime that executes autonomous AI agents inside sandboxed environments with kernel-level isolation. It prevents agents from accessing unauthorized files, exfiltrating data, leaking credentials, or making uncontrolled network requests. A single declarative YAML policy governs filesystem, network, process, and inference protections across all sandboxes and is hot-reloadable without restarting running agents.
+NVIDIA OpenShell is an open-source runtime for executing autonomous AI agents in sandboxed environments with kernel-level isolation. It combines sandbox runtime controls and a declarative YAML policy so teams can run agents without giving them unrestricted access to local files, credentials, and external networks.
 
-## Common Challenges with AI Agents
+## Why OpenShell Exists
 
-AI agents are most useful when they have broad access to reading files, installing packages, calling APIs, and using credentials. However, this same access makes them dangerous. An unrestricted agent can leak your API keys, send proprietary code to unauthorized endpoints, or reach infrastructure it was never meant to touch.
+AI agents are most useful when they can read files, install packages, call APIs, and use credentials. That same access can create material risk. OpenShell is designed for this tradeoff: preserve agent capability while enforcing explicit controls over what the agent can access.
 
-Conventional containers do not solve this. They isolate processes from the host, but they do not control what an agent does *inside* the container — which files it reads, which hosts it contacts, or where it sends your prompts.
+## Common Risks and Controls
 
-## Benefits of Using OpenShell
+The table below summarizes common failure modes and how OpenShell mitigates them.
 
-OpenShell addresses these risks through defense-in-depth enforcement across four policy domains: filesystem, network, process, and inference.
+| Threat | Without controls | With OpenShell |
+|---|---|---|
+| Data exfiltration | Agent uploads source code or internal files to unauthorized endpoints. | Network policies allow only approved destinations; other outbound traffic is denied. |
+| Credential theft | Agent reads local secrets such as SSH keys or cloud credentials. | Filesystem restrictions (Landlock) confine access to declared paths only. |
+| Unauthorized API usage | Agent sends prompts or data to unapproved model providers. | Privacy routing and network policies control where inference traffic can go. |
+| Privilege escalation | Agent attempts `sudo`, setuid paths, or dangerous syscall behavior. | Unprivileged process identity and seccomp restrictions block escalation paths. |
 
-:::{dropdown} 🛡️ Kernel-Level Isolation
-OpenShell enforces isolation at the Linux kernel level using Landlock for filesystem restrictions, seccomp for system call filtering, and network namespaces for traffic control. These mechanisms operate below the application layer, so agents cannot bypass them regardless of the tools or languages they use.
-:::
+## Protection Layers at a Glance
 
-:::{dropdown} 📜 Declarative Policy Enforcement
-A single YAML policy file defines all security boundaries for a sandbox: allowed filesystem paths, permitted network destinations, restricted processes, and inference routing rules. Policies are hot-reloadable, so you can tighten or relax rules on a running sandbox without restarting the agent.
-:::
+OpenShell applies defense in depth across four policy domains:
 
-:::{dropdown} 🔐 Credential Containment
-Credentials are injected into sandboxes as environment variables at startup and are scoped to the sandbox's isolated namespace. They cannot be read by processes outside the sandbox, and network policies prevent agents from transmitting them to unauthorized endpoints.
-:::
+| 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. |
 
-:::{dropdown} 🔀 Private Inference Routing
-The built-in inference router intercepts LLM API calls and redirects them to local or self-hosted backends based on your routing policy. Sensitive prompts and completions stay on infrastructure you control. Routes are configurable per sandbox and can be updated without restarting agents.
-:::
+For details, refer to [Built-in Default Policy](../sandboxes/index.md#built-in-default-policy) and [Customize Sandbox Policies](../sandboxes/policies.md).
 
-:::{dropdown} 🔍 Full L7 Traffic Inspection
-Every outbound TCP connection from a sandbox passes through an L7 proxy that resolves the calling process, evaluates the destination against the active policy, and either allows, denies, or reroutes the request. For REST endpoints, the proxy decrypts TLS, inspects HTTP method and path, and applies fine-grained access rules.
-:::
+## Common Use Cases
 
-## Use Cases
-
-The following are common use cases for OpenShell.
-
-:::{dropdown} 💻 Secure Coding Agents
-Run AI coding assistants such as Claude Code, OpenCode, or OpenClaw inside a sandbox where they can read and modify project files but cannot access SSH keys, cloud credentials, or files outside the project directory. Network policies restrict which package registries and APIs the agent can reach.
-:::
-
-:::{dropdown} 🏢 Private Enterprise Development
-Route all LLM inference through self-hosted NVIDIA NIM endpoints or private API backends. Proprietary source code and internal documentation stay on your infrastructure and are never sent to third-party LLM providers.
-:::
-
-:::{dropdown} ✅ Compliance and Audit
-Declarative policies serve as auditable security controls. Each sandbox runs under a well-defined policy that specifies exactly what the agent can access. Policy files can be version-controlled and reviewed as part of your security and compliance processes.
-:::
-
-:::{dropdown} 📦 Community and Custom Sandbox Images
-Use pre-built sandbox images from the [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) catalog or bring your own container. Community sandboxes bundle domain-specific tools, policies, and skills, while custom containers let you package any environment your agents need.
-:::
+- **Secure coding agents**: Run Claude Code, OpenCode, or OpenClaw with constrained file and network access.
+- **Private enterprise development**: Route inference to self-hosted or private backends while keeping sensitive context under your control.
+- **Compliance and audit**: Treat policy YAML as version-controlled security controls that can be reviewed and audited.
+- **Reusable environments**: Use community sandbox images or bring your own containerized runtime.
 
 ---
 
 ## Next Steps
 
 - [Architecture Overview](architecture.md): Understand the components that make up the OpenShell runtime.
-- [Get Started](../index.md): Install the CLI and create your first sandbox.
-- [Safety and Privacy](../safety-and-privacy/index.md): Learn how OpenShell enforces isolation across all protection layers.
+- [Quickstart](get-started.md): Install the CLI and create your first sandbox.
+- [Sandboxes](../sandboxes/index.md): Learn how OpenShell enforces isolation across all protection layers.