snapcraft.yaml

# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

name: openshell
title: OpenShell
adopt-info: openshell
summary: Safe, sandboxed runtimes for autonomous AI agents
description: |
  OpenShell provides safe, sandboxed runtimes for autonomous AI agents.
  It offers a CLI for managing gateways, sandboxes, and providers with
  policy-enforced egress routing, credential proxying, and privacy-aware
  profile-backed model-provider access.

  The OpenShell snap ships a CLI (`openshell`), a terminal UI (`openshell.term`),
  a standalone policy prover (`openshell.prover` with alias `openshell-prover`),
  and a managed gateway daemon (`openshell.user-gateway`). The user gateway is
  disabled by default so that one selected user can run it.

  **Setup instructions**

    1. Install and start Docker using your preferred package source before
       installing the OpenShell snap. Use a system package or Docker's package
       repository. The Docker snap is not currently compatible with OpenShell.

       Snap Store installations automatically connect the required interfaces.

       Enable and start the gateway from the single user account that will run
       it:

         systemctl --user enable --now snap.openshell.user-gateway.service

       Do not enable the gateway for multiple users who may be logged in at the
       same time. Every user gateway binds to 127.0.0.1:17670, so only one can
       run on the system at a time.

       Older OpenShell snap revisions could enable the user gateway globally.
       When upgrading such an installation, remove that global enablement so
       the gateway does not start automatically for other users:

         sudo systemctl disable --global snap.openshell.user-gateway.service

       This does not stop gateways already running in other user sessions.
       Those users must disable and stop the service from their own sessions.

       If the OpenShell snap was installed before Docker was running, its user
       service may have hit the systemd start limit. Resolve this from the
       affected user's session after Docker is available:

         systemctl --user reset-failed snap.openshell.user-gateway.service
         systemctl --user restart snap.openshell.user-gateway.service

    2. Register the per-user gateway after it provisions its mTLS credentials:

         snap services openshell.user-gateway
         openshell gateway add https://127.0.0.1:17670 --local --name openshell
         openshell status

  **Legacy upgrades**

  Installations upgraded from the former `openshell.gateway` service retain
  their state through `openshell.system-gateway`. Existing HTTPS registrations
  continue to work because the endpoint and TLS identity do not change.

  If this user still has an old HTTP registration, or has not previously been
  enrolled, wait for `openshell.system-gateway` to be active, copy its client
  credentials, and register its HTTPS endpoint:

    snap services openshell.system-gateway
    d=~/snap/openshell/common/.local/state/openshell/tls
    mkdir -p -m 700 "$d" "$d/client"
    sudo install -o "$USER" -g "$(id -gn)" -m 600 \
      /var/snap/openshell/common/tls/ca.crt "$d/"
    sudo install -o "$USER" -g "$(id -gn)" -m 600 \
      /var/snap/openshell/common/tls/client/tls.crt "$d/client/"
    sudo install -o "$USER" -g "$(id -gn)" -m 600 \
      /var/snap/openshell/common/tls/client/tls.key "$d/client/"
    openshell gateway list
    old_registration="NAME_FROM_GATEWAY_LIST"
    openshell gateway remove "$old_registration"
    openshell gateway add https://127.0.0.1:17670 --local --name openshell
    openshell status

  The user and system gateways have separate state. See the OpenShell
  installation guide before changing `gateway-mode`; use `gateway-mode=disable`
  to stop both services while preserving the current TLS directory.

base: core24
grade: stable
confinement: strict
# The system :docker slot was added in snapd 2.76, so this is the minimum
# required version. Snapd 2.77 allowed manual connection to that slot without
# snap-declaration overrides from the store, such as when installing a locally-
# built snap, but that is not required for installations from the snap store.
assumes: [snapd2.76]
license: Apache-2.0
website: https://docs.nvidia.com/openshell/latest/index.html
source-code: https://github.com/NVIDIA/OpenShell
issues: https://github.com/NVIDIA/OpenShell/issues
contact: https://github.com/NVIDIA/OpenShell/security/policy
platforms:
  amd64:
    build-on: [amd64]
    build-for: [amd64]
  arm64:
    build-on: [arm64]
    build-for: [arm64]

