Files
openshell_controller/README.md
T
2026-04-25 03:06:19 +00:00

6.7 KiB

OpenShell Control

OpenShell Control is a local, development-stage dashboard for operating OpenShell sandboxes and their OpenClaw gateway dashboards.

It is currently built for active development and lab use. It includes a simple password gate, but it is not a hardened production control plane yet.

Current Status

  • Development software. Expect fast-moving APIs and sharp edges.
  • Designed to run near the OpenShell gateway host.
  • Uses local shell/CLI access for sandbox lifecycle, network policy grants, file transfer, and OpenClaw dashboard proxying.
  • Authentication is intentionally simple so a future dev team can replace it with a real identity provider.

Features

  • View live OpenShell sandbox inventory.
  • Create, destroy, and restart sandboxes.
  • Launch a sandbox-specific OpenClaw Gateway Dashboard through the local proxy.
  • Approve or reject pending OpenShell network permission requests.
  • Configure per-sandbox inference routes for Ollama, NIM, vLLM, and external endpoints.
  • Poll Ollama for available models.
  • Upload files into sandboxes and download files back out.
  • Open an operator terminal for the selected sandbox.
  • Simple local login, setup account, forgot password, and recovery token flow.

Version Requirements

Tested on the current development host with:

  • Ubuntu/Linux host
  • Node.js v22.22.2
  • npm 10.9.7
  • Docker 29.1.3
  • OpenShell CLI 0.0.24
  • OpenShell cluster image ghcr.io/nvidia/openshell/cluster:0.0.24

Minimum expected versions:

  • Node.js 20+
  • npm 10+
  • Docker 24+
  • OpenShell CLI and gateway compatible with OpenShell 0.0.24

The app uses Next.js 14.2.15, React 18.3.1, TypeScript, Tailwind CSS, ws, and node-pty.

Prerequisites

Install and verify:

node -v
npm -v
docker ps
openshell --version

OpenShell must already be installed and able to reach its gateway. On this host the active gateway metadata lives under:

~/.config/openshell/gateways/

The installer does not create an OpenShell gateway for you. Start or connect OpenShell first, then install this dashboard.

Installer

From the repository root:

./install.sh

The installer:

  • checks Node, npm, Docker, OpenShell CLI availability, sandbox inventory reachability, and default port occupancy;
  • installs npm dependencies with npm ci when package-lock.json exists;
  • runs a non-blocking npm audit summary;
  • creates .env.local if needed;
  • generates a local dashboard password, signing secret, and recovery token if they are missing;
  • runs npm run build as a verification step.

It refuses to run as root unless --allow-root is supplied. It does not install or manage a systemd service.

Options:

./install.sh --no-build
./install.sh --no-audit
./install.sh --clean-next
./install.sh --allow-root
./install.sh --start
./install.sh --help

After install, read the generated local password from:

grep OPENSHELL_CONTROL_PASSWORD .env.local

Run

npm run dev

Open:

http://localhost:3000

Default ports:

  • 3000: dashboard HTTP server
  • 3001: OpenClaw dashboard websocket sidecar
  • 3011: operator terminal upstream

Authentication

This project currently uses a simple local password and signed HTTP-only cookie.

Configuration keys:

OPENSHELL_CONTROL_PASSWORD=...
OPENSHELL_CONTROL_AUTH_SECRET=...
OPENSHELL_CONTROL_RECOVERY_TOKEN=...

Pages:

  • /login
  • /setup-account
  • /forgot-password

There is no email sender. Forgot-password uses OPENSHELL_CONTROL_RECOVERY_TOKEN from .env.local, which means it is a host-admin recovery flow. Anyone who can read .env.local can reset the dashboard password.

After changing .env.local, restart the server:

pkill -f 'node server.mjs|npm run dev' || true
npm run dev

OpenShell And OpenClaw Notes

The dashboard shells out to the OpenShell CLI for several operations:

  • openshell list
  • openshell sandbox exec
  • openshell sandbox delete
  • openshell rule get
  • openshell rule approve
  • openshell rule reject

OpenClaw dashboard access is loopback-only inside the host/sandbox context, so the UI uses local proxy routes:

  • /api/openshell/dashboard/proxy
  • /api/openshell/instances/[instanceId]/dashboard/proxy

The custom server in server.mjs also handles websocket upgrades for:

  • operator terminal websocket traffic;
  • OpenClaw dashboard websocket traffic.

Those upgrade paths are protected by the same auth cookie as the HTTP routes.

Inference Endpoints

Inference endpoint configuration is development-stage.

The UI supports per-sandbox route profiles and can apply them live to OpenClaw where possible. Depending on the sandbox and provider, changes may require a sandbox restart to fully take effect inside the container.

Supported provider categories in the UI:

  • Ollama
  • NVIDIA NIM
  • vLLM
  • external HTTP-compatible endpoints

File Transfer

The file transfer UI is scoped to safe sandbox paths:

  • /sandbox
  • /tmp

The default max transfer size is 128 MiB. Override with:

SANDBOX_FILE_TRANSFER_MAX_BYTES=134217728

Development Commands

npm run dev
npm run lint
npx tsc --noEmit
npm run build

After running npm run build during development, restart cleanly:

pkill -f 'node server.mjs|npm run dev' || true
rm -rf .next
npm run dev

Configuration

Copy or edit .env.local:

cp .env.example .env.local

Common keys:

NEXT_PUBLIC_DASHBOARD_PORT=3000
NEXT_PUBLIC_API_BASE=/api
NEXT_PUBLIC_ENABLE_SANDBOX_OPERATIONS=true
OPEN_SHELL_CONTAINER=openshell-cluster-nemoclaw
OPENSHELL_GATEWAY=nemoclaw
OPENSHELL_CONTROL_PASSWORD=change-this-password
OPENSHELL_CONTROL_AUTH_SECRET=change-this-random-secret
OPENSHELL_CONTROL_RECOVERY_TOKEN=change-this-recovery-token

Security Limitations

This is not production hardened.

Known limitations:

  • single shared local password;
  • no user accounts or roles;
  • no email reset flow;
  • no rate limiting;
  • no audit log persistence beyond process/container logs;
  • local recovery token can reset the password;
  • assumes a trusted operator host and trusted local filesystem.

Before exposing this outside a trusted lab network, replace auth with a real identity provider, add role-based access control, add audit logging, use TLS, and review every shell-out path.

Troubleshooting

Check OpenShell:

openshell --version
openshell list
docker ps | grep openshell

Check auth:

grep OPENSHELL_CONTROL_PASSWORD .env.local
grep OPENSHELL_CONTROL_RECOVERY_TOKEN .env.local

Check dashboard:

npm run lint
npx tsc --noEmit
npm run build

If the UI behaves oddly after a production build:

pkill -f 'node server.mjs|npm run dev' || true
rm -rf .next
npm run dev

License

Internal development prototype. Add the appropriate license before distribution.