### Quick Start: Setup and Run VM

Source: https://github.com/nvidia/openshell/blob/main/crates/openshell-vm/README.md

Use these commands for a one-time setup and to build and run the VM.

```bash
mise run vm:setup
```

```bash
mise run vm
```

--------------------------------

### Manual Onboarding and Gateway Setup

Source: https://github.com/nvidia/openshell/blob/main/examples/openclaw.md

Run these commands inside the created sandbox to complete the onboarding process and start the gateway in the background. Ensure to redirect output to a log file.

```sh
openclaw onboard
nohup openclaw gateway run > /tmp/gateway.log 2>&1 &
exit
```

--------------------------------

### Run OpenShell Driver VM Quick Start

Source: https://github.com/nvidia/openshell/blob/main/crates/openshell-driver-vm/README.md

Executes the start.sh script for runtime setup, building, codesigning, and environment wiring. The first run may take a few minutes for staging and building the rootfs.

```shell
crates/openshell-driver-vm/start.sh
```

```shell
make -C crates/openshell-driver-vm start
```

--------------------------------

### Start Gateway CLI Command

Source: https://github.com/nvidia/openshell/blob/main/docs/CONTRIBUTING.mdx

Use shell code blocks for copyable CLI examples. Do not prefix commands with '$'.

```shell
openshell gateway start
```

--------------------------------

### Full Example

Source: https://github.com/nvidia/openshell/blob/main/docs/reference/policy-schema.mdx

A comprehensive example demonstrating network policies for GitHub and npm registry access.

```APIDOC
### Full Example

The following policy grants read-only GitHub API access and npm registry access:

```yaml
network_policies:
  github_rest_api:
    name: github-rest-api
    endpoints:
      - host: api.github.com
        port: 443
        protocol: rest
        enforcement: enforce
        access: read-only
    binaries:
      - path: /usr/local/bin/claude
      - path: /usr/bin/node
      - path: /usr/bin/gh
  npm_registry:
    name: npm-registry
    endpoints:
      - host: registry.npmjs.org
        port: 443
    binaries:
      - path: /usr/bin/npm
      - path: /usr/bin/node
```
```

--------------------------------

### Install OpenShell CLI

Source: https://context7.com/nvidia/openshell/llms.txt

Installs the OpenShell CLI using a script or the uv package manager. Recommended to use the binary installation.

```bash
# Binary installation (recommended)
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
```

```bash
# Using uv package manager
uv tool install -U openshell
```

```bash
# Verify installation
openshell --help
```

--------------------------------

### Common Workflows: First Time Setup

Source: https://github.com/nvidia/openshell/blob/main/crates/openshell-vm/README.md

Commands for initial setup, including downloading the runtime and building/running the VM for the first time.

```bash
# First time setup
mise run vm:setup              # download pre-built runtime (~30s)
mise run vm                    # build + run
```

--------------------------------

### k3s Server Command Example

Source: https://github.com/nvidia/openshell/blob/main/architecture/gateway-single-node.md

This command is used to start the k3s server within the OpenShell container. It includes configurations for disabling Traefik, adding TLS SANs for local and remote access, and mounting persistent storage.

```bash
server --disable=traefik --tls-san=127.0.0.1 --tls-san=localhost --tls-san=host.docker.internal
```

--------------------------------

### Install OpenShell using Binary

Source: https://github.com/nvidia/openshell/blob/main/README.md

Installs the latest stable release of OpenShell using a script. To install a specific version, set the OPENSHELL_VERSION environment variable.

```bash
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
```

--------------------------------

### Install Z3 on Ubuntu/Debian

Source: https://github.com/nvidia/openshell/blob/main/CONTRIBUTING.md

Installs the Z3 solver library using apt. This is required for the openshell-prover crate.

```bash
# Ubuntu / Debian
sudo apt install libz3-dev
```

--------------------------------

### Install OpenShell using PyPI

Source: https://github.com/nvidia/openshell/blob/main/README.md

Installs the latest stable release of OpenShell from PyPI using uv. To install a specific version, use 'uv tool install openshell==<version>'.

```bash
uv tool install -U openshell
```

--------------------------------

### Complete OpenShell Policy Example

Source: https://github.com/nvidia/openshell/blob/main/architecture/security-policy.md

A comprehensive example demonstrating all OpenShell policy features, including filesystem access, process execution, and various network policy configurations for L4 and L7 traffic.

