Skip to content

Commit 9f8edb5

Browse files
ericcurtinericcurtin
authored
docs(installation): add container gateway page with docker run and compose examples (#1321)
Add a dedicated page documenting how to run the OpenShell gateway as a container using docker run, docker-compose, or podman, without the system package manager installer. This is useful for users on immutable OS distributions (Fedora CoreOS, bootc-based images, Silverblue) where the standard install.sh path is not appropriate, and for container-first environments. Covers a quick-start with TLS disabled (localhost-bound), a full mTLS setup using the gateway's generate-certs subcommand, a docker-compose example, and a Podman variant. Closes the gap raised in #1285. Signed-off-by: Eric Curtin <eric.curtin@docker.com>
1 parent 9a7c0df commit 9f8edb5

4 files changed

Lines changed: 151 additions & 2 deletions

File tree

‎docs/about/container-gateway.mdx‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
3+
# SPDX-License-Identifier: Apache-2.0
4+
title: "Running the Gateway as a Container"
5+
sidebar-title: "Container Gateway"
6+
description: "Run the OpenShell gateway using docker run or docker-compose without the installer."
7+
keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Docker, Podman, docker-compose, container, immutable OS, bootc, rpm-ostree"
8+
position: 4
9+
---
10+
11+
Use this approach when you want to run the OpenShell gateway as a container instead of installing it with the system package manager. This is useful on immutable OS distributions (Fedora CoreOS, bootc-based images, Silverblue) where the standard installer is not appropriate, or anywhere you prefer a container-first workflow.
12+
13+
The gateway image is published at `ghcr.io/nvidia/openshell/gateway`.
14+
15+
## Quick Start
16+
17+
This example runs the gateway locally with TLS disabled. It is suitable for development on a single machine. Binding to `127.0.0.1` prevents remote access without authentication.
18+
19+
```shell
20+
docker run -d \
21+
--name openshell-gateway \
22+
--restart unless-stopped \
23+
-p 127.0.0.1:8080:8080 \
24+
-v openshell-state:/var/openshell \
25+
-v /var/run/docker.sock:/var/run/docker.sock \
26+
-e OPENSHELL_DRIVERS=docker \
27+
-e OPENSHELL_DB_URL=sqlite:/var/openshell/openshell.db \
28+
-e OPENSHELL_DISABLE_TLS=true \
29+
ghcr.io/nvidia/openshell/gateway:latest
30+
```
31+
32+
Register the gateway with the CLI:
33+
34+
```shell
35+
openshell gateway add http://127.0.0.1:8080 --local --name local
36+
```
37+
38+
Confirm the CLI can reach the gateway:
39+
40+
```shell
41+
openshell status
42+
```
43+
44+
<Warning>
45+
Disabling TLS removes authentication. Binding to `127.0.0.1` limits access to the local machine. If you expose the port on `0.0.0.0`, enable mTLS to prevent unauthenticated access.
46+
</Warning>
47+
48+
## Full mTLS Setup
49+
50+
To run the gateway with mutual TLS, generate the PKI bundle first, then start the gateway with the cert paths configured.
51+
52+
Bootstrap the PKI into a local state directory:
53+
54+
```shell
55+
mkdir -p ~/.local/state/openshell/tls
56+
57+
docker run --rm \
58+
-v "$HOME/.local/state/openshell:/home/openshell/.local/state/openshell" \
59+
-v "$HOME/.config/openshell:/home/openshell/.config/openshell" \
60+
ghcr.io/nvidia/openshell/gateway:latest \
61+
generate-certs --output-dir /home/openshell/.local/state/openshell/tls
62+
```
63+
64+
This writes the server and client certificates under `~/.local/state/openshell/tls/` and copies the client bundle to `~/.config/openshell/gateways/openshell/mtls/` so the CLI picks it up automatically.
65+
66+
Start the gateway with mTLS enabled:
67+
68+
```shell
69+
docker run -d \
70+
--name openshell-gateway \
71+
--restart unless-stopped \
72+
-p 127.0.0.1:8080:8080 \
73+
-v "$HOME/.local/state/openshell:/home/openshell/.local/state/openshell" \
74+
-v /var/run/docker.sock:/var/run/docker.sock \
75+
-e OPENSHELL_DRIVERS=docker \
76+
-e OPENSHELL_DB_URL=sqlite:/home/openshell/.local/state/openshell/openshell.db \
77+
-e OPENSHELL_TLS_CERT=/home/openshell/.local/state/openshell/tls/server/tls.crt \
78+
-e OPENSHELL_TLS_KEY=/home/openshell/.local/state/openshell/tls/server/tls.key \
79+
-e OPENSHELL_TLS_CLIENT_CA=/home/openshell/.local/state/openshell/tls/ca.crt \
80+
-e OPENSHELL_DOCKER_TLS_CA=/home/openshell/.local/state/openshell/tls/ca.crt \
81+
-e OPENSHELL_DOCKER_TLS_CERT=/home/openshell/.local/state/openshell/tls/client/tls.crt \
82+
-e OPENSHELL_DOCKER_TLS_KEY=/home/openshell/.local/state/openshell/tls/client/tls.key \
83+
ghcr.io/nvidia/openshell/gateway:latest
84+
```
85+
86+
Register the gateway with mTLS:
87+
88+
```shell
89+
openshell gateway add https://127.0.0.1:8080 --local --name local
90+
```
91+
92+
## Docker Compose
93+
94+
Save the following as `compose.yml`. This uses the TLS-disabled configuration bound to localhost, suitable for local development.
95+
96+
```yaml
97+
services:
98+
gateway:
99+
image: ghcr.io/nvidia/openshell/gateway:latest
100+
restart: unless-stopped
101+
ports:
102+
- "127.0.0.1:8080:8080"
103+
volumes:
104+
- openshell-state:/var/openshell
105+
- /var/run/docker.sock:/var/run/docker.sock
106+
environment:
107+
OPENSHELL_DRIVERS: docker
108+
OPENSHELL_DB_URL: "sqlite:/var/openshell/openshell.db"
109+
OPENSHELL_DISABLE_TLS: "true"
110+
111+
volumes:
112+
openshell-state:
113+
```
114+
115+
Start the gateway:
116+
117+
```shell
118+
docker compose up -d
119+
```
120+
121+
Register the gateway with the CLI:
122+
123+
```shell
124+
openshell gateway add http://127.0.0.1:8080 --local --name local
125+
```
126+
127+
## Using Podman
128+
129+
Replace `docker` with `podman` in the commands above. Mount the Podman socket instead of the Docker socket and set the driver to `podman`:
130+
131+
```shell
132+
podman run -d \
133+
--name openshell-gateway \
134+
-p 127.0.0.1:8080:8080 \
135+
-v openshell-state:/var/openshell \
136+
-v "$XDG_RUNTIME_DIR/podman/podman.sock:/var/run/podman.sock" \
137+
-e OPENSHELL_DRIVERS=podman \
138+
-e OPENSHELL_PODMAN_SOCKET=/var/run/podman.sock \
139+
-e OPENSHELL_DB_URL=sqlite:/var/openshell/openshell.db \
140+
-e OPENSHELL_DISABLE_TLS=true \
141+
ghcr.io/nvidia/openshell/gateway:latest
142+
```
143+
144+
## Next Steps
145+
146+
- To create your first sandbox, refer to the [Quickstart](/get-started/quickstart).
147+
- To control what the agent can access, refer to [Policies](/sandboxes/policies).
148+
- For environment variable reference, refer to [Sandbox Compute Drivers](/reference/sandbox-compute-drivers).

‎docs/about/installation.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ Kubernetes deployments use the OpenShell Helm chart. For step-by-step installati
7676
## Next Steps
7777

7878
- To create your first sandbox, refer to the [Quickstart](/get-started/quickstart).
79+
- To run the gateway as a container without the installer, refer to [Running the Gateway as a Container](/about/container-gateway).
7980
- To register, select, and inspect gateways, refer to [Gateways](/sandboxes/manage-gateways).
8081
- To supply API keys or tokens, refer to [Manage Providers](/sandboxes/manage-providers).
8182
- To control what the agent can access, refer to [Policies](/sandboxes/policies).

‎docs/about/release-notes.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ title: "NVIDIA OpenShell Release Notes"
55
sidebar-title: "Release Notes"
66
description: "Track the latest changes and improvements to NVIDIA OpenShell."
77
keywords: "Generative AI, Cybersecurity, Release Notes, Changelog, AI Agents"
8-
position: 5
8+
position: 6
99
---
1010

1111
NVIDIA OpenShell follows a frequent release cadence. Use the following GitHub resources directly.

‎docs/about/supported-agents.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
title: "Supported Agents"
55
description: "AI agent frameworks and runtimes compatible with OpenShell sandboxes."
66
keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Claude, Codex, Cursor"
7-
position: 4
7+
position: 5
88
---
99
The following table summarizes the agents that run in OpenShell sandboxes. All agent sandbox images are maintained in the [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) repository. Agents in the base image are auto-configured when passed as the trailing command to `openshell sandbox create`.
1010

0 commit comments

Comments
 (0)