Skip to content

Instantly share code, notes, and snippets.

@pimlock
Last active June 23, 2026 21:52
Show Gist options
  • Select an option

  • Save pimlock/1bbd1d8970318d7b0053e164392c95de to your computer and use it in GitHub Desktop.

Select an option

Save pimlock/1bbd1d8970318d7b0053e164392c95de to your computer and use it in GitHub Desktop.
OpenShell Linux tarball installer.
#!/bin/sh
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Install OpenShell Linux release tarballs and a systemd user gateway service.
set -e
APP_NAME="openshell"
REPO="NVIDIA/OpenShell"
GITHUB_URL="https://github.com/${REPO}"
RELEASE_TAG="${OPENSHELL_VERSION:-}"
CHECKSUMS_NAME="openshell-checksums-sha256.txt"
GATEWAY_CHECKSUMS_NAME="openshell-gateway-checksums-sha256.txt"
LOCAL_GATEWAY_PORT="${OPENSHELL_SERVER_PORT:-17670}"
LINUX_GATEWAY_GLIBC_MIN_VERSION="2.28"
PREFIX="${OPENSHELL_INSTALL_PREFIX:-/usr/local}"
START_SERVICE="${OPENSHELL_INSTALL_START_SERVICE:-1}"
REGISTER_GATEWAY="${OPENSHELL_INSTALL_REGISTER_GATEWAY:-1}"
info() {
printf '%s: %s\n' "$APP_NAME" "$*" >&2
}
warn() {
printf '%s: warning: %s\n' "$APP_NAME" "$*" >&2
}
error() {
printf '%s: error: %s\n' "$APP_NAME" "$*" >&2
exit 1
}
usage() {
cat <<EOF
install-tarball.sh - Install OpenShell from Linux release tarballs
USAGE:
curl -fsSL https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install-tarball.sh | sh
OPTIONS:
--help Print this help message
ENVIRONMENT VARIABLES:
OPENSHELL_VERSION Release tag to install. Defaults to the
latest tagged release. Set to dev for
the rolling dev release.
OPENSHELL_INSTALL_PREFIX Install prefix. Defaults to /usr/local.
OPENSHELL_DRIVERS Optional gateway driver override to seed
in ~/.config/openshell/gateway.toml.
Examples: docker, podman, kubernetes, vm.
OPENSHELL_INSTALL_START_SERVICE Set to 0 to install without starting the
systemd user service.
OPENSHELL_INSTALL_REGISTER_GATEWAY Set to 0 to skip CLI gateway registration.
NOTES:
This installer downloads the standalone openshell CLI and openshell-gateway
Linux tarballs, verifies checksums, installs binaries, and creates a systemd
user service. It does not install Podman, Docker, or any other compute
driver runtime.
EOF
}
has_cmd() {
command -v "$1" >/dev/null 2>&1
}
require_cmd() {
if ! has_cmd "$1"; then
error "'$1' is required"
fi
}
download() {
_url="$1"
_output="$2"
curl -fLsS --retry 3 --max-redirs 5 -o "$_output" "$_url"
}
download_release_asset() {
_tag="$1"
_filename="$2"
_output="$3"
if curl -fLsS --retry 3 --max-redirs 5 -o "$_output" \
"${GITHUB_URL}/releases/download/${_tag}/${_filename}"; then
return 0
fi
_normalized="$(printf '%s' "$_filename" | tr '~' '.')"
if [ "$_normalized" != "$_filename" ]; then
if download "${GITHUB_URL}/releases/download/${_tag}/${_normalized}" "$_output"; then
info "using GitHub-normalized asset name ${_normalized}"
return 0
fi
fi
return 1
}
as_root() {
if [ "$(id -u)" -eq 0 ]; then
"$@"
elif has_cmd sudo; then
sudo "$@"
else
error "this installer needs root privileges; rerun as root or install sudo"
fi
}
target_user() {
if [ "$(id -u)" -eq 0 ] && [ -n "${SUDO_USER:-}" ] && [ "${SUDO_USER}" != "root" ]; then
echo "$SUDO_USER"
else
id -un
fi
}
user_home() {
_user="$1"
if has_cmd getent; then
_home="$(getent passwd "$_user" | awk -F: '{ print $6 }')"
if [ -n "$_home" ]; then
echo "$_home"
return 0
fi
fi
if [ "$(id -un)" = "$_user" ]; then
echo "${HOME:-}"
return 0
fi
echo "/home/${_user}"
}
as_target_user() {
_bus="unix:path=${TARGET_RUNTIME_DIR}/bus"
if [ "$(id -u)" -eq "$TARGET_UID" ]; then
env HOME="$TARGET_HOME" XDG_RUNTIME_DIR="$TARGET_RUNTIME_DIR" DBUS_SESSION_BUS_ADDRESS="$_bus" "$@"
elif has_cmd sudo; then
sudo -u "$TARGET_USER" env HOME="$TARGET_HOME" XDG_RUNTIME_DIR="$TARGET_RUNTIME_DIR" DBUS_SESSION_BUS_ADDRESS="$_bus" "$@"
elif has_cmd runuser; then
runuser -u "$TARGET_USER" -- env HOME="$TARGET_HOME" XDG_RUNTIME_DIR="$TARGET_RUNTIME_DIR" DBUS_SESSION_BUS_ADDRESS="$_bus" "$@"
else
error "cannot run user service commands as ${TARGET_USER}; install sudo or run as ${TARGET_USER}"
fi
}
resolve_release_tag() {
if [ -n "$RELEASE_TAG" ] && [ "$RELEASE_TAG" != "latest" ]; then
if [ "$RELEASE_TAG" = "dev" ]; then
echo "dev"
else
echo "$RELEASE_TAG"
fi
return 0
fi
_latest_url="${GITHUB_URL}/releases/latest"
_resolved="$(curl -fLsS -o /dev/null -w '%{url_effective}' "$_latest_url")"
_tag="${_resolved##*/}"
[ -n "$_tag" ] || error "could not resolve latest release tag"
echo "$_tag"
}
version_at_least_major_minor() {
_version="$1"
_minimum="$2"
_major="${_version%%.*}"
_rest="${_version#*.}"
_minor="${_rest%%.*}"
_min_major="${_minimum%%.*}"
_min_rest="${_minimum#*.}"
_min_minor="${_min_rest%%.*}"
case "$_major:$_minor:$_min_major:$_min_minor" in
*[!0-9:]* | *::*)
return 1
;;
esac
[ "$_major" -gt "$_min_major" ] && return 0
[ "$_major" -lt "$_min_major" ] && return 1
[ "$_minor" -ge "$_min_minor" ]
}
detect_glibc_version() {
if has_cmd getconf; then
_out="$(getconf GNU_LIBC_VERSION 2>/dev/null || true)"
case "$_out" in
glibc\ [0-9]*.[0-9]*)
printf '%s\n' "${_out#glibc }"
return 0
;;
esac
fi
if has_cmd ldd; then
_out="$(ldd --version 2>&1 | sed -n '1p' || true)"
case "$_out" in
*musl*)
return 2
;;
*[0-9]*.[0-9]*)
printf '%s\n' "$_out" | sed -n 's/.* \([0-9][0-9]*\.[0-9][0-9]*\).*/\1/p' | sed -n '1p'
return 0
;;
esac
fi
return 1
}
require_linux_gateway_glibc() {
_status=0
_glibc_version="$(detect_glibc_version)" || _status=$?
case "$_status" in
0)
;;
2)
error "OpenShell gateway tarballs require glibc >= ${LINUX_GATEWAY_GLIBC_MIN_VERSION}; detected musl or unsupported libc."
;;
*)
error "OpenShell gateway tarballs require glibc >= ${LINUX_GATEWAY_GLIBC_MIN_VERSION}; could not detect glibc."
;;
esac
if ! version_at_least_major_minor "$_glibc_version" "$LINUX_GATEWAY_GLIBC_MIN_VERSION"; then
error "OpenShell gateway tarballs require glibc >= ${LINUX_GATEWAY_GLIBC_MIN_VERSION}; detected glibc ${_glibc_version}."
fi
}
linux_arch() {
_arch="$(uname -m)"
case "$_arch" in
x86_64|amd64)
echo "x86_64"
;;
aarch64|arm64)
echo "aarch64"
;;
*)
error "no Linux tarball is published for architecture: ${_arch}"
;;
esac
}
cli_target() {
case "$1" in
x86_64) echo "x86_64-unknown-linux-musl" ;;
aarch64) echo "aarch64-unknown-linux-musl" ;;
*) error "unsupported CLI architecture: $1" ;;
esac
}
gateway_target() {
case "$1" in
x86_64) echo "x86_64-unknown-linux-gnu" ;;
aarch64) echo "aarch64-unknown-linux-gnu" ;;
*) error "unsupported gateway architecture: $1" ;;
esac
}
find_checksum_asset() {
_checksums="$1"
_asset="$2"
awk -v asset="$_asset" '
$2 == asset || $2 == "*" asset {
sub("^\\*", "", $2)
print $2
exit
}
' "$_checksums"
}
verify_checksum() {
_path="$1"
_checksums="$2"
_asset="$3"
_expected="$(awk -v asset="$_asset" '
$2 == asset || $2 == "*" asset {
print $1
exit
}
' "$_checksums")"
[ -n "$_expected" ] || error "checksum entry not found for ${_asset}"
if has_cmd sha256sum; then
_actual="$(sha256sum "$_path" | awk '{ print $1 }')"
elif has_cmd shasum; then
_actual="$(shasum -a 256 "$_path" | awk '{ print $1 }')"
else
error "'sha256sum' or 'shasum' is required"
fi
[ "$_actual" = "$_expected" ] || error "checksum verification failed for ${_asset}"
}
install_binaries() {
_cli_tar="$1"
_gateway_tar="$2"
_extract_dir="$3"
_bindir="${PREFIX}/bin"
mkdir -p "${_extract_dir}/cli" "${_extract_dir}/gateway"
tar -xzf "$_cli_tar" -C "${_extract_dir}/cli"
tar -xzf "$_gateway_tar" -C "${_extract_dir}/gateway"
[ -x "${_extract_dir}/cli/openshell" ] || error "openshell binary not found in CLI tarball"
[ -x "${_extract_dir}/gateway/openshell-gateway" ] || error "openshell-gateway binary not found in gateway tarball"
info "installing binaries to ${_bindir}..."
as_root install -d -m 0755 "$_bindir"
as_root install -m 0755 "${_extract_dir}/cli/openshell" "${_bindir}/openshell"
as_root install -m 0755 "${_extract_dir}/gateway/openshell-gateway" "${_bindir}/openshell-gateway"
}
write_gateway_template() {
_template="$1"
{
printf '%s\n' '# Default gateway configuration for tarball installs.'
printf '%s\n' '[openshell]'
printf '%s\n' 'version = 1'
printf '%s\n' ''
printf '%s\n' '[openshell.gateway]'
printf 'bind_address = "0.0.0.0:%s"\n' "$LOCAL_GATEWAY_PORT"
if [ -n "${OPENSHELL_DRIVERS:-}" ]; then
printf 'compute_drivers = ["%s"]\n' "$OPENSHELL_DRIVERS"
else
printf '%s\n' '# compute_drivers is unset so the gateway auto-detects Kubernetes, Podman, then Docker.'
fi
} >"$_template"
}
install_service() {
_tmpdir="$1"
_bindir="${PREFIX}/bin"
_sharedir="${PREFIX}/share/openshell-gateway"
_unit_dir="/etc/systemd/user"
_unit_path="${_unit_dir}/openshell-gateway.service"
_template_path="${_sharedir}/gateway.toml.default"
_template_tmp="${_tmpdir}/gateway.toml.default"
_unit_tmp="${_tmpdir}/openshell-gateway.service"
write_gateway_template "$_template_tmp"
cat >"$_unit_tmp" <<EOF
[Unit]
Description=OpenShell Gateway (tarball)
Documentation=https://github.com/NVIDIA/OpenShell
After=default.target
[Service]
Type=exec
Environment=OPENSHELL_LOCAL_TLS_DIR=%h/.local/state/openshell/tls
EnvironmentFile=-%E/openshell/gateway.env
ExecStartPre=/bin/sh -c 'test -f %E/openshell/gateway.toml || install -Dm644 ${_template_path} %E/openshell/gateway.toml'
ExecStartPre=${_bindir}/openshell-gateway generate-certs --output-dir \${OPENSHELL_LOCAL_TLS_DIR} --server-san host.openshell.internal
ExecStart=${_bindir}/openshell-gateway
StateDirectory=openshell
Restart=on-failure
RestartSec=5
NoNewPrivileges=yes
ProtectSystem=strict
PrivateTmp=yes
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
[Install]
WantedBy=default.target
EOF
info "installing gateway config template and systemd user service..."
as_root install -d -m 0755 "$_sharedir" "$_unit_dir"
as_root install -m 0644 "$_template_tmp" "$_template_path"
as_root install -m 0644 "$_unit_tmp" "$_unit_path"
}
compute_runtime_available() {
if [ -n "${OPENSHELL_DRIVERS:-}" ]; then
return 0
fi
if [ -n "${KUBERNETES_SERVICE_HOST:-}" ]; then
return 0
fi
if has_cmd podman && podman info >/dev/null 2>&1; then
return 0
fi
if has_cmd docker && docker info >/dev/null 2>&1; then
return 0
fi
return 1
}
start_user_gateway() {
if [ "$START_SERVICE" != "1" ]; then
info "service installed but not started because OPENSHELL_INSTALL_START_SERVICE=${START_SERVICE}"
return 0
fi
if ! compute_runtime_available; then
warn "no compute driver runtime detected; leaving openshell-gateway installed but stopped"
info "install Docker or Podman, run inside Kubernetes, or set OPENSHELL_DRIVERS, then start with: systemctl --user enable --now openshell-gateway"
return 0
fi
if ! as_target_user systemctl --user daemon-reload >/dev/null 2>&1; then
warn "could not reach the user systemd manager for ${TARGET_USER}"
info "start later with: systemctl --user daemon-reload && systemctl --user enable --now openshell-gateway"
return 0
fi
info "enabling and restarting openshell-gateway user service as ${TARGET_USER}..."
as_target_user systemctl --user enable openshell-gateway
as_target_user systemctl --user restart openshell-gateway
if ! as_target_user systemctl --user is-active --quiet openshell-gateway; then
warn "openshell-gateway service did not become active"
info "inspect it with: systemctl --user status openshell-gateway"
return 0
fi
if [ "$REGISTER_GATEWAY" = "1" ]; then
info "registering local gateway as ${TARGET_USER}..."
if ! as_target_user "${PREFIX}/bin/openshell" gateway add "https://127.0.0.1:${LOCAL_GATEWAY_PORT}" --local --name openshell >/dev/null 2>&1; then
warn "could not register the local gateway automatically"
info "register it later with: openshell gateway add https://127.0.0.1:${LOCAL_GATEWAY_PORT} --local --name openshell"
fi
fi
}
main() {
if [ "$#" -gt 0 ]; then
case "$1" in
--help)
usage
exit 0
;;
*)
error "unknown option: $1"
;;
esac
fi
[ "$(uname -s)" = "Linux" ] || error "tarball service installs are supported on Linux only"
require_cmd curl
require_cmd tar
require_cmd install
require_linux_gateway_glibc
RELEASE_TAG="$(resolve_release_tag)"
TARGET_USER="$(target_user)"
TARGET_UID="$(id -u "$TARGET_USER" 2>/dev/null || true)"
[ -n "$TARGET_UID" ] || error "cannot resolve uid for ${TARGET_USER}"
TARGET_HOME="$(user_home "$TARGET_USER")"
TARGET_RUNTIME_DIR="/run/user/${TARGET_UID}"
_arch="$(linux_arch)"
_cli_asset="openshell-$(cli_target "$_arch").tar.gz"
_gateway_asset="openshell-gateway-$(gateway_target "$_arch").tar.gz"
_tmpdir="$(mktemp -d)"
chmod 0755 "$_tmpdir"
trap 'rm -rf "$_tmpdir"' EXIT
info "downloading ${RELEASE_TAG} checksums..."
download "${GITHUB_URL}/releases/download/${RELEASE_TAG}/${CHECKSUMS_NAME}" "${_tmpdir}/${CHECKSUMS_NAME}"
download "${GITHUB_URL}/releases/download/${RELEASE_TAG}/${GATEWAY_CHECKSUMS_NAME}" "${_tmpdir}/${GATEWAY_CHECKSUMS_NAME}"
_cli_asset="$(find_checksum_asset "${_tmpdir}/${CHECKSUMS_NAME}" "$_cli_asset")"
[ -n "$_cli_asset" ] || error "CLI tarball not found in ${CHECKSUMS_NAME}"
_gateway_asset="$(find_checksum_asset "${_tmpdir}/${GATEWAY_CHECKSUMS_NAME}" "$_gateway_asset")"
[ -n "$_gateway_asset" ] || error "gateway tarball not found in ${GATEWAY_CHECKSUMS_NAME}"
info "selected ${_cli_asset} and ${_gateway_asset}"
download_release_asset "$RELEASE_TAG" "$_cli_asset" "${_tmpdir}/${_cli_asset}" || error "failed to download ${_cli_asset}"
download_release_asset "$RELEASE_TAG" "$_gateway_asset" "${_tmpdir}/${_gateway_asset}" || error "failed to download ${_gateway_asset}"
info "verifying checksums..."
verify_checksum "${_tmpdir}/${_cli_asset}" "${_tmpdir}/${CHECKSUMS_NAME}" "$_cli_asset"
verify_checksum "${_tmpdir}/${_gateway_asset}" "${_tmpdir}/${GATEWAY_CHECKSUMS_NAME}" "$_gateway_asset"
install_binaries "${_tmpdir}/${_cli_asset}" "${_tmpdir}/${_gateway_asset}" "${_tmpdir}/extract"
install_service "$_tmpdir"
start_user_gateway
info "installed OpenShell tarball release ${RELEASE_TAG}"
}
main "$@"
@pimlock

pimlock commented Jun 23, 2026

Copy link
Copy Markdown
Author

Use:

curl -fsSL https://gist.githubusercontent.com/pimlock/1bbd1d8970318d7b0053e164392c95de/raw/install-tarball.sh | sh

Optional: OPENSHELL_DRIVERS=docker, OPENSHELL_VERSION=dev or a tag, OPENSHELL_INSTALL_START_SERVICE=0.

@pimlock

pimlock commented Jun 23, 2026

Copy link
Copy Markdown
Author

To remove:

PREFIX=/usr/local

systemctl --user disable --now openshell-gateway || true

"$PREFIX/bin/openshell" gateway remove openshell || true

sudo rm -f /etc/systemd/user/openshell-gateway.service
sudo rm -f "$PREFIX/bin/openshell" "$PREFIX/bin/openshell-gateway"
sudo rm -rf "$PREFIX/share/openshell-gateway"

systemctl --user daemon-reload || true

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment