• 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. Project
  2. How to contribute
Sign in
Start free

How to contribute

Set up a development environment, find something to work on and send a change.

shpyrd is developed in the open at github.com/shpyrd-io/shpyrd under the MPL-2.0 license. The exception is ee/, the enterprise features: its source is public under the shpyrd Enterprise License, and only the shpyrd team changes it for now, so pull requests there are not accepted. Issues, ideas and pull requests are welcome everywhere else.

Where to start

  • Try it and report. Follow Getting started, or install it on your machine, and open an issue for anything confusing, slow or broken. UX feedback is as valuable as code at this stage.
  • Pick an issue. The issue tracker has bugs and roadmap items. Comment on one before starting so work is not duplicated.
  • Propose a change. Small fixes go straight to a pull request. Anything that changes behaviour or architecture starts as an issue describing the problem and the shape of the change first.
  • Talk. Questions and discussions happen on Discord; the code of conduct applies everywhere.

Development environment

Docker, Go 1.27 and Node.js 24, the version in .nvmrc (nvm use; for the applications, the design library and the website). Run npm install once at the repository root: the applications, design/ui and content/ are one npm workspace. Another Node brings another npm, which writes package-lock.json in another order; npm warns when the version is not 24.

git clone https://github.com/shpyrd-io/shpyrd && cd shpyrdmake cli                      # ./bin/shpyrd and ./bin/shpyrd-ctlmake dev-cluster              # kind cluster with everything except the shpyrd servermake dev-deploy               # build the server image, load it into kind, apply the shpyrd component

make dev-deploy again after changes to the server or the controller.

The dashboard is two applications the server embeds: apps/workspace (a workspace's dashboard) and apps/console (the platform's). Each runs on its own with hot reload - npm run dev against a shpyrd server (SHPYRD_DEV_API names it; see the application's next.config.ts), or npm run design against sample data, with no server at all:

npm --prefix apps/workspace run design   # http://localhost:4325npm --prefix apps/console run design     # http://localhost:4326

How an application is made, and how a design session runs, are in apps/AGENTS.md and design/DESIGN_FOR_AGENT.md.

Useful targets:

make test vet                 # Go tests, the applications' tests, and go vetmake generate                 # regenerate the App CRD and deepcopy code after editing api/make ui                       # build the applications the server embedsnpm --prefix apps/workspace run lint && npm --prefix apps/workspace run test./bin/shpyrd-ctl cluster init --only shpyrd --set SHPYRD_SERVER_IMAGE=shpyrd-server:dev   # re-apply one component

Manifests under deploy/ are embedded in the binaries: rebuild the CLI after editing them.

Conventions

  • Commit messages follow Conventional Commits (feat:, fix:, docs:, chore:) and carry a DCO sign-off (git commit -s).
  • Go code is gofmted and go vet clean; the applications, design/ui and the website are oxlint clean, type-checked and tested (npm run lint, npm run typecheck, npm run test in each).
  • Tests live next to the code: internal/controller (reconciler with a fake client), pkg/api (handlers with fake clients and an httptest Prometheus), pkg/install (every component renders offline).
  • User-facing names follow the concepts: projects, processes, instances, builds, releases, config vars.

Documentation

These pages live in this repository. Each is an MDX file (Markdown with a few named editorial blocks) under content/docs/, and the menu beside them is content/docs/index.mdx; the site that draws them is apps/website (Next, made of design/ui). To preview:

make website-dev              # http://localhost:4324/docs/getting-started

A saved page shows at once. npm --prefix content run test checks that every page is in the menu and every entry of the menu has a page. Besides Markdown, a page can use a few tags: callout, quick-links, chat with message for a conversation with an agent, and agent-setup for the tabs that show how to add shpyrd to each agent.

Support the project

shpyrd is free and open source. If it saves you time, you can support its development with a donation: donate.stripe.com/9B63cxfbwg8H31OgPX2ZO01. Thank you.

On this page

  • Where to start
  • Development environment
  • Conventions
  • Documentation
  • Support the project
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