apps:
  openshell:
    command: bin/openshell
    environment:
      XDG_CONFIG_HOME: "$SNAP_USER_COMMON/.config"
      XDG_DATA_HOME: "$SNAP_USER_COMMON/.local/share"
      XDG_STATE_HOME: "$SNAP_USER_COMMON/.local/state"
    plugs:
      - home
      - network
      - system-observe
  term:
    command: bin/openshell term
    desktop: meta/gui/term.desktop
    environment:
      XDG_CONFIG_HOME: "$SNAP_USER_COMMON/.config"
      XDG_DATA_HOME: "$SNAP_USER_COMMON/.local/share"
      XDG_STATE_HOME: "$SNAP_USER_COMMON/.local/state"
    plugs:
      - home
      - network
      - system-observe
  prover:
    command: bin/openshell-prover
    aliases:
      - openshell-prover
    plugs:
      - home
  system-gateway:
    command: bin/openshell-gateway-wrapper
    daemon: simple
    daemon-scope: system
    install-mode: disable
    # refresh-mode: endure prevents snapd from restarting the gateway daemon
    # during snap refreshes, which would kill active sandbox sessions.
    # The installer restarts the selected service after an explicit refresh.
    refresh-mode: endure
    # This compatibility daemon runs as root. The wrapper serves TLS from the bundle
    # generated in $SNAP_COMMON/tls, and the default config requires client
    # certificates; the legacy installer path copies the client bundle to the
    # target user. The wrapper uses $SNAP_COMMON/gateway.db. Before startup it
    # bootstraps package-managed credentials and validates the selected
    # operator-provided config without creating or rewriting it. A nonempty
    # OPENSHELL_GATEWAY_CONFIG takes precedence over gateway.toml.
    environment:
      XDG_DATA_HOME: "$SNAP_COMMON"
      OPENSHELL_SNAP_CONFIG_FILE: "$SNAP_COMMON/gateway.toml"
      OPENSHELL_DB_URL: "sqlite:$SNAP_COMMON/gateway.db?mode=rwc"
      OPENSHELL_LOCAL_TLS_DIR: "$SNAP_COMMON/tls"
    plugs:
      - docker
      - log-observe
      - network
      - network-bind
      - system-observe
  user-gateway:
    command: bin/openshell-gateway-wrapper
    daemon: simple
    daemon-scope: user
    install-mode: disable
    refresh-mode: endure
    # Use persistent user-owned XDG roots shared with the snap CLI and TUI.
    # Snapd provides the ephemeral XDG_RUNTIME_DIR automatically.
    environment:
      XDG_CONFIG_HOME: "$SNAP_USER_COMMON/.config"
      XDG_DATA_HOME: "$SNAP_USER_COMMON/.local/share"
      XDG_STATE_HOME: "$SNAP_USER_COMMON/.local/state"
    plugs:
      - docker
      - log-observe
      - network
      - network-bind
      - system-observe

parts:
  openshell:
    plugin: nil
    source: ./snap/prebuilt
    override-pull: |
      craftctl default
      craftctl set version="$(cat "$CRAFT_PART_SRC/version")"
    override-build: |
      set -euo pipefail

      MISSING=()
      for bin in openshell openshell-prover openshell-gateway openshell-sandbox openshell-gateway-wrapper; do
        if [ ! -f "$CRAFT_PART_SRC/$bin" ]; then
          MISSING+=("$bin")
        fi
      done

      if [ ${#MISSING[@]} -gt 0 ]; then
        printf '%s\n' \
          "ERROR: snap/prebuilt/ is incomplete:" \
          "${MISSING[@]/#/'  - '}" \
          "" \
          "The snap build directory must be populated by CI before snapcraft pack." \
          >&2
        exit 1
      fi

      install -D -m 0755 "$CRAFT_PART_SRC/openshell" \
        "$CRAFT_PART_INSTALL/bin/openshell"
      install -D -m 0755 "$CRAFT_PART_SRC/openshell-prover" \
        "$CRAFT_PART_INSTALL/bin/openshell-prover"
      install -D -m 0755 "$CRAFT_PART_SRC/openshell-gateway" \
        "$CRAFT_PART_INSTALL/bin/openshell-gateway"
      install -D -m 0755 "$CRAFT_PART_SRC/openshell-sandbox" \
        "$CRAFT_PART_INSTALL/bin/openshell-sandbox"
      install -D -m 0755 "$CRAFT_PART_SRC/openshell-gateway-wrapper" \
        "$CRAFT_PART_INSTALL/bin/openshell-gateway-wrapper"
      install -D -m 0644 "$CRAFT_PART_SRC/meta/gui/term.desktop" \
        "$CRAFT_PART_INSTALL/meta/gui/term.desktop"
      install -D -m 0644 "$CRAFT_PART_SRC/meta/gui/icon.png" \
        "$CRAFT_PART_INSTALL/meta/gui/icon.png"
      install -D -m 0644 "$CRAFT_PART_SRC/LICENSE" \
        "$CRAFT_PART_INSTALL/usr/share/doc/openshell/LICENSE"
      install -D -m 0644 "$CRAFT_PART_SRC/README.md" \
        "$CRAFT_PART_INSTALL/usr/share/doc/openshell/README.md"

  ssh:
    # Vendor the openssh-client `ssh` binary into the snap so the CLI/TUI
    # can spawn `ssh` for sandbox connect/exec/forward without relying on
    # the host's ssh-keys interface. The binary lands at
    # $SNAP/usr/bin/ssh and is found via the snap runtime PATH.
    plugin: nil
    stage-packages:
      - openssh-client
    prime:
      - usr/bin/ssh