• Get started

    • Getting started
    • Concepts
    • Tour
  • Using shpyrd

    • Deploying
    • shpyrd.yaml
    • Resources
    • Databases and caches
    • Domains and exposure
    • Sign-in for your app
    • Teams, roles and security
    • AI assistants (MCP)
    • Logs
    • Dashboard
    • CLI reference
  • Running it yourself

    • Installation
    • Oracle Cloud (OKE)
    • AWS (EKS)
    • Extensions and sign-in
    • Platform backups
    • Architecture guide
  • Project

    • Design principles
    • Roadmap
    • How to contribute
    • Support the project
  1. Running it yourself
  2. Installation
Sign in
Start free

Installation

Create a local cluster with the shpyrd base stack, or install it on an existing Kubernetes cluster.

On shpyrd cloud the platform is run for you: see Getting started. shpyrd is also open source, and this page is for running it yourself. Two CLIs install together: shpyrd for people who deploy, shpyrd-ctl for the operator who runs the cluster. Either installs the platform on a Kubernetes cluster (shpyrd-ctl cluster … and shpyrd cluster … are the same commands): a local kind cluster it creates for you, or a cluster you already have - on Oracle Cloud (OKE) or AWS (EKS), other providers as their profiles arrive. This page covers the local cluster and what every profile shares.

Requirements

  • Docker (Docker Desktop on macOS/Windows, Docker Engine on Linux). Give it 6-8 GB of memory: the base stack idles around 3 GB and buildpack builds need headroom.
  • Internet access for the first install (kind node image, Helm charts, buildpacks, ~2 GB) and for name resolution of the default 127.0.0.1.nip.io domain.
  • macOS or Linux, Intel or ARM. On Windows, use WSL 2.
Docker Desktop and cgroup v1

Recent Kubernetes releases refuse to run on cgroup v1. If Docker Desktop has the deprecated cgroup v1 setting enabled (DeprecatedCgroupv1 in its settings), shpyrd cluster create detects it, applies a kubelet override and warns; switching Docker Desktop to cgroup v2 is recommended.

Install the CLI

macOS, with Homebrew:

brew install shpyrd-io/tap/shpyrd

macOS or Linux, with the install script (downloads the latest release, verifies its SHA-256 checksum and installs shpyrd and shpyrd-ctl into /usr/local/bin or ~/.local/bin):

curl -fsSL https://shpyrd.io/install.sh | sh

Homebrew installs both binaries too. SHPYRD_VERSION=v0.1.0 pins a version and SHPYRD_INSTALL_DIR=... picks the directory. The archives and checksums are also on the release page for a manual install (Windows archives too; the script and the local cluster need WSL 2). Check with shpyrd version.

Every release also publishes the server image ghcr.io/shpyrd-io/shpyrd-server:<version> for linux/amd64 and linux/arm64; the CLI installs the image of its own version, so CLI and server always match. Upgrading is brew upgrade shpyrd (or re-running the script) followed by shpyrd cluster init.

Building from source

Developers build the CLI with make cli (Go 1.27) after cloning shpyrd-io/shpyrd; a development build installs the latest released server image unless told otherwise with --set SHPYRD_SERVER_IMAGE=... (see the contributing guide).

Create a local cluster

shpyrd cluster create

This runs kind as a library to create a two-node cluster named shpyrd (one control-plane, one worker), then installs the base stack in dependency-ordered runlevels, waiting for each to be healthy:

LevelComponents
rc0Prometheus Operator CRDs
rc1node-local storage for project data, cert-manager, the registry credential, the platform's Service
rc2development CA ClusterIssuer, trust-manager, ingress-nginx (host ports 80/443), the in-cluster registry (TLS from the CA) and the node trust for it
rc3kpack with the Paketo buildpacks builder, kube-prometheus-stack, the control-plane database (PostgreSQL)
rc4shpyrd server (API, App controller, dashboard), the platform backup schedule (only with a backup target)

The first run takes 10-20 minutes, mostly downloads. Re-running cluster create or cluster init on an existing cluster is idempotent and takes about 30 seconds.

Options worth knowing:

