mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-19 05:50:41 +08:00
Drew Newberry
f257ed0193
* fix(packaging): use gateway TOML config in packages * refactor(packaging): rely on gateway runtime defaults
192 lines
6.1 KiB
Markdown
192 lines
6.1 KiB
Markdown
---
|
|
title: OPENSHELL-GATEWAY
|
|
section: 8
|
|
header: OpenShell Manual
|
|
footer: openshell-gateway
|
|
date: 2025
|
|
---
|
|
|
|
# NAME
|
|
|
|
openshell-gateway - OpenShell gateway server daemon
|
|
|
|
# SYNOPSIS
|
|
|
|
**openshell-gateway** \[*OPTIONS*\]
|
|
|
|
# DESCRIPTION
|
|
|
|
**openshell-gateway** is the control-plane server for OpenShell. It
|
|
manages sandbox lifecycle, stores provider credentials, delivers
|
|
network and filesystem policies to sandboxes, routes inference
|
|
requests, and provides the SSH tunnel endpoint for CLI-to-sandbox
|
|
connections.
|
|
|
|
When installed via a Linux package, the gateway runs as a systemd user
|
|
service. The packaged service starts from built-in defaults and reads
|
|
the default gateway TOML path only when that file exists.
|
|
|
|
The gateway exposes a single port with multiplexed gRPC and HTTP,
|
|
secured by mutual TLS (mTLS) by default unless the TOML config disables
|
|
TLS.
|
|
|
|
# OPTIONS
|
|
|
|
**--bind-address** *IP*
|
|
: IP address to bind all listeners to. Default: **127.0.0.1**.
|
|
Environment: **OPENSHELL_BIND_ADDRESS**.
|
|
|
|
**--port** *PORT*
|
|
: Port for the gRPC/HTTP API. Default: **17670**.
|
|
Environment: **OPENSHELL_SERVER_PORT**.
|
|
|
|
**--health-port** *PORT*
|
|
: Port for unauthenticated health endpoints (/healthz, /readyz).
|
|
Set to 0 to disable. Default: **0**.
|
|
Environment: **OPENSHELL_HEALTH_PORT**.
|
|
|
|
**--metrics-port** *PORT*
|
|
: Port for Prometheus metrics (/metrics). Set to 0 to disable.
|
|
Default: **0**. Environment: **OPENSHELL_METRICS_PORT**.
|
|
|
|
**--log-level** *LEVEL*
|
|
: Log level: trace, debug, info, warn, error. Default: **info**.
|
|
Environment: **OPENSHELL_LOG_LEVEL**.
|
|
|
|
**--db-url** *URL*
|
|
: SQLite database URL for state persistence. When unset, the gateway
|
|
stores SQLite state under *~/.local/state/openshell/gateway/*.
|
|
Environment: **OPENSHELL_DB_URL**.
|
|
|
|
**--drivers** *DRIVER*\[,*DRIVER*\]
|
|
: Compute driver. Accepts a comma-delimited list. The gateway
|
|
currently requires exactly one driver. Options: **podman**,
|
|
**docker**, **kubernetes**, **vm**. When unset, the gateway
|
|
auto-detects Kubernetes, then Podman, then Docker. VM is opt-in.
|
|
Environment: **OPENSHELL_DRIVERS**.
|
|
|
|
**--tls-cert** *PATH*
|
|
: Path to server TLS certificate file. Defaults to the local generated
|
|
TLS bundle when present. Required unless **--disable-tls** is set.
|
|
Environment: **OPENSHELL_TLS_CERT**.
|
|
|
|
**--tls-key** *PATH*
|
|
: Path to server TLS private key file. Defaults to the local generated
|
|
TLS bundle when present. Required unless **--disable-tls** is set.
|
|
Environment: **OPENSHELL_TLS_KEY**.
|
|
|
|
**--tls-client-ca** *PATH*
|
|
: Path to CA certificate for client certificate verification (mTLS).
|
|
When set without **--oidc-issuer**, client certificates are required
|
|
and the TLS handshake rejects unauthenticated connections. When set
|
|
together with **--oidc-issuer**, client certificates are accepted
|
|
but not required — callers may authenticate with either a Bearer
|
|
token or a client certificate.
|
|
Environment: **OPENSHELL_TLS_CLIENT_CA**.
|
|
|
|
**--disable-tls**
|
|
: Disable TLS entirely and listen on plaintext HTTP. When the bind
|
|
address is **0.0.0.0** (the RPM default), disabling TLS exposes the
|
|
API to the entire network without authentication. Only use when the
|
|
gateway sits behind a TLS-terminating reverse proxy, or restrict
|
|
**--bind-address** to **127.0.0.1**.
|
|
Environment: **OPENSHELL_DISABLE_TLS**.
|
|
|
|
**--server-san** *SAN*
|
|
: Subject Alternative Name configured on the gateway server
|
|
certificate. Repeat or pass a comma-separated value through
|
|
**OPENSHELL_SERVER_SAN**. Wildcard DNS SANs also enable sandbox
|
|
service URLs under that domain.
|
|
Environment: **OPENSHELL_SERVER_SAN**.
|
|
|
|
Compute driver settings such as sandbox image, callback endpoint, image
|
|
pull policy, network name, VM state directory, and guest TLS material are
|
|
configured in the TOML file passed with **--config**.
|
|
|
|
# SYSTEMD INTEGRATION
|
|
|
|
The package installs a systemd user unit at
|
|
*/usr/lib/systemd/user/openshell-gateway.service*. Manage the gateway
|
|
with standard systemd commands:
|
|
|
|
systemctl --user enable --now openshell-gateway
|
|
systemctl --user status openshell-gateway
|
|
systemctl --user restart openshell-gateway
|
|
systemctl --user stop openshell-gateway
|
|
|
|
View logs:
|
|
|
|
journalctl --user -u openshell-gateway
|
|
journalctl --user -u openshell-gateway -f
|
|
|
|
The unit runs **openshell-gateway generate-certs** as an **ExecStartPre**
|
|
step on first start. This generates a self-signed PKI bundle for mTLS
|
|
and skips generation when the bundle already exists.
|
|
|
|
The gateway then starts from built-in defaults and reads
|
|
*~/.config/openshell/gateway.toml* when that file exists.
|
|
|
|
To persist the service across logouts:
|
|
|
|
sudo loginctl enable-linger $USER
|
|
|
|
# CONFIGURATION
|
|
|
|
The systemd user unit launches the gateway with:
|
|
|
|
openshell-gateway
|
|
|
|
Gateway listener, TLS, database, and compute driver settings have local
|
|
defaults. Create *~/.config/openshell/gateway.toml* when you need to
|
|
override them. The gateway rejects `database_url` in TOML; set
|
|
**OPENSHELL_DB_URL** when you need a different database.
|
|
|
|
To override individual settings without creating TOML:
|
|
|
|
systemctl --user edit openshell-gateway
|
|
|
|
This creates a drop-in override that persists across package upgrades.
|
|
|
|
# FILES
|
|
|
|
*/usr/bin/openshell-gateway*
|
|
: Gateway binary.
|
|
|
|
*/usr/lib/systemd/user/openshell-gateway.service*
|
|
: Systemd user unit file.
|
|
|
|
*~/.config/openshell/gateway.toml*
|
|
: Optional gateway TOML configuration.
|
|
|
|
*~/.local/state/openshell/tls/*
|
|
: Auto-generated TLS certificates.
|
|
|
|
*~/.local/state/openshell/gateway/openshell.db*
|
|
: SQLite database for gateway state.
|
|
|
|
*~/.config/openshell/gateways/openshell/mtls/*
|
|
: Client mTLS certificates for CLI auto-discovery.
|
|
|
|
# EXAMPLES
|
|
|
|
Start the gateway as a systemd user service:
|
|
|
|
systemctl --user enable --now openshell-gateway
|
|
|
|
Check gateway health from the CLI:
|
|
|
|
openshell gateway add --local https://127.0.0.1:17670
|
|
openshell status
|
|
|
|
Override the API port in TOML:
|
|
|
|
$EDITOR ~/.config/openshell/gateway.toml
|
|
systemctl --user restart openshell-gateway
|
|
|
|
# SEE ALSO
|
|
|
|
**openshell**(1), **systemctl**(1), **journalctl**(1), **loginctl**(1),
|
|
**podman**(1)
|
|
|
|
Full documentation: *https://docs.nvidia.com/openshell/*
|