OpenShell/deploy/rpm/QUICKSTART.md

OpenShell RPM Quick Start

Get from dnf install to a running sandbox in five minutes.

Prerequisites

Podman (rootless)

The gateway uses rootless Podman for sandbox containers. Verify Podman is installed and the cgroup version is v2:

podman --version
podman info --format '{{.Host.CgroupsVersion}}'

The cgroup version must be v2. If it reports v1, enable the unified cgroup hierarchy and reboot:

sudo grubby --update-kernel=ALL --args="systemd.unified_cgroup_hierarchy=1"
sudo reboot

Subordinate UID/GID ranges

Rootless containers require subordinate UID/GID mappings:

grep $USER /etc/subuid /etc/subgid

If empty, add entries:

sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER

Podman socket

The gateway communicates with Podman over its API socket. Enable socket activation:

systemctl --user enable --now podman.socket

Network access

The gateway pulls container images from ghcr.io on first sandbox creation. Ensure the host can reach ghcr.io over HTTPS (port 443).

For air-gapped environments, pre-load images with podman pull and set image_pull_policy = "never" in ~/.config/openshell/gateway.toml. See CONFIGURATION.md for details.

Start the gateway

systemctl --user enable --now openshell-gateway

On first start, the gateway automatically generates:

• A self-signed PKI bundle (CA, server cert, client cert) for mTLS

Note: The primary gateway listener uses the loopback default, 127.0.0.1:17670. Host-networked Podman supervisors use this same listener. mTLS user authentication is enabled automatically on first start. Supervisor connections use the gateway CA and sandbox-scoped bearer tokens. See CONFIGURATION.md for details.

Verify the service is running:

systemctl --user status openshell-gateway

Register the gateway with the CLI

The CLI needs to know where the gateway is. Register it:

openshell gateway add --local https://127.0.0.1:17670

This discovers the pre-provisioned mTLS certificates at ~/.config/openshell/gateways/openshell/mtls/ and sets the gateway as active.

Verify the connection:

openshell status

Persist across reboots

By default, user services stop when you log out. To keep the gateway running after logout and across reboots:

sudo loginctl enable-linger $USER

Without this, the gateway and all running sandboxes are killed when your login session ends. This is required for any headless or production use.

Create your first sandbox

Set your API key in the environment, then create a sandbox:

export ANTHROPIC_API_KEY=sk-...
openshell sandbox create -- claude

The CLI detects the agent, prompts to create a credential provider from your local environment, pulls the sandbox image from ghcr.io, and connects you to the running sandbox.

Other agents:

openshell sandbox create -- opencode
openshell sandbox create -- codex

Set up providers manually

If you prefer to configure providers before creating sandboxes:

# Create a provider from a local environment variable
openshell provider create --name anthropic --type anthropic --from-existing

# Or supply the credential directly
openshell provider create --name openai --type openai \
  --credential OPENAI_API_KEY=sk-...

# List configured providers
openshell provider list

Configure provider-backed inference (optional)

To grant a sandbox access to a model provider:

openshell sandbox provider attach <sandbox> openai

# Configure the workload to call the provider's native endpoint and select
# the model in the client.

Next steps

• See CONFIGURATION.md for TLS settings, environment variables, and file locations.
• See TROUBLESHOOTING.md for CLI compatibility notes, remote access, and common issues.
• Run man openshell for the CLI reference.
• Run man openshell-gateway for the gateway daemon reference.