```yaml
version: 1

filesystem_policy:
  include_workdir: true
  read_only:
    - /usr
    - /lib
    - /proc
    - /dev/urandom
    - /app
    - /etc
  read_write:
    - /sandbox
    - /tmp
    - /dev/null

landlock:
  compatibility: best_effort

process:
  run_as_user: sandbox
  run_as_group: sandbox

network_policies:
  # L4-only: Claude Code can reach Anthropic APIs (no L7 inspection)
  claude_code:
    name: claude_code
    endpoints:
      - { host: api.anthropic.com, port: 443 }
      - { host: statsig.anthropic.com, port: 443 }
      - { host: sentry.io, port: 443 }
    binaries:
      - { path: /usr/local/bin/claude }

  # L7 + auto-TLS: Full access with HTTPS inspection (TLS terminated automatically)
  claude_code_inspected:
    name: claude_code_inspected
    endpoints:
      - host: api.anthropic.com
        port: 443
        protocol: rest
        enforcement: enforce
        access: full
    binaries:
      - { path: /usr/local/bin/claude }

  # L7 with access preset: Read-only API access (GET, HEAD, OPTIONS)
  github_readonly:
    name: github_readonly
    endpoints:
      - host: api.github.com
        port: 8080
        protocol: rest
        enforcement: audit
        access: read-only
    binaries:
      - { path: /usr/bin/curl }

  # L7 with explicit rules: Fine-grained method+path control
  internal_api:
    name: internal_api
    endpoints:
      - host: api.internal.svc
        port: 8080
        protocol: rest
        enforcement: enforce
        rules:
          - allow:
              method: GET
              path: "/api/v1/**"
          - allow:
              method: POST
              path: "/api/v1/data"
    binaries:
      - { path: /usr/bin/curl }

  # L4-only: Git operations via glab CLI
  gitlab:
    name: gitlab
    endpoints:
      - { host: gitlab.com, port: 443 }
    binaries:
      - { path: /usr/bin/glab }

  # Glob binary pattern: Any binary in /usr/bin/ can reach this endpoint
  monitoring:
    name: monitoring
    endpoints:
      - { host: metrics.internal, port: 9090 }
    binaries:
      - { path: "/usr/bin/*" }

  # Private IP access: host + allowed_ips (SSRF allowlist)
  internal_database:
    name: internal_database
    endpoints:
      - host: db.internal.corp
        port: 5432
        allowed_ips:
          - "10.0.5.0/24"
    binaries:
      - { path: /usr/bin/curl }

  # Hostless private IP access: any hostname on port 8080 within the allowlist
  private_services:
    name: private_services
    endpoints:
      - port: 8080
        allowed_ips:
          - "10.0.5.0/24"
          - "10.0.6.0/24"
    binaries:
      - { path: /usr/bin/curl }

  # Host wildcard: allow any subdomain of example.com on dual ports
  example_apis:
    name: example_apis
    endpoints:
      - host: "*.example.com"
        ports:
          - 443
          - 8443
    binaries:
      - { path: /usr/bin/curl }

  # Multi-port with L7: same L7 rules applied across two ports (TLS auto-terminated)
  multi_port_l7:
    name: multi_port_l7
    endpoints:
      - host: api.internal.svc
        ports: [8080, 9090]
        protocol: rest
        enforcement: enforce
        access: read-only
    binaries:
      - { path: /usr/bin/curl }

  # Forward proxy + CONNECT: private service accessible via plain HTTP or tunnel
  # With allowed_ips set and the destination being a private IP, both
  # `http://10.86.8.223:8000/path` (forward proxy) and
  # `CONNECT 10.86.8.223:8000` (tunnel) work.
  computer_control:
    name: computer-control
    endpoints:
      - host: 10.86.8.223
        port: 8000
        allowed_ips:
          - "10.86.8.223/32"
    binaries:
      - { path: /usr/local/bin/python3.13 }
```

--------------------------------

### Allow Any Subdomain of example.com on Port 443

Source: https://github.com/nvidia/openshell/blob/main/architecture/security-policy.md

Use '*.example.com' to match any subdomain of example.com. Ensure the pattern starts with '*.'.

```yaml
network_policies:
  example_wildcard:
    name: example_wildcard
    endpoints:
      - host: "*.example.com"
        port: 443
    binaries:
      - { path: /usr/bin/curl }
