From f8d2d824ce4cd9ca25d047f4d2ea38df2eb3e21a Mon Sep 17 00:00:00 2001 From: Kirit Thadaka Date: Mon, 9 Mar 2026 16:52:30 -0700 Subject: [PATCH] docs: Simplified the sandbox docs (#186) * Removed network access docs * Simplified docs for sandboxes and inference * Fixed build --- docs/get-started/run-claude.md | 2 +- docs/get-started/run-opencode.md | 2 +- docs/index.md | 3 - docs/inference/configure-routes.md | 4 +- docs/inference/index.md | 4 +- docs/reference/architecture.md | 3 +- docs/reference/cli.md | 3 +- .../network-access-rules.md | 290 ------------------ docs/sandboxes/community-sandboxes.md | 1 - docs/sandboxes/create-and-manage.md | 77 +---- docs/sandboxes/custom-containers.md | 80 ----- docs/sandboxes/index.md | 19 +- docs/sandboxes/providers.md | 37 --- docs/sandboxes/terminal.md | 110 ------- 14 files changed, 21 insertions(+), 614 deletions(-) delete mode 100644 docs/safety-and-privacy/network-access-rules.md delete mode 100644 docs/sandboxes/custom-containers.md delete mode 100644 docs/sandboxes/terminal.md diff --git a/docs/get-started/run-claude.md b/docs/get-started/run-claude.md index d09a23710..3abd231d3 100644 --- a/docs/get-started/run-claude.md +++ b/docs/get-started/run-claude.md @@ -116,4 +116,4 @@ This is useful when you plan to reconnect later or iterate on the policy while t - {doc}`../sandboxes/create-and-manage`: Learn the isolation model and sandbox lifecycle. - {doc}`../sandboxes/providers`: Understand how credentials are injected without exposing them to agent code. - {doc}`../safety-and-privacy/policies`: Customize the default policy or write your own. -- {doc}`../safety-and-privacy/network-access-rules`: Explore the network proxy and per-endpoint rules. +- {doc}`../safety-and-privacy/policies`: Explore network policies and per-endpoint rules. diff --git a/docs/get-started/run-opencode.md b/docs/get-started/run-opencode.md index 00a85bb9a..e088ee4aa 100644 --- a/docs/get-started/run-opencode.md +++ b/docs/get-started/run-opencode.md @@ -252,7 +252,7 @@ $ nemoclaw sandbox delete opencode-sandbox ## Next Steps - {doc}`../safety-and-privacy/policies`: Full reference on policy YAML structure, static and dynamic fields, and enforcement modes. -- {doc}`../safety-and-privacy/network-access-rules`: How the proxy evaluates network rules, L4 and L7 inspection, and TLS termination. +- {doc}`../safety-and-privacy/policies`: How the proxy evaluates network rules and policy enforcement. - {doc}`../inference/index`: Inference route configuration, protocol detection, and transparent rerouting. - {doc}`../sandboxes/providers`: Provider types, credential discovery, and manual and automatic creation. - {doc}`../safety-and-privacy/security-model`: The four protection layers and how they interact. diff --git a/docs/index.md b/docs/index.md index 7c9584fdf..bb094a90d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -204,9 +204,7 @@ get-started/tutorials sandboxes/index sandboxes/create-and-manage sandboxes/providers -sandboxes/custom-containers sandboxes/community-sandboxes -sandboxes/terminal ``` ```{toctree} @@ -216,7 +214,6 @@ sandboxes/terminal safety-and-privacy/index safety-and-privacy/security-model safety-and-privacy/policies -safety-and-privacy/network-access-rules ``` ```{toctree} diff --git a/docs/inference/configure-routes.md b/docs/inference/configure-routes.md index a76f904a5..1b487743b 100644 --- a/docs/inference/configure-routes.md +++ b/docs/inference/configure-routes.md @@ -8,7 +8,7 @@ This guide covers how to create and manage inference routes so that sandboxes can route AI API calls from userland code to policy-controlled backends. You will learn to create routes, connect them to sandboxes through policy, and manage routes across a cluster. :::{note} -Inference routes are for *userland code*, which are scripts and programs that the agent writes and executes inside the sandbox. The agent's own API traffic flows directly through network policies, not through inference routing. Refer to {doc}`../safety-and-privacy/network-access-rules` for the distinction between agent traffic and userland traffic. +Inference routes are for *user code*, which are scripts and programs that the agent writes and executes inside the sandbox. The agent's own API traffic flows directly through network policies, not through inference routing. Refer to {doc}`../safety-and-privacy/policies` for the distinction between agent traffic and user traffic. ::: ## Create a Route @@ -88,5 +88,5 @@ The `inference` section is a dynamic field, so you can add or remove routing hin ## Next Steps - {doc}`index`: understand the inference routing architecture, interception sequence, and routing hints. -- {doc}`../safety-and-privacy/network-access-rules`: configure the network policies that control agent traffic (as opposed to userland inference traffic). +- {doc}`../safety-and-privacy/policies`: configure the network policies that control agent traffic (as opposed to userland inference traffic). - {doc}`../safety-and-privacy/policies`: the full policy iteration workflow. diff --git a/docs/inference/index.md b/docs/inference/index.md index 67f47a308..9e4cbd61d 100644 --- a/docs/inference/index.md +++ b/docs/inference/index.md @@ -13,7 +13,7 @@ to backends you control. Inference routing applies to userland traffic: code that the agent writes or runs, not the agent itself. The agent's own API calls (for example, Claude calling `api.anthropic.com`) go directly through network policy. Refer to -{doc}`/safety-and-privacy/network-access-rules` for the distinction. +{doc}`/safety-and-privacy/policies` for the distinction. ::: ## How It Works @@ -79,5 +79,5 @@ If an intercepted request does not match any known pattern, it is denied. ## Next Steps - {doc}`configure-routes`: Create and manage inference routes. -- {doc}`/safety-and-privacy/network-access-rules`: Understand agent traffic versus +- {doc}`/safety-and-privacy/policies`: Understand agent traffic versus userland traffic and how network rules interact with inference routing. diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md index d36af1d06..2376ec932 100644 --- a/docs/reference/architecture.md +++ b/docs/reference/architecture.md @@ -136,8 +136,7 @@ the proxy. For each connection, the proxy: binary path. 3. Acts on the decision: allow the connection directly, hand it to the privacy router for inference routing, or deny it. Refer to - [How the Proxy Evaluates Connections](../safety-and-privacy/network-access-rules.md#how-the-proxy-evaluates-connections) - for the full decision model. + {doc}`../safety-and-privacy/policies` for the full decision model. For endpoints configured with `protocol: rest` and `tls: terminate`, the proxy performs full L7 inspection: it decrypts TLS, reads the HTTP method and path, diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 9856ee5f4..d5e9a0af5 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -159,8 +159,7 @@ Manage inference routes that intercept and reroute LLM API calls from userland c status, live logs, and policy decisions in a single view. Navigate with `j`/`k`, press `f` to follow live output, `s` to filter by source, and `q` to quit. -Refer to {doc}`/sandboxes/terminal` for the full guide, including how to read log -entries, diagnose blocked connections, and interpret inference interception. +Refer to {doc}`/sandboxes/create-and-manage` for more on monitoring sandboxes and reading log entries. ## Sandbox Name Fallback diff --git a/docs/safety-and-privacy/network-access-rules.md b/docs/safety-and-privacy/network-access-rules.md deleted file mode 100644 index 4ef9bd655..000000000 --- a/docs/safety-and-privacy/network-access-rules.md +++ /dev/null @@ -1,290 +0,0 @@ - - -# Network Access Rules - -Every outbound connection from a sandbox passes through OpenShell's transparent -proxy. Nothing leaves the sandbox directly. The proxy identifies which binary -initiated the connection, evaluates the active policy, and decides what happens -next. - -## How the Proxy Evaluates Connections - -Each outbound connection resolves to one of three outcomes: - -| Outcome | When it applies | What happens | -|------------------------|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------| -| Allow | A `network_policies` entry matches the destination host *and* the calling binary. | Traffic flows directly to the destination. The agent's own API key is used. | -| InspectForInference| No network policy matches, but `inference.allowed_routes` is configured. | The proxy intercepts the connection and hands it to the privacy router, which reroutes it to a configured backend. The route's API key is used. | -| Deny | No network policy matches and no inference route applies. | The connection is blocked. The calling process receives a 403 or connection reset. | - -:::{note} -This is the most important distinction in OpenShell's network model. - -*Agent traffic* is the coding agent (Claude, OpenCode, Codex) calling its own API to get completions. This traffic matches a `network_policies` entry because the policy declares both the endpoint (for example, `api.anthropic.com:443`) and the binary (for example, `/usr/local/bin/claude`). The proxy allows it through directly. The agent's own API key (injected by the provider) is used as-is. - -*Userland traffic* is code that the agent *writes* making inference calls. A Python script calling the OpenAI-compatible API, a data pipeline hitting an LLM endpoint, a test harness querying a model. This traffic does *not* match any network policy because the calling binary (`/usr/bin/python3`) is not listed in the agent's policy entry. The proxy intercepts it, the privacy router reroutes it to a configured backend, and the route's API key is substituted in. The agent's code never touches your real API key. -::: - -```{mermaid} -flowchart TD - A["Outbound connection from sandbox"] --> B["Proxy resolves calling binary\n(/proc/pid/exe, ancestors, cmdline)"] - B --> C{"Network policy matches\n(endpoint + binary)?"} - C -- Yes --> D["Allow: forward directly\nto destination"] - C -- No --> E{"Inference routes\nconfigured?"} - E -- Yes --> F["InspectForInference:\nTLS terminate, check for\ninference pattern"] - F --> G{"Matches inference\npattern?"} - G -- Yes --> H["Route to configured\ninference backend"] - G -- No --> I["Deny: 403"] - E -- No --> I - - style A fill:#ffffff,stroke:#000000,color:#000000 - style B fill:#76b900,stroke:#000000,color:#000000 - style C fill:#76b900,stroke:#000000,color:#000000 - style D fill:#76b900,stroke:#000000,color:#000000 - style E fill:#76b900,stroke:#000000,color:#000000 - style F fill:#76b900,stroke:#000000,color:#000000 - style G fill:#76b900,stroke:#000000,color:#000000 - style H fill:#76b900,stroke:#000000,color:#000000 - style I fill:#ff4444,stroke:#000000,color:#ffffff - - linkStyle default stroke:#76b900,stroke-width:2px -``` - -## Structure of a Network Policy Entry - -Each entry in the `network_policies` section pairs a set of endpoints with a set of binaries. Only the listed binaries can connect to the listed endpoints: - -```yaml -network_policies: - my_rule: - name: my-rule - endpoints: - - host: api.example.com - port: 443 - protocol: rest - tls: terminate - enforcement: enforce - access: full - binaries: - - path: /usr/local/bin/my-agent -``` - -The key (`my_rule`) is a logical name for reference. The `name` field is the human-readable label that appears in logs and the OpenShell Terminal. - -## Endpoints - -Each endpoint entry controls access to a single host-port combination. Refer to [Endpoint Object](../reference/policy-schema.md#endpoint-object) for the full field reference. - -The `access` field provides presets: `full` (all methods), `read-only` (`GET`, `HEAD`, `OPTIONS`), or `read-write` (`GET`, `HEAD`, `OPTIONS`, `POST`, `PUT`, `PATCH`). - -### Custom Rules - -When access presets are not granular enough, define explicit allow rules. Each rule specifies a method and a path pattern: - -```yaml -endpoints: - - host: github.com - port: 443 - protocol: rest - tls: terminate - enforcement: enforce - rules: - - allow: - method: GET - path: /**/info/refs* - - allow: - method: POST - path: /**/git-upload-pack -``` - -This example allows Git fetch operations (read-only clone and pull) while blocking push operations. Path patterns use glob syntax. - -If a request does not match any rule, it is denied (in `enforce` mode) or logged (in `audit` mode). - -## Binaries - -The `binaries` list specifies which executables are permitted to use the endpoint. Each entry has a `path` field that the proxy matches against the calling process. - -The proxy resolves the calling binary through several mechanisms, evaluated in order: - -| Match type | Example | Description | -|-------------------|---------|-------------| -| Exact path | `/usr/local/bin/claude` | Matches the binary at exactly this path. | -| Ancestor process | `/usr/local/bin/claude` | Matches if any ancestor in the process tree has this path. A Node.js subprocess spawned by Claude matches a `claude` entry. | -| Cmdline path | `/usr/local/bin/opencode` | Matches against `/proc/pid/cmdline` for interpreted languages where the `exe` link points to the interpreter. | -| Glob pattern | `/sandbox/.vscode-server/**` | Matches any executable under the directory tree. | - -```yaml -binaries: - - path: /usr/local/bin/claude - - path: /usr/bin/node - - path: /sandbox/.vscode-server/** -``` - -## L7 Inspection - -To inspect HTTPS traffic at the HTTP level, you need both `protocol: rest` and `tls: terminate` on the endpoint: - -```yaml -endpoints: - - host: api.example.com - port: 443 - protocol: rest - tls: terminate - enforcement: enforce - access: full -``` - -With both fields set, the proxy terminates the TLS connection, decrypts the HTTP request, evaluates it against the `access` preset or custom `rules`, and re-encrypts before forwarding to the destination. - -:::{warning} -Without `tls: terminate` on port 443, the proxy cannot decrypt the traffic. L7 rules (`access`, `rules`) are not evaluated because the HTTP payload is encrypted. The connection is handled at L4 only: allowed or denied based on host and port, with no HTTP-level access control. -::: - -### Bare Endpoints (L4-Only) - -Endpoints declared without `protocol` or `tls` are L4-only: - -```yaml -endpoints: - - host: registry.npmjs.org - port: 443 -``` - -The proxy allows the TCP connection through to the destination without decrypting or inspecting the payload. Use L4-only entries for non-HTTP traffic, package registries where you need connectivity but not method-level control, or endpoints where TLS termination is not desired. - -:::{warning} -With L4-only rules, you have no control over *what* is sent to the endpoint: only *whether* the connection is allowed. Any binary listed in the entry can send any data to the host. If you need to restrict HTTP methods or paths, add `protocol: rest` and `tls: terminate`. -::: - -## Forward Proxy Mode - -The sandbox proxy supports two request modes: CONNECT tunnels (the default for -HTTPS) and forward proxy (for plain HTTP to private endpoints). - -When a client inside the sandbox sets `HTTP_PROXY` and makes a plain `http://` -request, standard HTTP libraries send a forward proxy request instead of a -CONNECT tunnel. The proxy handles these transparently. - -### Security Constraints - -Forward proxy mode is restricted to private IP endpoints that are explicitly -allowed by policy. Plain HTTP traffic never reaches the public internet. All -three conditions must be true: - -1. The network policy explicitly allows the destination. -2. The matched endpoint has `allowed_ips` configured. -3. All resolved IP addresses are RFC 1918 private (`10/8`, `172.16/12`, `192.168/16`). - -If any condition fails, the proxy returns 403. - -| Condition | Forward proxy | CONNECT | -|---|---|---| -| Public IP, no `allowed_ips` | 403 | Allowed (standard SSRF check) | -| Public IP, with `allowed_ips` | 403 (private-IP gate) | Allowed if IP in allowlist | -| Private IP, no `allowed_ips` | 403 | 403 (SSRF block) | -| Private IP, with `allowed_ips` | Allowed | Allowed | -| `https://` scheme | 403 (must use CONNECT) | N/A | - -### Policy Configuration - -No new policy fields are needed. The same `network_policies` entry that enables -CONNECT access to a private endpoint also enables forward proxy access. Add -`allowed_ips` to the endpoint: - -```yaml -network_policies: - internal_service: - name: internal-service - endpoints: - - host: 10.86.8.223 - port: 8000 - allowed_ips: - - "10.86.8.223/32" - binaries: - - path: /usr/local/bin/python3.12 -``` - -With this policy, both CONNECT and forward proxy requests to the endpoint work: - -```python -import httpx -resp = httpx.get("http://10.86.8.223:8000/api/", - proxy="http://10.200.0.1:3128") -``` - -### Limitations - -- Forward proxy v1 injects `Connection: close` (no keep-alive). Each connection handles exactly one request-response exchange. -- L7 inspection is not performed on forwarded traffic. -- `https://` URLs must use the CONNECT tunnel, not the forward proxy path. - -## Enforcement Modes - -Each endpoint can operate in one of two enforcement modes: - -| Mode | Behavior on violation | -|-----------|-----------------------| -| `enforce` | Blocks the request and returns HTTP 403 to the calling process. The violation is logged. | -| `audit` | Logs the violation but forwards the traffic to the destination. The agent is not interrupted. | - -:::{tip} -Start with `enforcement: audit` when developing a new policy. Audit mode shows you what *would* be blocked without actually breaking the agent. After the policy is correct and you have confirmed that no legitimate traffic is flagged, switch to `enforcement: enforce`. -::: - -## Putting It Together - -Here is a realistic policy snippet for an agent that needs to reach its own API, clone Git repositories (read-only), and install npm packages: - -```yaml -network_policies: - agent_api: - name: agent-api - endpoints: - - host: api.anthropic.com - port: 443 - protocol: rest - tls: terminate - enforcement: enforce - access: full - binaries: - - path: /usr/local/bin/claude - - path: /usr/bin/node - - github: - name: github - endpoints: - - host: github.com - port: 443 - protocol: rest - tls: terminate - enforcement: enforce - rules: - - allow: - method: GET - path: /**/info/refs* - - allow: - method: POST - path: /**/git-upload-pack - binaries: - - path: /usr/bin/git - - npm_registry: - name: npm-registry - endpoints: - - host: registry.npmjs.org - port: 443 - binaries: - - path: /usr/bin/npm - - path: /usr/bin/node - - path: /usr/local/bin/npm - - path: /usr/local/bin/node -``` - -## Next Steps - -- [Write Sandbox Policies](policies.md): The full iterative workflow for authoring, testing, and updating policies. -- {doc}`security-model`: Threat scenarios and how the four protection layers work together. diff --git a/docs/sandboxes/community-sandboxes.md b/docs/sandboxes/community-sandboxes.md index f176abdf0..0124f4506 100644 --- a/docs/sandboxes/community-sandboxes.md +++ b/docs/sandboxes/community-sandboxes.md @@ -91,5 +91,4 @@ or anything else), consider contributing it back so others can use it. ## Next Steps - {doc}`create-and-manage`: Full sandbox lifecycle management -- {doc}`custom-containers`: Build a fully custom container with BYOC - {doc}`../safety-and-privacy/policies`: Customize the policy applied to any sandbox diff --git a/docs/sandboxes/create-and-manage.md b/docs/sandboxes/create-and-manage.md index f9653d1b1..cb0db002d 100644 --- a/docs/sandboxes/create-and-manage.md +++ b/docs/sandboxes/create-and-manage.md @@ -16,18 +16,12 @@ Ensure the following are installed before creating sandboxes. ## Create a Sandbox -The simplest way to create a sandbox is to specify a trailing command: - ```console $ nemoclaw sandbox create -- claude ``` -The CLI bootstraps the runtime (if this is your first run), discovers your -credentials, applies the default policy, and drops you into the sandbox. +If you have an existing gateway, a sandbox will be created within that gateway or if you don't have one, one will be created for you. -You can customize creation with flags like `--name`, `--provider`, `--policy`, -`--upload`, `--keep`, `--forward`, and `--from`. Refer to the -[CLI Reference](../reference/cli.md) for the full flag list. A fully specified creation command might look like: @@ -75,17 +69,6 @@ Open an SSH session into a running sandbox: $ nemoclaw sandbox connect my-sandbox ``` -### VS Code Remote-SSH - -Export the sandbox SSH configuration and append it to your SSH config: - -```console -$ nemoclaw sandbox ssh-config my-sandbox >> ~/.ssh/config -``` - -Then open VS Code, install the Remote - SSH extension if you have not -already, and connect to the host named `my-sandbox`. - ## View Logs Stream and filter sandbox logs to monitor agent activity and diagnose policy decisions. @@ -105,17 +88,21 @@ Use flags to filter and follow output: | `--level` | Filter by severity | `--level warn` | | `--since` | Show logs from a time window | `--since 5m` | -Combine flags to narrow in on what you need: +## Monitor your Sandbox + +NemoClaw Terminal is a real-time dashboard that combines sandbox status and live logs in a single view. ```console -$ nemoclaw logs my-sandbox --tail --source sandbox --level warn --since 5m +$ nemoclaw term ``` -:::{tip} -For a real-time dashboard that combines sandbox status and logs in one view, -run `nemoclaw term`. Refer to {doc}`terminal` for details on reading log entries and -diagnosing blocked connections. -::: +The dashboard shows: + +- **Sandbox status** — name, phase, image, attached providers, age, and active port forwards. +- **Live log stream** — outbound connections, policy decisions, and inference interceptions as they happen. Logs are labeled by source: `sandbox` (proxy and policy events) or `gateway` (lifecycle events). + +Use the terminal to spot blocked connections (`action=deny` entries) and inference interceptions (`action=inspect_for_inference` entries). If a connection is blocked unexpectedly, add the host to your network policy — refer to {doc}`../safety-and-privacy/policies` for the workflow. + ## Transfer Files @@ -138,39 +125,6 @@ You can also upload files at creation time with the `--upload` flag on `nemoclaw sandbox create`. ::: -## Port Forwarding - -Forward a port from the sandbox to your host machine. This runs in the -foreground by default: - -```console -$ nemoclaw forward start 8080 my-sandbox -``` - -Add `-d` to run the forward in the background: - -```console -$ nemoclaw forward start 8080 my-sandbox -d -``` - -List active port forwards: - -```console -$ nemoclaw forward list -``` - -Stop a port forward: - -```console -$ nemoclaw forward stop 8080 my-sandbox -``` - -:::{note} -You can set up port forwarding at creation time with the `--forward` flag on -`nemoclaw sandbox create`, which is convenient when you know upfront that -your workload exposes a service. -::: - ## Delete Sandboxes Remove sandboxes when they are no longer needed. Deleting a sandbox stops all processes, releases cluster resources, and purges injected credentials. @@ -181,15 +135,8 @@ Delete a sandbox by name: $ nemoclaw sandbox delete my-sandbox ``` -You can delete multiple sandboxes in a single command: - -```console -$ nemoclaw sandbox delete sandbox-a sandbox-b sandbox-c -``` - ## Next Steps - {doc}`community-sandboxes`: Use pre-built sandboxes from the community catalog - {doc}`providers`: Create and attach credential providers -- {doc}`custom-containers`: Build and run your own container image - {doc}`../safety-and-privacy/policies`: Control what the agent can access \ No newline at end of file diff --git a/docs/sandboxes/custom-containers.md b/docs/sandboxes/custom-containers.md deleted file mode 100644 index 6eb1583a1..000000000 --- a/docs/sandboxes/custom-containers.md +++ /dev/null @@ -1,80 +0,0 @@ - - -# Custom Containers - -Build a custom container image and run it as a OpenShell sandbox. - -## Prerequisites - -Ensure the following are installed before building custom container sandboxes. - -- OpenShell CLI installed (`pip install nemoclaw`) -- Docker running on your machine -- A Dockerfile for your workload - -## Step 1: Create a Sandbox from Your Dockerfile - -Point `--from` at the directory containing your Dockerfile: - -```console -$ nemoclaw sandbox create --from ./my-app --keep --name my-app -``` - -The CLI builds the image locally using Docker, pushes it into the cluster, and -creates the sandbox, all in one step. No external container registry is -needed. - -You can also pass a full container image reference if the image is already -built: - -```console -$ nemoclaw sandbox create --from my-registry.example.com/my-image:latest --keep --name my-app -``` - -## Step 2: Forward Ports - -If your container runs a service, forward the port to your host: - -```console -$ nemoclaw forward start 8080 my-app -d -``` - -The `-d` flag runs the forward in the background so you can continue using -your terminal. - -## Step 3: Iterate - -When you change your Dockerfile, delete the sandbox and recreate: - -```console -$ nemoclaw sandbox delete my-app && \ - nemoclaw sandbox create --from ./my-app --keep --name my-app -``` - -## Shortcut: Create with Forwarding and a Startup Command - -You can combine port forwarding and a startup command in a single step: - -```console -$ nemoclaw sandbox create --from ./my-app --forward 8080 --keep -- ./start-server.sh -``` - -This creates the sandbox, sets up port forwarding on port 8080, and runs -`./start-server.sh` as the sandbox command. - -:::{warning} -NemoClaw does not support distroless and `FROM scratch` images. The -supervisor requires glibc, `/proc`, and a shell to operate. Images missing -`iproute2` or required Linux capabilities will fail to start in proxy mode. -Ensure your base image includes these dependencies. -::: - -## Next Steps - -- {doc}`create-and-manage`: Full sandbox lifecycle commands -- {doc}`providers`: Attach credentials to your custom container -- {doc}`/safety-and-privacy/policies`: Write a policy tailored to your workload -- {doc}`/safety-and-privacy/security-model`: Understand the isolation layers applied to custom images \ No newline at end of file diff --git a/docs/sandboxes/index.md b/docs/sandboxes/index.md index 18a20d331..1cf23a105 100644 --- a/docs/sandboxes/index.md +++ b/docs/sandboxes/index.md @@ -26,20 +26,7 @@ inside a Docker container on your machine. You do not need to set this up manually. The first time you run a command that needs a cluster (such as `nemoclaw sandbox create`), the CLI provisions -one automatically. This is the "Runtime ready" line you see in the output. -Subsequent commands reuse the existing cluster. - -For teams or when you need more resources, you can deploy the cluster to a -remote host instead of your local machine: - -```console -$ nemoclaw gateway start --remote user@host -``` - -Refer to [Remote Deployment](../about/architecture.md) for -details. If you have multiple clusters (local and remote), switch between them -with `nemoclaw gateway select `. Refer to the -[CLI Reference](../reference/cli.md#gateway-commands) for the full command set. +one automatically. ## Next Steps @@ -47,9 +34,5 @@ with `nemoclaw gateway select `. Refer to the sandboxes. - {doc}`providers`: Create and attach credential providers so agents can authenticate with external services. -- {doc}`custom-containers`: Build and run your own container image inside a - sandbox. - {doc}`community-sandboxes`: Use pre-built sandboxes from the community catalog. -- {doc}`terminal`: Monitor sandbox status and live activity in a terminal - dashboard. diff --git a/docs/sandboxes/providers.md b/docs/sandboxes/providers.md index 1dc7d26f8..4427ae5b7 100644 --- a/docs/sandboxes/providers.md +++ b/docs/sandboxes/providers.md @@ -102,42 +102,6 @@ $ nemoclaw sandbox create -- claude This detects `claude` as a known tool, finds your `ANTHROPIC_API_KEY`, creates a provider, attaches it to the sandbox, and launches Claude Code. -## How Credentials Flow - -Credentials follow a secure path from your machine into the agent process. - -```{mermaid} -flowchart LR - A["You create a provider"] --> B["Attach provider\nto sandbox at creation"] - B --> C["Sandbox starts"] - C --> D["Supervisor fetches\ncredentials from gateway"] - D --> E["Credentials injected into\nagent process + SSH sessions"] - - style A fill:#ffffff,stroke:#000000,color:#000000 - style B fill:#ffffff,stroke:#000000,color:#000000 - style C fill:#76b900,stroke:#000000,color:#000000 - style D fill:#76b900,stroke:#000000,color:#000000 - style E fill:#76b900,stroke:#000000,color:#000000 - - linkStyle default stroke:#76b900,stroke-width:2px -``` - -1. You create a provider with credentials from your environment or - specified explicitly. -2. You attach the provider to a sandbox at creation time using the - `--provider` flag (one or more providers can be attached). -3. The sandbox starts. The supervisor process initializes. -4. The supervisor fetches credentials from the OpenShell gateway at runtime. - The system does not store credentials in the sandbox specification. It retrieves them on demand. -5. Credentials are injected into the agent process as environment variables. - They are also available in SSH sessions when you connect to the sandbox. - -:::{warning} -The system does not store credentials in the sandbox container specification. The supervisor fetches them at runtime and holds them only in process memory. This -means you cannot find credentials in container inspection, image layers, or -environment dumps of the container spec. -::: - ## Supported Provider Types The following provider types are supported. @@ -161,5 +125,4 @@ environment variable names and values yourself with `--credential`. ## Next Steps - {doc}`create-and-manage`: Full sandbox lifecycle management -- {doc}`custom-containers`: Use providers with custom container images - {doc}`../safety-and-privacy/security-model`: Why credential isolation matters \ No newline at end of file diff --git a/docs/sandboxes/terminal.md b/docs/sandboxes/terminal.md deleted file mode 100644 index 43888e767..000000000 --- a/docs/sandboxes/terminal.md +++ /dev/null @@ -1,110 +0,0 @@ - - -# Terminal - -NemoClaw Terminal is a terminal dashboard that displays sandbox status and live activity in a single view. Use it to monitor agent behavior, diagnose blocked connections, and observe inference interception in real time. - -```console -$ nemoclaw term -``` - -## Sandbox Status - -The status pane at the top of the dashboard displays the following sandbox metadata: - -- Name and phase (`Provisioning`, `Ready`, `Error`) -- Image running in the sandbox -- Providers attached and their available credentials -- Age since creation -- Port forwards currently active - -A phase other than `Ready` indicates the sandbox is still initializing or has encountered an error. Inspect the logs pane for details. - -## Live Log Stream - -The logs pane streams activity in real time. Outbound connections, policy decisions, and inference interceptions appear as they occur. - -Log entries originate from two sources: - -- sandbox: The sandbox supervisor (proxy decisions, policy enforcement, SSH connections, process lifecycle). -- gateway: The control plane (sandbox creation, phase changes, policy distribution). - -Press `f` to enable follow mode and auto-scroll to new entries. - -## Diagnosing Blocked Connections - -Entries with `action=deny` indicate connections blocked by policy: - -``` -22:35:19 sandbox INFO CONNECT action=deny dst_host=registry.npmjs.org dst_port=443 -``` - -Each deny entry contains the following fields: - -| Field | Description | -|---|---| -| `action=deny` | Connection was blocked by the network policy. | -| `dst_host` | Destination host the process attempted to reach. | -| `dst_port` | Destination port (typically 443 for HTTPS). | -| `src_addr` | Source address inside the sandbox. | -| `policy` | Policy rule that was evaluated, or `-` if no rule matched. | - -To resolve a blocked connection: - -1. Add the host to the network policy if the connection is legitimate. Refer to {doc}`../safety-and-privacy/policies` for the iteration workflow. -2. Leave it blocked if the connection is unauthorized. - -## Diagnosing Inference Interception - -Entries with `action=inspect_for_inference` indicate intercepted API calls: - -``` -22:35:37 sandbox INFO CONNECT action=inspect_for_inference dst_host=integrate.api.nvidia.com dst_port=443 -22:35:37 sandbox INFO Intercepted inference request, routing locally kind=chat_completion -``` - -This sequence indicates: - -- No network policy matched the connection (the endpoint and binary combination is not in the policy). -- Inference routing is configured (`allowed_routes` is non-empty), so the proxy intercepted the call instead of denying it. -- The proxy TLS-terminated the connection, detected an inference API pattern, and routed the request through the privacy router. - -:::{note} -If these calls should go directly to the destination rather than through inference routing, the most likely cause is a binary path mismatch. The process making the HTTP call does not match any binary listed in the network policy. - -Check the log entry for the binary path, then update the `binaries` list in the policy. Refer to {doc}`../safety-and-privacy/network-access-rules` for details on binary matching. -::: - -## Filtering and Navigation - -The dashboard provides filtering and navigation controls: - -- Press `s` to filter logs by source. Display only `sandbox` logs (policy decisions) or only `gateway` logs (lifecycle events). -- Press `f` to toggle follow mode. Auto-scroll to the latest entries. -- Press `Enter` on a log entry to open the detail view with the full message. -- Use `j` / `k` to navigate up and down the log list. - -## Keyboard Shortcuts - -The following keyboard shortcuts are available in the terminal dashboard. - -| Key | Action | -|---|---| -| `j` / `k` | Navigate down / up in the log list. | -| `Enter` | Open detail view for the selected entry. | -| `g` / `G` | Jump to top / bottom. | -| `f` | Toggle follow mode (auto-scroll to new entries). | -| `s` | Open source filter (sandbox, gateway, or all). | -| `Esc` | Return to the main view / close detail view. | -| `q` | Quit. | - -## Related Topics - -For deeper dives into topics covered by the terminal dashboard, refer to the following guides. - -- Blocked connections: Follow {doc}`../safety-and-privacy/policies` to pull the current policy, add the missing endpoint, and push an update without restarting the sandbox. -- Inference interception: Refer to {doc}`../safety-and-privacy/network-access-rules` for the distinction between agent traffic (routed directly) and userland traffic (routed through inference routing). -- Troubleshooting: Refer to {doc}`../troubleshooting` for troubleshooting tips and diagnostics.