• 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. Extensions and sign-in
Sign in
Start free

Extensions and sign-in

Optional capabilities switched on per cluster, and how people sign in to the dashboard with their own accounts.

On shpyrd cloud the platform is run for you and every capability on this page is on: see Getting started. This page is for the operator of a cluster you run yourself. shpyrd keeps its core small and adds optional capabilities as extensions, Go packages compiled into the binaries and switched on per cluster. The first one gives the dashboard real user accounts.

Extensions

shpyrd-ctl extensions listshpyrd-ctl extensions enable auth-localshpyrd-ctl extensions disable auth-local --yes
NAME            STATUS    COMPONENT                        DESCRIPTIONauth-local  enabled  dex  Bundled Dex identity broker; optional operator-managed static credentialslogs-agent      enabled   logs-agent                       Vector log agent: collects container logs from all project pods, labels them project/process/instance, feeds drains (RFC-0022a)postgres        enabled   cnpg, barman-cloud, pg-gateway   PostgreSQL databases for projects (CloudNativePG), attached to apps as DATABASE_URL (shpyrd pg create)redis           enabled   -                                Redis-compatible caches and queues for projects (Valkey or Redis), attached to apps as REDIS_URL (shpyrd redis create)object-storage  enabled   object-storage                   S3-compatible storage through the cloud gateway or local Garage with a key per consumer: the backing store for Postgres backups and platform backups (RFC-0046)mail            enabled   -                                Send email from the platform: invitations and notifications over SMTP (shpyrd-ctl mail set)sleep           disabled  keda, keda-http                  Scale web processes to zero after a quiet period and wake them on the first request: KEDA and its HTTP add-on (shpyrd sleep)autoscale       disabled  keda, metrics-server, keda-http  Let a web process follow its load between a minimum and a maximum of instances: KEDA, its HTTP add-on and the Metrics Server (shpyrd autoscale)opencost        disabled  opencost                         Infrastructure cost allocation via OpenCost (RFC-0075)

shpyrd extensions answers too when a kubeconfig is at hand. Enabling installs the extension's component with the same runlevel installer as the base stack (ordering, readiness waits, install record) and restarts the server with the extension; the choice is recorded in the cluster, so shpyrd-ctl cluster init and shpyrd-ctl cluster status keep it. Disabling removes the component and is refused while resources of the extension still exist. The console's Components page lists every extension with its state.

Extensions contribute an installer component, resource types with controllers, API routes, CLI commands and login providers through a few small Go interfaces. Databases (Postgres, Redis), object storage and the log agent are extensions. Shared volumes are not: they come from the profile.

Enterprise features

Some features are the enterprise's: sign-in through GitHub, Google, Microsoft or any OpenID Connect provider, auto sleep, costs and cost drains, and the MCP server. Their source is public, in ee/ of the repository, under the shpyrd Enterprise License; they are built into the released binaries and switch on with a license: shpyrd-ctl license set <file>, shown on the console's Settings page. A license switches them all on until its expiry date, and off on that day. One bought from shpyrd renews online: a week before it expires the cluster sends it back, with the last 30 days of what it used and cost (summed, nothing per project), and installs the next one; the console's Settings › License shows the last renewal and opens your billing account. Without one the platform runs with email and password sign-in, and without sleep, costs or MCP. On shpyrd cloud they are always on. The costs feature reads its numbers from the opencost extension above.

Object storage

shpyrd-ctl extensions enable object-storage gives the platform an S3-compatible store: the working store for what needs durable objects — Postgres backups and, on the gateway, the uploaded sources and (unless they are given buckets of their own) the platform backups and the registry — and the buckets a project makes for its app's files. It takes one of two forms:

  • The S3 gateway, on shpyrd cloud and on a cluster you run that was installed with --object-storage-credentials-file. One bucket at the cloud provider holds everything; the gateway in front of it (object-gateway in shpyrd-system) gives each consumer a bucket of its own inside it. The Terraform roots write the credential file: contrib/oci/terraform/backups (<name>-objects.env) and contrib/aws/terraform/object-storage. The data lives outside the cluster and survives it. On Oracle Cloud the gateway runs as a single pod: OCI's S3 API ignores If-Match, so one process writes the gateway's records (SHPYRD_GATEWAY_SINGLE_WRITER=true, SHPYRD_GATEWAY_REPLICAS=1, set by the oci profile). On AWS it runs two.
  • Garage in the cluster, without the gateway (a local cluster): Garage, one node on the profile's block storage class, SHPYRD_OBJECT_STORAGE_SIZE: 20Gi locally and on AWS, 50Gi on Oracle Cloud. Its data goes with the cluster.