```

--------------------------------

### Install OpenShell CLI

Source: https://github.com/nvidia/openshell/blob/main/architecture/README.md

Installs the OpenShell command-line interface using pip. This is the first step for interacting with the OpenShell platform.

```bash
pip install <package>
```

--------------------------------

### Formatted CLI Output Example

Source: https://github.com/nvidia/openshell/blob/main/STYLEGUIDE.md

This example demonstrates the recommended style for structured CLI output, including blank lines after headings and indented key-value fields.

```text
Created sandbox:

  Id: cddeeb6d-a4d3-4158-a4d1-bd931f743700
  Name: sandbox-cddeeb6d
  Namespace: openshell
```

--------------------------------

### Initialize Tracing and Logging

Source: https://github.com/nvidia/openshell/blob/main/architecture/gateway.md

Sets up tracing by creating a `TracingLogBus` and installing a subscriber that outputs to stdout and publishes log events.

```rust
Creates a TracingLogBus and installs a tracing subscriber that writes to stdout and publishes log events keyed by sandbox_id into the bus.
```

--------------------------------

### Start OpenShell Cluster

Source: https://github.com/nvidia/openshell/blob/main/examples/local-inference/README.md

Starts an OpenShell cluster. This is a prerequisite for configuring cluster-wide inference settings.

```bash
mise run cluster
openshell status
```

--------------------------------

### Deploy Gateway with Custom Port

Source: https://context7.com/nvidia/openshell/llms.txt

Starts a local gateway on a specified port. Use this to avoid conflicts with other services.

```bash
openshell gateway start --port 9090
```

--------------------------------

### Create Sandbox with Forwarding (CLI)

Source: https://github.com/nvidia/openshell/blob/main/architecture/sandbox-connect.md

Creates a sandbox and automatically starts a background port forward before connecting or executing commands.

```bash
openshell sandbox create --forward <port>
```

--------------------------------

### Start llmster daemon

Source: https://github.com/nvidia/openshell/blob/main/docs/get-started/tutorials/local-inference-lmstudio.mdx

Start the llmster daemon in headless mode after installation.

```shell
lms daemon up
```

--------------------------------

### RFC Metadata Example

Source: https://github.com/nvidia/openshell/blob/main/rfc/README.md

Include this YAML front matter at the start of every RFC document to define authors, state, and related links.

```yaml
---
authors:
  - "@username"
state: draft
links:
  - https://github.com/NVIDIA/OpenShell/pull/123
  - https://github.com/NVIDIA/OpenShell/discussions/456
---
```

--------------------------------

### Get LM Studio Provider Configuration

Source: https://github.com/nvidia/openshell/blob/main/docs/get-started/tutorials/local-inference-lmstudio.mdx

View the configuration details for the LM Studio inference provider. Ensure this matches your LM Studio setup.

```shell
openshell provider get lmstudio
```

--------------------------------

### Build Rootfs: Base vs. Full

Source: https://github.com/nvidia/openshell/blob/main/crates/openshell-vm/README.md

Build the root filesystem for the VM. Use `-- --base` for a lightweight version or omit for a full, pre-initialized version.

```bash
# Base rootfs (~200-300MB, cold starts in ~30-60s)
mise run vm:rootfs -- --base
```

```bash
# Full rootfs (~2GB+, pre-initialized, boots in ~3-5s)
mise run vm:rootfs
```

--------------------------------

### Define Network Policy Rule

Source: https://github.com/nvidia/openshell/blob/main/architecture/security-policy.md

Example of a network policy rule named `claude_code`. It specifies allowed endpoints and binaries for outbound connections. The sandbox starts in proxy mode to evaluate all egress.

```yaml
network_policies:
  claude_code: # <-- map key (arbitrary identifier)
    name: claude_code # <-- human-readable name (used in audit logs)
    endpoints: # <-- allowed host:port pairs
      - { host: api.anthropic.com, port: 443 }
      - { host: "*.anthropic.com", ports: [443, 8443] } # glob host + multi-port
    binaries: # <-- allowed binary identities
      - { path: /usr/local/bin/claude }
