Scroll to navigation

OPENSHELL(1) OpenShell Manual OPENSHELL(1)

NAME

openshell - CLI for managing OpenShell sandboxes, gateway registrations, and providers

SYNOPSIS

openshell [OPTIONS] COMMAND [ARGS]

DESCRIPTION

openshell is the command-line interface for OpenShell, a platform providing safe, sandboxed runtimes for autonomous AI agents. It manages gateway registrations, sandbox lifecycle, credential providers, network policies, and provider attachments.

The CLI communicates with a gateway server over gRPC. The gateway can run as a package-managed systemd user service, a Helm deployment, a development task, or behind a cloud reverse proxy.

COMMANDS

Gateway Management

Register an existing gateway with the CLI.
Remove a local CLI registration and stored auth tokens. This does not stop or destroy the gateway service.
List registered gateways or switch the active gateway.
Show registration details for a gateway.
List registered gateways.
Re-authenticate with a cloud gateway.
Clear stored authentication credentials for a gateway.
Check the health of the active gateway.

Sandbox Management

Create a new sandbox on the active gateway.
List all sandboxes on the active gateway.
Show details for a sandbox.
Delete one or all sandboxes.
SSH into a running sandbox.
Execute a command in a sandbox.
Upload files to a sandbox.
Download files from a sandbox.

Policy Management

Show the active policy for a sandbox.
Apply a policy to a sandbox.
Incrementally update a sandbox policy.
Show policy revision history.
Verify policy properties.

Provider Management

Create a credential provider.
List all providers.
Show provider details.
Update provider credentials.
Delete a provider.
Attach a provider to a running sandbox. New processes receive its endpoint-bound credential placeholders and provider-derived policy.
Revoke a provider attachment from a running sandbox.

Other

View sandbox logs.
Start port forwarding to a sandbox.
Stop port forwarding.
List active port forwards.
Open the real-time TUI dashboard.
Validate local Docker prerequisites for standalone gateway development. For package-managed gateways, prefer systemd, journalctl, kubectl, or Helm diagnostics.
Generate shell completions (bash, zsh, fish).

GLOBAL OPTIONS

Target a specific gateway by name.
–gateway-endpoint URL
Connect to a gateway by URL directly.
Print help information.
Print version.

ENVIRONMENT

Default gateway name (overrides active gateway).
Direct gateway URL (bypasses metadata lookup).
API keys discovered by auto-provider creation.
GitHub credentials for provider auto-discovery.

FILES

~/.config/openshell/gateways/
Gateway metadata and mTLS certificates.
~/.config/openshell/active_gateway
Name of the currently active gateway.

EXAMPLES

Register the local RPM gateway and create a sandbox:

openshell gateway add --local https://127.0.0.1:17670
openshell sandbox create -- claude
    

List sandboxes and connect to one:

openshell sandbox list
openshell sandbox connect my-sandbox
    

Create a provider from a local environment variable:

openshell provider create --name openai --type openai --from-existing
    

Check gateway health:

openshell status
    

SEE ALSO

openshell-gateway(8)

Full documentation: https://docs.nvidia.com/openshell/

Run openshell COMMAND –help for detailed help on any command.

2026 openshell