Adam Miller
436c59a2a1
* fix(rpm): restore 0.0.0.0 bind address for Podman via default gateway.toml The gateway binary default changed to 127.0.0.1 in recent commits (b61a98db,f257ed01). This breaks the Podman compute driver because sandbox containers reach the gateway over the host network bridge and cannot connect to the loopback address. Ship a default TOML config template that the RPM systemd unit seeds into ~/.config/openshell/gateway.toml on first start. The template sets bind_address = "0.0.0.0:17670" and pins compute_drivers = ["podman"] to prevent unexpected driver selection when Docker is also installed. The binary default remains 127.0.0.1 (secure-by-default for non-RPM installs). Changes: - deploy/rpm/gateway.toml.default: new default config template - openshell.spec: install template to %{_datadir}/openshell-gateway/; add ExecStartPre to seed ~/.config/openshell/gateway.toml on first start; add %check assertions for template presence and unit reference - deploy/rpm/CONFIGURATION.md: document default config, override paths, and updated bind address throughout - deploy/rpm/QUICKSTART.md: update bind address note for RPM installs - crates/openshell-server/src/config_file.rs: contract test that parses the RPM template through load() and asserts bind_address=0.0.0.0 and compute_drivers=[podman] - e2e/with-podman-gateway.sh: start from RPM template as base config so e2e exercises the same TOML path RPM users get on first start * fix(rpm): restore openshell_python_version macro in dist-info metadata * fix(rpm): reset Packit-managed version fields to match main baseline Version, Source0, and Source1 were stamped to 0.0.43 by Packit CI during branch builds. Reset to 0.0.37 (current main baseline) so the spec diff only contains our intentional changes. Packit's fix-spec-file action will re-stamp these fields at build time. * Revert "fix(rpm): reset Packit-managed version fields to match main baseline" This reverts commit8ef9d7ad8e. * fix(rpm): introduce openshell_version macro; remove hardcoded versions Add %global openshell_version as the single source of truth for the package version. Version:, Source0:, Source1:, openshell_cargo_version, and openshell_python_version all expand from this one macro. Update .packit.yaml fix-spec-file to patch %global openshell_version instead of the Version:, Source0:, and Source1: lines individually.
3.8 KiB
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 RPM default configuration binds to
0.0.0.0:17670so Podman sandbox containers can reach the gateway over the host network bridge. Mutual TLS (mTLS) is enabled automatically on first start, requiring a valid client certificate for every connection. 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 inference routing (optional)
To route inference requests through a specific provider and model:
openshell inference set --provider openai --model gpt-4
openshell inference get
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 openshellfor the CLI reference. - Run
man openshell-gatewayfor the gateway daemon reference.