gorbital

Go APIs, ready for orbit.

Website · Documentation · Quickstart · Changelog · Roadmap

gorbital is a Go library and a CLI, orb, that write a production API into your repository: PostgreSQL, sign-in with 2FA and passkeys, API keys, organisations, background jobs, email, feature flags, audit logs, observability and ops endpoints. The code it writes is plain Go that you read, change and own. Sign-in and organisations are written into your repository too, so you can read how every flow works; the primitives they call, such as password hashing, session tokens and OAuth verification, stay in the library, so fixes to those reach you with go get.

Your app keeps building if you uninstall orb.

Status

v0.3.2 is the current release, published on 2026-09-22. v0.1.0 was the first public one; everything in the roadmap marked done is in the current release, and every change is in the changelog. Do not use v0.3.0: it is retracted and does not build outside this repository, and go get says so. v0.3.2 is the same code as v0.3.1 with every module requiring the version it ships with.

v0 carries no compatibility promise: a minor release may change the API, and when it does, the changelog and upgrade notes say what to do. The compatibility checks already run on every change. v1.0.0 freezes the API and starts the scaffold compatibility promise, and it ships only after the external security review signs off (stability).

Install

You need Go 1.26 or later and Docker.

go install gorbital.dev/cli/cmd/orb@latest

orb goes into $(go env GOPATH)/bin. If your shell says command not found: orb, add that directory to your PATH and open a new terminal.

To use the library without the CLI:

go get gorbital.dev@latest

Quickstart

orb new my-api --preset full --scope single
cd my-api
orb dev

orb dev starts PostgreSQL and a mail catcher in Docker, runs migrations and seed data, then starts your API and the Dev Portal. It prints the seeded administrator's password and 2FA key once. In a terminal, orb new starts orb dev for you.

The Quickstart walks through it with the real output. If something goes wrong, see Troubleshooting.

What it decided for you

• Plain Go. Standard net/http and log/slog, constructors instead of a DI container, no reflection wiring. You give up the conveniences of a heavier framework.
• PostgreSQL only. Jobs, sessions, rate limits, settings and audit logs live there too. There's no Redis, Kafka or SaaS to run. No MySQL, no SQLite: if that rules you out, it rules you out.
• You own the code. A layered structure with one folder per domain module. orb upgrade merges template changes on a branch and never overwrites your edits silently. You also maintain what's generated.
• Three layers, and only the first is ours. Argon2id passwords, session tokens, OAuth, TOTP and passkeys are versioned library packages, and no command moves them into your app: that is the one place a small change is a security hole you cannot see. The sign-in and organisation flows are written into internal/modules/auth and internal/modules/orgs, where you read and change them. What a role means, what a tenant is and who may do what are yours alone, and are not in the library at all. orb doctor --security tells you when a flow you own has a fix waiting upstream.
• Your tenant, your word. Tenancy is a contract you fill in — its name, its path parameter, its ID format, its roles — so your API says /v1/merchants/{merchantId}/orders and refuses with merchant_not_found. The framework never learns your table names and never queries them. Organisations are the implementation we supply, not the model you inherit.
• Operations from day one. Health and readiness checks, OpenTelemetry, Prometheus metrics, runtime settings, feature flags, maintenance mode, incidents and an ops API guarded by roles and 2FA.

Presets

orb new shop-api    --auth basic --scope merchant     # password sign-in, merchants own the data
orb new catalog-api --auth none  --scope none         # a public API: no users, no auth tables
orb new club-api    --auth basic --scope custom       # your own membership rules from commit one
orb new saas-api    --auth full  --scope organisation # everything

--auth decides how much sign-in a Full app gets: none (no users, no auth tables), basic (email and password, sessions, operators — 29 endpoints) or full (and 2FA, passkeys, Google, Apple, GitHub, API keys and service accounts — 74).

--scope decides what owns the data: none, single (users), custom (your tables and your rules), or a name of your own, which mounts organisations under that word with members, invitations and optional row-level security.

Modules

The root module holds the small core. Everything that brings a dependency is its own module, so your app only downloads what it uses. All modules share one version.

API reference for every package: pkg.go.dev/gorbital.dev.

Documentation

• Start: What you need, Quickstart, Your first resource, Concepts
• Build a whole app: Build an app, twenty-three chapters that write Plateful, a restaurant platform, from orb new to deployment
• Sign-in: Overview, Every key and credential
• Own your model: Tenancy, Access control, Resource access, The code in your repo
• Build and run: Architecture, Life of a request, Environment variables, Testing, Running in production
• Keep up to date: Upgrading, Upgrade notes, Stability
• Why it's built this way: Decision records, Roadmap

Everything is also at docs.gorbital.dev. The full index is docs/README.md.

Contributing

Read CONTRIBUTING.md before opening a pull request. Larger changes start with a decision record. GOVERNANCE.md explains who decides, and the Code of Conduct applies everywhere.

Security

Don't report vulnerabilities in public issues. SECURITY.md says how to report them privately and which versions get fixes. The threat model and internal security review are public.

License

gorbital is licensed under the Apache License 2.0. See NOTICE.

gorbital is provided "as is", without warranty of any kind, express or implied, including the warranties of merchantability, fitness for a particular purpose and non-infringement. You are responsible for deciding whether it suits your use, including production, security-sensitive and regulated workloads. In no event shall the authors, contributors or copyright holders be liable for any claim, damages or other liability arising from the software or its use. The License's Sections 7 and 8 govern.