```

--------------------------------

### Quick Build VM Runtime (macOS)

Source: https://github.com/nvidia/openshell/blob/main/crates/openshell-vm/runtime/README.md

This command initiates a quick build of the VM runtime on macOS using `mise`. Pre-built runtimes are recommended for faster setup.

```bash
mise run vm:setup
```

--------------------------------

### Create a Sandbox

Source: https://github.com/nvidia/openshell/blob/main/docs/get-started/tutorials/first-network-policy.mdx

Create a sandbox named 'demo' that remains running after exit and skips provider setup. This provides a clean environment to observe default-deny behavior.

```bash
openshell sandbox create --name demo --keep --no-auto-providers
```

--------------------------------

### Common Workflows: Starting Over

Source: https://github.com/nvidia/openshell/blob/main/crates/openshell-vm/README.md

Commands to completely reset the VM environment by cleaning artifacts, re-downloading the runtime, and performing a full rebuild and run.

```bash
# Something broken, start over
mise run vm:clean              # wipe everything
mise run vm:setup              # re-download runtime
mise run vm                    # full rebuild + run
```

--------------------------------

### Create OpenClaw Sandbox with Helper Script

Source: https://github.com/nvidia/openshell/blob/main/examples/openclaw.md

Use this command to quickly create and launch an OpenClaw sandbox. The `openclaw-start` script handles onboarding and gateway setup.

```sh
openshell sandbox create --forward 18789 --from openclaw -- openclaw-start
```

--------------------------------

### Run VM: Default Gateway Mode

Source: https://github.com/nvidia/openshell/blob/main/crates/openshell-vm/README.md

Boot the VM in the default gateway mode, which includes k3s, openshell-server, and openshell-sandbox.

```bash
mise run vm
```

```bash
./target/debug/openshell-vm
```

--------------------------------

### List Helm Install Job Logs

Source: https://github.com/nvidia/openshell/blob/main/crates/openshell-cli/src/doctor_llm_prompt.md

Examine the logs of the Helm install job to diagnose failures related to chart values or dependency issues during Helm installation.

```bash
openshell doctor exec -- kubectl -n kube-system logs -l job-name=helm-install-openshell
```

--------------------------------

### Serve Fern Docs Locally

Source: https://github.com/nvidia/openshell/blob/main/CONTRIBUTING.md

Build and serve the Fern documentation website locally for previewing changes.

```bash
mise run docs:serve
```

--------------------------------

### Install llmster on Windows

Source: https://github.com/nvidia/openshell/blob/main/docs/get-started/tutorials/local-inference-lmstudio.mdx

Use this command to install the llmster application on Windows systems.

```powershell
irm https://lmstudio.ai/install.ps1 | iex
```

--------------------------------

### Install llmster on Linux/Mac

Source: https://github.com/nvidia/openshell/blob/main/docs/get-started/tutorials/local-inference-lmstudio.mdx

Use this command to install the llmster application on Linux or macOS systems.

```shell
curl -fsSL https://lmstudio.ai/install.sh | bash
```

--------------------------------

### Create and Run a Sandbox

Source: https://github.com/nvidia/openshell/blob/main/examples/gateway-deploy-connect.md

Creates a new sandbox named 'hello' and executes a command within it. This is useful for testing isolated environments.

```bash
openshell sandbox create --name hello -- echo "it works"
```

--------------------------------

### Install Rustls Crypto Provider

Source: https://github.com/nvidia/openshell/blob/main/architecture/gateway.md

Installs the default Rustls crypto provider. This is a prerequisite for secure communication.

```rust
rustls::crypto::ring::default_provider().install_default()
```

--------------------------------

### Install Z3 on Fedora

Source: https://github.com/nvidia/openshell/blob/main/CONTRIBUTING.md

Installs the Z3 solver library using dnf. This is required for the openshell-prover crate.

```bash
# Fedora
sudo dnf install z3-devel
```

--------------------------------

### Build Full VM Runtime from Source (Linux)

Source: https://github.com/nvidia/openshell/blob/main/crates/openshell-vm/runtime/README.md

Use this command with `mise` to build the complete VM runtime from source on Linux. Set `FROM_SOURCE=1` to ensure a source build.

```bash
FROM_SOURCE=1 mise run vm:setup
```

--------------------------------

### OpenShell File System Layout Example

Source: https://github.com/nvidia/openshell/blob/main/architecture/gateway-single-node.md

Illustrates the directory structure for OpenShell artifacts, including gateway metadata and mTLS bundles.

```text
openshell/
  active_gateway                           # plain text: active gateway name
  gateways/
    {name}_metadata.json                   # GatewayMetadata JSON
    {name}/
      mtls/                                # mTLS bundle (when TLS enabled)
        ca.crt
        tls.crt
        tls.key
