Run NVIDIA OpenShell on a remote VM

Start an agent#

On the VM (ssh my-openshell.exe.xyz):

openshell sandbox create --name claude --from agents:local --provider exe-llm -- claude

Detach with Ctrl-P Ctrl-Q; Claude keeps running. Reattach with openshell sandbox connect claude. Use -- codex for Codex, or no command for a shell. Your work is in /sandbox.

Other commands: openshell sandbox list, openshell sandbox delete <name>, and openshell term (a dashboard).

Approve network access#

A new sandbox reaches the models and nothing else. When something is blocked, say a git clone, OpenShell drafts a rule:

openshell rule get claude --status pending
openshell rule approve claude --chunk-id <chunk-id>

The retry works without a restart. Rules apply to one program: allowing github.com for git doesn't allow it for curl. openshell rule approve-all claude approves everything pending, and openshell logs claude shows each connection. See OpenShell's policy docs.

Set it up#

ssh exe.dev new --name=my-openshell
ssh my-openshell.exe.xyz

sudo systemctl enable --now docker.service
sudo curl -fsSL -o /etc/nginx/conf.d/exe-llm-relay.conf \
  https://exe-staging.dev/deploy/openshell/exe-llm-relay.conf
sudo systemctl enable nginx && sudo systemctl restart nginx
curl -s localhost:11435/v1/models | head -c 80; echo

curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh \
  | OPENSHELL_INSTALL_METHOD=deb sh
openshell status

mkdir -p ~/openshell && cd ~/openshell
for f in exe-llm.yaml Dockerfile; do
  curl -fsSLO https://exe-staging.dev/deploy/openshell/$f
done
openshell profile import --file exe-llm.yaml
openshell provider create --name exe-llm --type exe-llm
docker build -t agents:local .

openshell sandbox create --name check --no-keep --from agents:local --provider exe-llm \
  -- claude -p "Reply with exactly: claude ok"

How it works#

• The gateway (openshell-gateway, a systemd user service) stores sandboxes, policies, and providers in ~/.local/state/openshell.
• A supervisor beside each sandbox routes all of its traffic and checks every connection against the policy.
• The sandbox is a Docker container with no network interface, plus Landlock and seccomp.

Sandboxes can't reach llm.int.exe.xyz directly, because OpenShell blocks link-local addresses. A keyless nginx relay (exe-llm-relay.conf) listens on the VM's loopback, and exe-llm.yaml lets the agents reach it at host.openshell.internal:11435. The Dockerfile installs Claude Code and Codex and points both at the relay.

Open a web app in a sandbox#

Expose a port, here 3000 in the sandbox claude:

openshell service expose claude 3000

That URL works only on the VM. To serve it at https://my-openshell.exe.xyz:8080/, private to you through the HTTPS proxy:

sudo tee /etc/nginx/conf.d/openshell-web.conf > /dev/null <<'EOF'
server {
    listen 8080;
    location / {
        proxy_pass http://127.0.0.1:17670;
        proxy_set_header Host default--claude.openshell.localhost:17670;
        proxy_set_header Origin "";
        proxy_set_header Referer "";
        proxy_set_header Sec-Fetch-Site "";
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $http_connection;
    }
}
EOF
sudo nginx -t && sudo systemctl reload nginx

Clearing the origin headers is needed because OpenShell rejects cross-origin requests.

Run sandboxes as microVMs#

sudo usermod -aG kvm exedev
mkdir -p ~/.config/openshell
cat > ~/.config/openshell/gateway.toml <<'EOF'
[openshell]
version = 2

[openshell.gateway]
compute_driver = "vm"
EOF
openshell-gateway config preflight --path ~/.config/openshell/gateway.toml
sudo systemctl restart user@$(id -u).service

Back up and update#

openshell sandbox download claude /sandbox ~/backup/claude

curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh \
  | OPENSHELL_INSTALL_METHOD=deb sh

systemctl --user disable --now openshell-gateway
sudo apt remove openshell
rm -rf ~/.local/state/openshell

Troubleshooting#

• openshell status can't connect: journalctl --user -u openshell-gateway -n 50.
• Agent can't reach its API: run curl -s localhost:11435/v1/models to check the relay. Check openshell policy get <name> --full for _provider_exe_llm; if it's missing, openshell sandbox provider attach <name> exe-llm. If openshell logs <name> shows DENIED <program>, add that program to binaries in exe-llm.yaml.
• Installs fail inside a sandbox: that's the policy. Approve the pending rule (above).