Every consumer gets a bucket and a key that opens only that bucket: an ObjectBucket resource in its namespace produces a bucket and a Secret <name>-object-storage next to it (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL, BUCKET). The bucket is shpyrd-<namespace>-<name> on Garage, and shpyrd- plus a hash of the namespace and name on the gateway. A key from one project cannot list or read another project's bucket. Optional retention (retentionDays) expires old objects; deletionPolicy: Retain keeps the bucket's contents when the resource goes.

The console's Storage page shows the store and every bucket with its size and object count; shpyrd-ctl object-storage list prints the same. The store speaks plain HTTP inside the cluster. On the gateway the projects' buckets go through a listener of their own (port 3901, signing with us-east-1; the platform's consumers keep port 3900 and garage), capped and rate-limited per bucket, and reachable from outside the cluster through one TLS host, SHPYRD_BUCKETS_HOST (buckets.<domain> unless the operator names another), for presigned addresses and public objects. More on the gateway, and on moving an existing cluster to it, is in contrib/object-storage.md in the repository.

Email

The mail extension gives the platform one SMTP sender, used for invitations and, later, notifications. It has no component of its own: the settings live in the Secret shpyrd-mail of the system namespace, written by the operator and read again every thirty seconds, so a change needs no restart.

shpyrd-ctl extensions enable mailshpyrd-ctl mail set --host smtp.example.com --user postmaster@example.com \    --password @/path/to/password --from "shpyrd <noreply@example.com>"shpyrd-ctl mail statusshpyrd-ctl mail test you@example.com

STARTTLS on port 587 is the default; --tls speaks TLS from the first byte (port 465); --plain is for a relay on a private network only — credentials are never sent unencrypted anywhere else. PLAIN and LOGIN authentication are supported. The test message is sent by the server from inside the cluster, so it proves the settings, the network path and the sender address at once; the console's Email page shows the status and sends the same test. Deliveries to one address are rate limited (five in ten minutes), and every test and failure is in the audit trail. Without a sender, invitations show their link to whoever invites, to pass along.

Any SMTP relay works, and the two kinds differ in one thing. A commercial provider (Mailgun, SES, Postmark, Resend...) keeps a suppression list per sending domain on every plan: addresses that bounced, complained or unsubscribed are refused from then on, over SMTP as much as over its API, and the list is yours to edit in its panel. A relay of your own does not, and the platform keeps no such list either: its volume is invitations and alerts to people an administrator named, and the rate limit above is the only guard. Either way the platform learns only what the relay answers during delivery; a failure the relay discovers later is in the provider's log, not in the audit trail.

Signing in with an account

The auth-local extension installs the bundled Dex OIDC broker:

shpyrd-ctl extensions enable auth-local

For OSS, configure Dex staticPasswords with bcrypt hashes and stable userID values. Credentials are entered on Dex, not in a workspace password form. Core has no user/password CRUD commands or reset/set-password endpoints. Cloud uses Accounts or customer SSO; MFA, passkeys and recovery belong to that IdP. See Accounts and authentication.

The CLI uses workspace sign-in (shpyrd login), with authorization and revocation owned by the workspace. shpyrd-ctl uses operator kubeconfig access.

Company identity providers

Anyone with an identity provider that speaks OpenID Connect (Okta, Auth0, Keycloak, Microsoft Entra, Google Workspace...) connects it to shpyrd as a connector of the bundled issuer of auth-local, and so do GitHub, Google and Microsoft. These are enterprise features: on with a license, always on shpyrd cloud. Every provider becomes a button on the sign-in page. Since v0.9.15 each workspace can add methods of its own on its Sign-in tab (shpyrd sso add), shown on that workspace's login page only — see Your company's sign-in. Identities are bound by trusted issuer and subject, not merged by matching email. Provider groups can map to workspace teams; permissions reference stable principals.

GitHub, Google, Microsoft and OpenID Connect through Dex

All four go through Dex (the auth-local extension must be enabled) and are configured with one command — or from the dashboard's Workspace › Sign-in tab — that writes a Dex connector; the button appears on the sign-in page at once.

shpyrd-ctl auth connector add github --client-id ... --client-secret "$GITHUB_CLIENT_SECRET" --org acmeshpyrd-ctl auth connector add google --client-id ... --client-secret "$GOOGLE_CLIENT_SECRET" --hosted-domain acme.comshpyrd-ctl auth connector add microsoft --client-id ... --client-secret "$MS_CLIENT_SECRET" --tenant acme.comshpyrd-ctl auth connector add oidc --id okta --issuer https://acme.okta.com --client-id ... --client-secret "$OKTA_CLIENT_SECRET" --label Oktashpyrd-ctl auth connector listshpyrd-ctl auth connector remove github

--client-secret also takes @path to read the secret from a file. --realm says whose login page shows the button: platform (the default: the methods every workspace offers) or console (the operator's own door). --tenant limits Microsoft sign-in to one Entra tenant (id or domain); without it any work or school account may sign in. The oidc connector takes any issuer (Okta, Keycloak, Auth0, Authelia) and asks for the groups scope, so the provider's groups map to teams.

The callback URL to register at every provider is https://auth.<domain>/callback (the command prints it).

At GitHub: Settings › Developer settings › OAuth Apps › New OAuth App, with that callback URL. --org limits sign-in to members of one organisation and makes its teams available as groups named org:team-slug (--group acme:platform on a Team); without it, everyone with a GitHub account may sign in and all their teams come along. GitHub must have a verified email on the account.

At Google: an OAuth client id of type Web application in the Google Cloud console, same callback URL; --hosted-domain limits sign-in to one Workspace domain. Google groups need a service account and are not configured by shpyrd.

At Okta: Applications › Create App Integration › OIDC - OpenID Connect, Web Application; grant type Authorization Code; the callback URL above as the sign-in redirect URI; leave DPoP off. The issuer is the org URL (https://acme.okta.com, not -admin). For groups, set a groups claim on the application (Sign On › OpenID Connect ID Token › Edit › Groups claim type Filter, groups Matches regex .*). Group names are matched exactly as the provider sends them (Okta sends names, Microsoft Entra sends object ids): shpyrd teams create platform --platform-role platform-admin --group "DevOps admin".

Local cluster note

The kind cluster serves auth.127.0.0.1.nip.io with the development CA, so run shpyrd-ctl cluster trust-ca once or the server will not trust the issuer. On other hosts, shpyrd-ctl cluster init --domain decides the hostname.

Who may join, and company domains

Two workspace settings decide what happens when someone signs in (dashboard: Workspace › Sign-in):

  • Who may join — anyone who can sign in (the default: whoever passes one of the methods becomes a person of the workspace, with no roles until granted), only accounts of a claimed domain (new people join only through a verified company domain), or only people already listed (an administrator invited them, gave them a workspace role, or listed their email in a team or a grant first). An invitation lets someone in under every policy. People who already signed in keep their access whatever the policy.
  • Company domains — claim acme.com by publishing the DNS TXT record the page shows (_shpyrd-verify.acme.com) and pressing Verify. Accounts of a verified domain count as the company's people; choose a sign-in method for the domain and @acme.com accounts can only come through it — nobody signs in as ceo@acme.com with a password they made up elsewhere.

Every person who signs in belongs to the built-in everyone team (shpyrd members add intranet --team everyone --role user opens an app to the whole company), and the People tab of the Workspace page can suspend someone: their access ends at once, everywhere, until reactivated.

On this page

  • Extensions
  • Enterprise features
  • Object storage
  • Email
  • Signing in with an account
  • Company identity providers
  • GitHub, Google, Microsoft and OpenID Connect through Dex
  • Who may join, and company domains
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