```

--------------------------------

### Install Z3 on macOS

Source: https://github.com/nvidia/openshell/blob/main/CONTRIBUTING.md

Installs the Z3 solver library using Homebrew. This is required for the openshell-prover crate.

```bash
# macOS
brew install z3
```

--------------------------------

### Install mise

Source: https://github.com/nvidia/openshell/blob/main/CONTRIBUTING.md

Installs the mise version manager using a curl script. This is a prerequisite for setting up the development environment.

```bash
curl https://mise.run | sh
```

--------------------------------

### Build Custom Rootfs and Binary

Source: https://github.com/nvidia/openshell/blob/main/architecture/custom-vm-runtime.md

Use these commands to build a full rootfs with pre-loaded container images or to rebuild the binary with the full rootfs for air-gapped environments.

```bash
mise run vm:rootfs                 # Full rootfs (~2GB, includes images)
mise run vm:build                  # Rebuild binary with full rootfs
```

--------------------------------

### Install Python Packages with uv

Source: https://github.com/nvidia/openshell/blob/main/AGENTS.md

Use `uv` for installing Python packages. This is the preferred method for managing Python dependencies.

```bash
uv pip install
```

--------------------------------

### Full Example Policy Configuration

Source: https://github.com/nvidia/openshell/blob/main/docs/reference/policy-schema.mdx

Combines network policies for GitHub REST API and npm registry access, specifying allowed binaries for each.

```yaml
network_policies:
  github_rest_api:
    name: github-rest-api
    endpoints:
      - host: api.github.com
        port: 443
        protocol: rest
        enforcement: enforce
        access: read-only
    binaries:
      - path: /usr/local/bin/claude
      - path: /usr/bin/node
      - path: /usr/bin/gh
  npm_registry:
    name: npm-registry
    endpoints:
      - host: registry.npmjs.org
        port: 443
    binaries:
      - path: /usr/bin/npm
      - path: /usr/bin/node
```

--------------------------------

### Create Provider from Existing Environment Variables

Source: https://github.com/nvidia/openshell/blob/main/docs/sandboxes/manage-providers.mdx

Use this command to create a provider by automatically discovering credentials from your shell environment variables. It's the quickest way to set up a provider.

```shell
openshell provider create --name my-claude --type claude --from-existing
```

--------------------------------

### Verify GitHub API Access (GET)

Source: https://github.com/nvidia/openshell/blob/main/examples/sandbox-policy-quickstart/README.md

Connects to the 'demo' sandbox and verifies that GET requests to the GitHub API are now allowed.

```bash
openshell sandbox connect demo
```

```bash
curl -s https://api.github.com/zen
```

--------------------------------

### Process Management and Environment Setup

Source: https://github.com/nvidia/openshell/blob/main/architecture/sandbox.md

Details the environment variables and pre-execution configurations applied when spawning new processes within the OpenShell sandbox.

```APIDOC
## Process Management

### Description
Manages the spawning of child processes, including setting up their execution environment and applying security configurations before the main program executes.

### File
`crates/openshell-sandbox/src/process.rs`

### `ProcessHandle`

#### Description
Wraps a `tokio::process::Child` and its associated Process ID (PID). Platform-specific `spawn()` methods delegate to a common `spawn_impl()` function.

### Environment Setup

#### Common Variables (Linux & Non-Linux)
- `OPENSHELL_SANDBOX=1`: Always set to indicate the process is running within the OpenShell sandbox.
- Provider credentials: Set via the `GetSandboxProviderEnvironment` RPC.

