Skip to content

Overview

Sherpa is a lab management platform for building virtual network topologies using virtual machines, containers, and unikernels. It is designed as a client/server architecture with multiple access methods.

Sherpa architecture: the sherpa CLI and web browsers connect to sherpad, which drives Libvirt and Docker, keeps its own embedded database, and manages host networking and storage

Client/Server

Server

The sherpad process runs as a systemd service on the host compute server. It manages the full lifecycle of labs, nodes, images, and users. The server exposes three interfaces:

  • WebSocket RPC — JSON-RPC 2.0 over WebSocket at wss://<server>:3030/ws. This is the primary transport used by the sherpa CLI.
  • REST API — Standard HTTP endpoints at https://<server>:3030/api/v1/. Supports JSON request/response bodies and Server-Sent Events (SSE) for streaming operations.
  • Web UI — Browser-based interface at https://<server>:3030/ built with HTMX. Provides lab management, image management, user administration, and interactive API documentation via Swagger UI at /api/docs.

A separate HTTP-only endpoint on port 3031 serves the server's TLS certificate for client trust bootstrapping.

Client

The sherpa client is a CLI utility that connects to the server over WebSocket RPC. It can be installed on Linux, macOS, and Windows. Client configuration and cached files are stored at ~/.sherpa/.

Providers

Sherpa supports three node kinds through different virtualisation providers:

Provider Technology Node Kind
Virtual Machine KVM/QEMU via Libvirt Virtual Machine
Container Docker (Bollard API) Container
Unikernel Nanos and Unikraft via Libvirt Unikernel

Virtual Machines

Virtual machines use the KVM hypervisor with the QEMU emulator. Sherpa manages VMs through the Libvirt virtualisation API, which handles domain lifecycle, storage pools, and network interfaces. Each VM is defined as a libvirt domain with configurable CPU, RAM, disk, and network parameters.

Containers

Containers run on the Docker engine. Sherpa communicates with Docker via the Bollard API library to manage container lifecycle, networking, and volumes. Container images can be pulled from OCI registries or imported from local archives.

Unikernels

Unikernels are single-purpose machine images that run directly on KVM/QEMU via Libvirt, similar to virtual machines but with a minimal footprint. Sherpa supports Nanos and Unikraft unikernels.

Database

Sherpa stores lab state, node configurations, user accounts, and image metadata in an embedded Turso database, a Rust rewrite of SQLite that runs inside sherpad. The data is a single file, /opt/sherpa/db/sherpa.sqlite. See Database for details.

Authentication

All API access (except login) requires authentication. Sherpa supports two authentication methods:

  • JWT Bearer Token — obtained via sherpa login or the login API endpoint. Tokens are valid for 7 days.
  • Cookie — sherpa_auth cookie used by the Web UI. Valid for 7 days, or 30 days with Remember me.

Every login starts a session on the server, and a token works only while its session lasts. Logging out (sherpa logout, Logout in the web UI, or the logout API endpoint) ends that one session, so a copied token stops working too. Changing your password ends your other sessions; an admin resetting a user's password, or deleting the user, ends all of that user's sessions. A web page whose session has ended sends you to the login page.

sherpad signs tokens with a secret in /opt/sherpa/.secret/jwt.secret, generated on first start. If the file is damaged (it is not 32 bytes long), sherpad refuses to start rather than replace it, because a new secret logs every user out; see Troubleshooting.

User accounts have one of two roles: Basic (lab operations) or Admin (full access including user and image management). sherpad init creates the built-in admin account and a first user account. The built-in admin account cannot be deleted, renamed or lose its admin role, and cannot start, resume or redeploy labs; labs are started from personal user accounts, which can also be admins.

Admins can list, inspect, stop, resume and destroy other users' labs, but cannot log in to their nodes or get what is needed to. For another user's lab an admin cannot download the lab files (SSH config, known_hosts, Talos, Vault, Keycloak and SurrealDB credentials, the lab CA), cannot open its nodes' serial or VNC consoles, and cannot add SSH keys to the user's account; sherpa ssh and sherpa provision refuse a folder that holds another user's lab, and the server refuses their sherpa console and sherpa vnc. The server logs each admin action on another user's lab and each refusal. Some access remains:

  • An admin who resets a user's Sherpa password can sign in as that user. The reset is logged and ends the user's sessions.
  • Root on the Sherpa host can reach consoles, VNC, disks and the database key. So can members of the kvm group, for consoles, VNC and disks. Admins can start privileged containers and host mounts, which is root on the host.

The boundary is for the admin role through Sherpa's interfaces. It is not a defence against root on the host.

TLS

TLS is enabled by default. With self_generate_cert on, the default, the server keeps its key and writes a new self-signed certificate for it on every start, and clients trust the key, so a renewed certificate needs no new trust. Clients can download and trust the server certificate via sherpa cert trust or from the HTTP endpoint at http://<server>:3031/cert. See Credentials for details.

Networking

Sherpa manages several network types for connecting nodes:

Zero-Touch Provisioning

Sherpa automatically provisions nodes at boot time using device-appropriate ZTP methods. Supported methods include cloud-init, ZTP scripts, and configuration file injection. See Zero-Touch Provisioning for details.

Observability

Sherpa supports OpenTelemetry for exporting traces and metrics to an OTLP-compatible collector. This is configured in the [otel] section of sherpa.toml. Server logs are written to /opt/sherpa/logs/sherpad.log.

Storage

Base images, container archives, and unikernel binaries are stored under /opt/sherpa/. Each lab gets a dedicated directory with cloned disk images and runtime files. See Storage for the full directory layout.