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.
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 thesherpaCLI. - 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 loginor the login API endpoint. Tokens are valid for 7 days. - Cookie —
sherpa_authcookie 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
kvmgroup, 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:
- Management Network — connects all nodes to the server for SSH access and ZTP
- Point-to-Point Links — direct connections between two nodes
- Private Bridges — shared segments visible only within a lab
- Public Bridges — connects nodes to the host's physical network (planned)
- Isolated Bridges — holds a node's unused interfaces, link down
- Reserved Bridges — holds interfaces a node reserves for its own control plane
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.