#### Proxy Variables
- **Uppercase**: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` (for tools like curl/wget).
- **Lowercase**: `http_proxy`, `https_proxy`, `grpc_proxy` (for gRPC C-core).
- **Bypass**: `NO_PROXY=127.0.0.1,localhost,::1` and `no_proxy=127.0.0.1,localhost,::1` for localhost bypass.
- **Node.js**: `NODE_USE_ENV_PROXY=1` (required for Node.js built-in clients).

#### TLS Trust Store
- `NODE_EXTRA_CA_CERTS`: Path to a standalone CA certificate.
- `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`: Paths to combined CA bundles.

### Pre-exec Closure (Runs in Child after fork, before exec - Async-Signal-Safe)

1. **`setpgid(0, 0)`**: Creates a new process group if the process is non-interactive.
2. **`setns(fd, CLONE_NEWNET)`**: Enters the network namespace (Linux only).
3. **`drop_privileges(policy)`**: Resets group and user IDs using `initgroups()`, `setgid()`, and `setuid()` based on the provided policy.
4. **Disable Core Dumps**: Sets `RLIMIT_CORE` to 0 on Unix-like systems.
5. **`prctl(PR_SET_DUMPABLE, 0)`**: Prevents core dumps on Linux.
6. **`sandbox::apply(policy, workdir)`**: Applies security policies using Landlock and Seccomp.
```

--------------------------------

### Install Bypass Rules

Source: https://github.com/nvidia/openshell/blob/main/architecture/sandbox.md

Installs iptables OUTPUT chain rules for bypass detection, enabling fast-fail UX and diagnostic logging. This is non-fatal if it fails.

```rust
install_bypass_rules(proxy_port)
```

--------------------------------

### Check Helm Install Job Logs

Source: https://github.com/nvidia/openshell/blob/main/crates/openshell-cli/src/doctor_llm_prompt.md

View logs from the Helm installation job for OpenShell. This is useful for diagnosing issues during the initial chart deployment.

```bash
openshell doctor exec -- kubectl -n kube-system logs -l job-name=helm-install-openshell --tail=200
```

--------------------------------

### Register and Create Sandbox with OpenShell CLI

Source: https://github.com/nvidia/openshell/blob/main/crates/openshell-driver-vm/README.md

Use these commands to register the gateway and create a new sandbox. The first sandbox creation may take longer due to rootfs extraction and initialization.

```shell
export OPENSHELL_GATEWAY_URL=http://127.0.0.1:8080
cargo run -p openshell-cli -- gateway register local --url $OPENSHELL_GATEWAY_URL --no-tls
cargo run -p openshell-cli -- sandbox create --name demo
cargo run -p openshell-cli -- sandbox connect demo
```

--------------------------------

### Install Ollama on Gateway Host

Source: https://github.com/nvidia/openshell/blob/main/docs/get-started/tutorials/inference-ollama.mdx

Install Ollama on the gateway host using the provided curl script. This is the first step for using host-level Ollama.

```shell
curl -fsSL https://ollama.com/install.sh | sh
```

--------------------------------

### Install Git Hook for Pre-commit

Source: https://github.com/nvidia/openshell/blob/main/AGENTS.md

Install the git hook locally to automatically run pre-commit checks. This ensures code quality and consistency before each commit.

```bash
mise generate git-pre-commit --write --task=pre-commit
```

--------------------------------

### OpenShell VM Build Commands

Source: https://github.com/nvidia/openshell/blob/main/architecture/custom-vm-runtime.md

Commands for setting up, building, and cleaning the OpenShell VM. Includes options for base or full rootfs, and building with a custom kernel.

```bash
# One-time setup: download pre-built runtime (~30s)
mise run vm:setup

# Build and run
mise run vm

# Build embedded binary with base rootfs (~120MB, recommended)
mise run vm:rootfs -- --base              # Build base rootfs tarball
mise run vm:build                          # Build binary with embedded rootfs

# Build with full rootfs (air-gapped, ~2GB+)
mise run vm:rootfs                         # Build full rootfs tarball
mise run vm:build                          # Rebuild binary

# With custom kernel (optional, adds ~20 min)
FROM_SOURCE=1 mise run vm:setup            # Build runtime from source
mise run vm:build                          # Then build embedded binary

# Wipe everything and start over
mise run vm:clean
```

--------------------------------

### Python E2E Test Example

Source: https://github.com/nvidia/openshell/blob/main/TESTING.md

An example of a Python end-to-end test using the `sandbox` fixture to execute a command within a sandbox and assert its output.

```python
def test_exec_returns_stdout(sandbox):
    with sandbox(delete_on_exit=True) as sb:
        result = sb.exec(["echo", "hello"])
        assert result.exit_code == 0
        assert "hello" in result.stdout

```

--------------------------------

### Run Inference Example in Sandbox (Cluster Mode)

Source: https://github.com/nvidia/openshell/blob/main/examples/local-inference/README.md