shpyrd cluster create --http-port 8080 --https-port 8443   # host ports 80/443 already in useshpyrd cluster create --domain myapps.example.test          # wildcard domain resolving to your machineshpyrd cluster create --workers 2                          # more kind worker nodesshpyrd cluster create --skip monitoring                    # lighter install, no Prometheusshpyrd cluster create --no-init                            # only the kind cluster

Local names and ports

Two choices decide what your URLs look like, and shpyrd cluster create detects the fitting ones:

DefaultAlternative
Names*.127.0.0.1.nip.io: public DNS answers 127.0.0.1, nothing to install (needs internet for name resolution)--local-dns with a domain such as shpyrd.test: a dnsmasq rule and a /etc/resolver/test file make every *.test name resolve to your machine, offline (macOS; one sudo prompt; dnsmasq installed with Homebrew if missing)
Front doorkind maps 80/443 to ingress-nginx; certificates from shpyrd's development CA (cluster trust-ca)--front-door caddy when a Caddy already serves 443: kind takes high ports, shpyrd writes ~/.shpyrd/caddy/shpyrd.caddy proxying *.<domain> to kind and reloads Caddy; certificates come from Caddy's CA you already trust, URLs carry no port

When Caddy is detected the CLI asks:

Caddy v2.11.4 is serving port(s) 80 and 443 on this machine.Use it as the front door (clean https URLs, certificates from Caddy's CA)? [Y/n]

and, unless --domain was given, uses shpyrd.test (offering to configure dnsmasq when the name does not resolve yet). The Caddyfile needs one line, import ~/.shpyrd/caddy/*.caddy, which the CLI offers to add to the Caddyfile of the running Caddy. The result:

  Dashboard:  https://shpyrd.shpyrd.test  Names: dnsmasq (*.shpyrd.test) · Front door: Caddy on 443 -> kind :8080

--yes accepts the proposals (CI does this); --front-door kind refuses them. Both choices are recorded in the cluster, so shpyrd cluster init, cluster status and cluster dashboard keep them; cluster destroy removes the Caddy site and offers to remove the DNS rule if shpyrd wrote it. An existing cluster can switch: shpyrd cluster init --domain shpyrd.test --front-door caddy (identity providers then need the new redirect URIs).

Trust the platform CA

Not needed behind a Caddy front door: Caddy issues the certificates from its own CA (run caddy trust once if your browser warns). Otherwise, certificates for https://<project>.<domain> are issued by a root CA generated on your machine (~/.shpyrd/ca/rootCA.pem) and stored in the cluster. Install it in your operating system trust store once:

shpyrd cluster trust-ca      # asks for sudo (macOS keychain / Linux ca-certificates)

Firefox keeps its own store: enable security.enterprise_roots.enabled in about:config or import the certificate.

Cloud clusters generate their own platform CA at install; it signs the in-cluster registry and the platform's internal endpoints, never the public hostnames (those come from Let's Encrypt). shpyrd cluster trust-ca --context <cluster> fetches and installs that CA when you need to talk to the registry from your machine.

Check the installation

shpyrd cluster status
Profile: local  Version: v0.1.1  Domain: 127.0.0.1.nip.io  Updated: 2026-09-21T22:23:28ZNames: public DNS (127.0.0.1.nip.io) · Front door: kind on 80/443
RUNLEVEL  COMPONENT             STATUS  VERSION  APPLIEDrc0       monitoring-crds       ready   32.0.0   ...rc1       storage-local         ready            ...rc1       cert-manager          ready   v1.21.2  ...rc1       registry-credentials  ready            ...rc1       platform-service      ready            ...rc2       ca-issuers            ready            ...rc2       trust-manager         ready   v0.25.0  ...rc2       ingress-nginx         ready   4.15.1   ...rc2       registry              ready            ...rc2       registry-nodes        ready            ...rc3       kpack                 ready            ...rc3       monitoring            ready   91.4.1   ...rc3       control-plane-db      ready            ...rc4       shpyrd                ready            ...

Endpoints on the default domain:

  • https://shpyrd.127.0.0.1.nip.io — dashboard
  • 10.96.0.50:5000 — the in-cluster registry, inside the cluster only (shpyrd cluster registry shows its state)

Sign in

The installer generated one credential, the admin token, stored as a Secret in the cluster. The CLI uses it through your kubeconfig without you noticing; the dashboard asks for it:

shpyrd cluster dashboard     # opens the dashboard signed in, through a one-time ticketshpyrd cluster token         # prints the token for the "Admin token" field of the sign-in page

For a team, configure the identity provider before inviting people. OSS uses operator-managed Dex static credentials; enterprise installations can configure customer SSO. Sign in once, then grant access to the verified principal. Console access and workspace roles are separate; keep kubeconfig access while setting them up. Core does not create or reset passwords. See Extensions and sign-in and People, teams and roles.

Deploy the example

The repository bundles an example, a Go module with a web and a worker process:

shpyrd projects create hello-worldcd examples/hello && shpyrd deployshpyrd open                              # https://hello-world.127.0.0.1.nip.ioshpyrd secrets set GREETING="Olá mundo"  # new release, the page picks it upshpyrd scale web=3 worker=2shpyrd logs -f
Ports 80 and 443 taken?

shpyrd cluster create --http-port 8080 --https-port 8443 maps other host ports; URLs then carry the port (https://hello-world.127.0.0.1.nip.io:8443).

Install on an existing cluster

The installer works against any kubeconfig context:

shpyrd cluster init --context my-cluster --profile local --domain apps.example.test --yes

--yes is required for contexts that do not look like kind clusters. The local profile assumes ingress-nginx can bind host ports on a node labelled ingress-ready=true and that the service subnet is 10.96.0.0/16 (the registry uses the fixed ClusterIP 10.96.0.50). For a managed Kubernetes cluster use a cloud profile: Oracle Cloud (OKE) or AWS (EKS).

Connect GitHub

Workspaces connect GitHub through one GitHub App per cluster, which the operator registers once. On shpyrd cloud the App is already set up.

shpyrd-ctl github app create --org acme      # or without --org, under your own account

A browser opens on GitHub with the App filled in: its name (shpyrd-<dashboard host>, or --name, at most 34 characters), its webhook at <dashboard>/api/github/webhook, its setup page at <dashboard>/api/github/installed, and the permissions it asks for: contents, metadata, members and statuses read; checks and deployments write. Members lets shpyrd check that the person connecting an organisation owns it. Checks and deployments let shpyrd show each commit's build and release on GitHub, and statuses let it wait for a commit's CI (Checks and Deployments on GitHub). One click creates the App. shpyrd-ctl keeps its credentials in the Secret shpyrd-system/shpyrd-github-app. The App is private unless you pass --public: then any account can install it, not only its owner. A private App registered under a personal account can be installed only on that account: to install it on an organisation, register it with --org (under the organisation), or with --public.

People link their own GitHub accounts through the same App: it asks for user authorization during installation, and its user tokens must expire (GitHub's "Expire user authorization tokens", under Optional features in the App's settings). An App registered before GitHub made that the default may have it off: turn it on, or linking says so. The server keeps the key that encrypts the people's GitHub tokens in the Secret shpyrd-system/shpyrd-token-key, made at its first start. To rotate it, delete the Secret and restart every server replica together; people then link again.

GitHub must reach the dashboard's address for the webhook. The address comes from the cluster's install settings; --url gives another, and the command needs one of them. The command waits ten minutes for GitHub; Ctrl-C stops it.

shpyrd-ctl github app show      # slug, id and page on GitHub; never the keysshpyrd-ctl github app delete    # remove the Secret; then delete the App on GitHub

GitHub Enterprise Server is not supported yet: the App works with github.com.

Upgrading

Install the new CLI and run shpyrd cluster init again with the same context and profile: the recorded decisions (domain, exposure, extensions) are reused, and --only shpyrd limits the run to the platform's own components when nothing else changed. What an upgrade does to running apps:

  • The apps keep serving throughout: the platform's server restarts, the apps do not depend on it at run time.
  • A release that changes what every instance is given (a new platform variable such as REVISION, a new resource model) rolls every app's instances once, one at a time; a single-instance app is unavailable for the seconds its new instance takes to start.
  • A release that changes what builds are made of (the buildpacks, the stack, the run image) makes kpack rebuild every buildpack app; the previous release keeps serving until the new image is ready, and a failed rebuild leaves it serving and marks the project so.
  • A release with a database migration migrates at the server's first start. Take a backup first (shpyrd cluster backup, or pg_dump against the control-plane-db pod). A backup carries the format of the server that made it: an older server refuses a newer backup instead of dropping what it does not know.
  • What a release changes is in its notes on the release page; read them before you upgrade across several versions.
  • Re-applying every component (without --only) restarts ingress-nginx, which is a real interruption of a few seconds at the front door.

Environment profiles

A profile describes the environment the base stack is built for and therefore how load balancing, DNS, TLS and the registry are provided:

localoci (Oracle Cloud)aws (AWS)
Load balancerkind host ports 80/443, or your CaddyOCI flexible load balancer on a reserved address; a private one for internal projectsNetwork Load Balancers with pod targets (AWS Load Balancer Controller): an internet-facing one on Elastic IPs, an internal one for internal projects
DNS*.127.0.0.1.nip.io or dnsmasq (*.shpyrd.test)a wildcard record you create, or a zone in OCI DNS managed by ExternalDNSa zone in Route 53 managed by ExternalDNS (alias records)
TLSdevelopment CA issued by cert-managerLet's Encrypt (one wildcard with a DNS provider); the platform CA for the registryLet's Encrypt (one wildcard through the Route 53 solver); the platform CA for the registry
Registryin-cluster, TLS from the CAin-cluster, TLS from the CA; an Object Storage bucket with --registry-credentials-file, or OCIR with --registry-hostin-cluster, TLS from the CA
Isolationkindnet enforces NetworkPolicyCalico in policy-only modethe VPC CNI's network policy agent
Project volumes and databasesthe node's diskBlock Volume (50 GB minimum, snapshots; disks on the Lower Cost class, databases on Balanced); File Storage for shared volumes (--class shpyrd-fss)EBS gp3 (snapshots); EFS for shared volumes (--class shpyrd-efs)
Platform disksthe node's diskBlock Volume (50 GB minimum)EBS gp3
Object storage (extension object-storage)Garage in the clusterthe S3 gateway in front of one Object Storage bucket (--object-storage-credentials-file), one writerthe S3 gateway in front of one S3 bucket (--object-storage-credentials-file)
Accessthis machineWireGuard instance (profile from Terraform), or the Bastion tunnelAWS Client VPN (profile from Terraform)

On the cloud profiles a volume is a provider block volume: it starts at the provider minimum, grows, has snapshots and follows its process to another node. On the local profile it is on the node's disk: no minimum, no resize, no snapshots, and it stays on that node; project backups protect it. A shared volume needs a class several nodes can mount, so name it when you create it (shpyrd volumes create assets --size 20Gi --shared --class shpyrd-fss). With --object-storage-credentials-file every bucket, Postgres backups included, goes through the S3 gateway to one provider bucket.

The dashboard's cluster page shows the installed profile, and the install record keeps every choice so cluster init re-runs need no flags.

Export the manifests

For GitOps tooling (Flux, Argo CD) the same embedded manifests can be rendered to disk instead of applied:

shpyrd cluster export -o ./gitops --domain apps.example.test

Remove everything

shpyrd cluster destroy                  # deletes the kind clustershpyrd cluster destroy --keep-cluster   # removes the platform, keeps the cluster for a fresh cluster init

Projects, images and configuration live inside the cluster and disappear with it; the development CA under ~/.shpyrd/ca is kept so the next cluster is trusted immediately.

On this page

  • Requirements
  • Install the CLI
  • Create a local cluster
  • Local names and ports
  • Trust the platform CA
  • Check the installation
  • Sign in
  • Deploy the example
  • Install on an existing cluster
  • Connect GitHub
  • Upgrading
  • Environment profiles
  • Export the manifests
  • Remove everything
Back to top
  • AI Community
  • Vibe Coders
  • Developers
  • Businesses
  • FDEs & Implementation Partners
  • Getting Started
  • Pricing
  • Docs
  • Changelog

© 2026. shpyrd. All rights reserved.LegalTerms of ServicePrivacy Policy