Creates a sandbox and runs the inference script, which targets inference.local. OpenShell intercepts this connection and routes it to the cluster-configured backend.

```bash
openshell sandbox create \
  --policy examples/inference/sandbox-policy.yaml \
  --name inference-demo \
  -- python examples/inference/inference.py
```

--------------------------------

### CLI Reference: Options and Subcommands

Source: https://github.com/nvidia/openshell/blob/main/crates/openshell-vm/README.md

Reference for the openshell-vm command-line interface, detailing available options and subcommands for managing VM instances.

```bash
openshell-vm [OPTIONS] [COMMAND]

Options:
  --rootfs <PATH>          Path to aarch64 Linux rootfs directory
  --name <NAME>            Named VM instance (auto-clones rootfs)
  --exec <PATH>            Run a custom process instead of k3s
  --args <ARGS>...         Arguments to the executable
  --env <KEY=VALUE>...     Environment variables
  --workdir <DIR>          Working directory inside the VM [default: /]
  -p, --port <H:G>...     Port mappings (host_port:guest_port)
  --vcpus <N>              Virtual CPUs [default: 4 gateway, 2 exec]
  --mem <MiB>              RAM in MiB [default: 8192 gateway, 2048 exec]
  --krun-log-level <0-5>   libkrun log level [default: 1]
  --net <BACKEND>          Networking: gvproxy, tsi, none [default: gvproxy]
  --reset                  Wipe runtime state before booting

Subcommands:
  prepare-rootfs           Ensure the target rootfs exists
  exec                     Execute a command inside a running VM
```

--------------------------------

### Inference Example Output (Cluster Mode)

Source: https://github.com/nvidia/openshell/blob/main/examples/local-inference/README.md

Expected output when running the inference example in cluster mode. It shows the backend model name and a success status.

```text
model=<backend model name>
content=NAV_OK
```

--------------------------------

### Create Sandbox from Community Catalog

Source: https://github.com/nvidia/openshell/blob/main/docs/get-started/quickstart.mdx

Creates a sandbox by pulling a specified image from the NVIDIA Container Registry using the --from flag. Example uses the 'base' image.

```shell
openshell sandbox create --from base
```

--------------------------------

### Destroy and Start OpenShell Gateway

Source: https://github.com/nvidia/openshell/blob/main/crates/openshell-cli/src/doctor_llm_prompt.md

Recreate the OpenShell gateway by first destroying the existing one and then starting it again, which can resolve issues with stale NotReady nodes after volume reuse.

```bash
openshell gateway destroy <name> && openshell gateway start
```

--------------------------------

### Create Sandbox from Community Image

Source: https://github.com/nvidia/openshell/blob/main/architecture/sandbox-custom-containers.md

Use this command to launch a sandbox using a pre-defined community sandbox image.

```bash
openshell sandbox create --from openclaw
```

--------------------------------

### Start Remote Gateway and Check Status

Source: https://github.com/nvidia/openshell/blob/main/docs/get-started/quickstart.mdx

Starts an OpenShell gateway on a remote machine via SSH and then checks its status. Ensure SSH access is configured before running.

```shell
openshell gateway start --remote <username>@<spark-ssid>.local
openshell status
```

--------------------------------

### L7 Deny Log Entry Example

Source: https://github.com/nvidia/openshell/blob/main/examples/sandbox-policy-quickstart/README.md

An example log entry showing an L7 decision to deny a POST request to the GitHub API due to policy restrictions.

```text
l7_decision=deny dst_host=api.github.com l7_action=POST l7_target=/repos/octocat/hello-world/issues l7_deny_reason="POST /repos/octocat/hello-world/issues not permitted by policy"
```

--------------------------------

### Build and Push Docker Image

Source: https://github.com/nvidia/openshell/blob/main/examples/private-ip-routing/README.md

Builds a Docker image for the demo application and pushes it to the local cluster registry. Ensure Docker is running and accessible.

```bash
docker build -t 127.0.0.1:5000/demo/private-api:latest examples/private-ip-routing/
```

```bash
docker push 127.0.0.1:5000/demo/private-api:latest
```

--------------------------------

### Common Workflows: Day-to-Day Iteration

Source: https://github.com/nvidia/openshell/blob/main/crates/openshell-vm/README.md

Commands for daily development, focusing on incremental builds and running the VM.

```bash
# Day-to-day iteration
mise run vm                    # incremental build + run
```