orbit

> Self-hosting status: Preview. The repository supports local evaluation,

> but it is not yet a supported production release. Review the current

> limitations in the readiness tracker.

Why Orbit exists

A task manager costs around 18 dollars per person per month. For a team of

twenty that is over four thousand dollars a year to keep a list of tasks in

order.

The alternatives were not a real answer. The free ones are slow and feel like

filling in a form. The self-hosted ones are heavy to run. The cheap ones are

cheap for a reason, and every one of them eventually asks for a card.

So we built the task manager we wanted, made it free and open-sourced it. Not free-with-an-asterisk,

not free-for-three-users, not free-until-we-raise. There is no billing code in

this repository and there is no plan to add any.

Orbit is sponsored by Noveum AI, who pay for the hosted

instance and the engineering time. Everything is Apache-2.0, so you can run it

yourself and never depend on us at all.

Screenshots

Issues, as a fast list or a board. Every property changes from the keyboard.

Command palette. Cmd K, then go anywhere or do anything.

Sprints with scope, points, burndown and carryover.

Docs with a rich editor, living beside the issues they describe.

HTML pages as one self-contained file, with a live preview and their own URL.

Source, split, or preview. CSS and script stay in the file.

Standup: the whole workspace as a Kanban, filtered to one person with a click.

Analytics: scope, throughput, churn and distributions.

More in `docs/assets/screenshots`, every screen in both themes.

What it does

Quick start

You need Bun 1.3 or newer and Docker. That is the whole list.

git clone https://github.com/Noveum/orbit.git
cd orbit

bun install
cp .env.example .env

bun run infra:up        # postgres, redis and minio
bun run db:push         # create the schema
bun run db:test-setup   # create the test databases
bun run db:seed         # load a demo workspace

bun run dev             # http://localhost:3000

Sign in as `alex@orbit.example`. The seed loads three teams, seven people,

thirty two issues, projects, sprints and docs, so there is something to click on

straight away.

Then press Cmd K, and open a second tab and change

something in one to watch the other update.

Full walkthrough in docs/getting-started.md.

Reference deployment (Preview)

The setup below describes the Noveum AI deployment profile. It is not a

provider-neutral production support commitment.

Orbit is one Next.js app. It needs Postgres, Redis and an S3-compatible bucket,

all of which have free tiers, so a small team can run it for nothing.

The button prompts for Resend so a fresh deployment can send sign-in codes. You

can instead configure password, Google or GitHub sign-in. Production refuses to

build or start without one complete method; see Authentication.

Two things that are not optional and produce confusing failures if you get them

wrong:

• Root directory is `apps/web`, and functions run on node. Do not set

`bunVersion` in `apps/web/vercel.json`. It moves every function to the Bun

runtime, where the websocket upgrade at `/api/ws` silently never happens and

the browser retries forever against a socket that never opens.

• Never set `NEXT_PUBLIC_REALTIME_URL` in production. The socket is served

from the page's own origin, and Orbit ignores this variable in production.

Leaving it set only makes the deployment configuration misleading.

Supabase for Postgres, Upstash for Redis, Cloudflare R2 for files and Resend for

email is the combination we run. Other providers have not yet been certified by

this project.

Full guide, including running it on your own server behind nginx:

docs/self-hosting.md.

For AI agents

Orbit ships an MCP server, so Claude, Cursor, VS Code or anything else that

speaks MCP can read your board and do work in it.

claude mcp add --transport http orbit https://orbit.example.com/mcp

OAuth only, no API keys. You pick the workspace, re-verify a passkey and approve

the scopes, and the grant is revocable from settings. **An agent never has more

permission than the person who authorised it**, because the tools run through

the same policy as everything else. A token with only `orbit.read` is not shown

the write tools at all.

Sixty odd tools covering issues, sprints, projects and docs. Things that work

today:

> "What is blocking the Realtime Sync Engine project?"

>

> "File a bug on Engineering: passkey sign-in fails on Safari when no credential

> is registered. High priority, assign it to me."

>

> "Summarise what each person closed yesterday."

docs/mcp.md has the setup and the full tool list.

Documentation

How it is built

apps/web                  Next.js 16: UI, REST handlers, auth, /api/ws, /mcp
apps/realtime             Websocket host, local development only, never deployed
packages/realtime-server  Connection hub: tickets, scopes, presence, Redis fan-out
packages/realtime-client  Browser client: subscribe, patch, reconnect
packages/mcp-server       MCP tools and the handler behind /mcp
packages/core             Domain operations shared by REST, MCP and the hub
packages/services         Markdown, storage, email, notifications, Slack, GitHub
packages/db               Drizzle schema, migrations, client, seed
packages/shared           Zod validators, domain types, event contracts, policy

TypeScript throughout, in strict mode with `any` as a lint error. Next.js 16 and

React 19. Postgres through Drizzle. Redis for realtime fan-out. Bun as the

toolchain, node as the runtime, because a Vercel function can only upgrade a

websocket on node.

A change writes to Postgres, bumps a monotonic `sync_id`, publishes to Redis,

and the hub fans it out to the connections whose scope entitles them to see it.

The client patches its cache rather than refetching, so your scroll position and

selection survive. docs/architecture.md has the detail.

Contributing

Contributions are wanted, and not only code. Docs, bug reports, translations,

accessibility and design all count.

bun run verify   # lint, comment policy, types, tests. The same four CI runs

Good places to start:

• **Good first issues**, scoped small with the file paths written into the description
• **Help wanted**, everything we would like a hand with
• **The roadmap**, for the bigger pieces

A few house rules that will otherwise surprise you in review: Bun only, no

npm or pnpm. No comments in code, the build fails on them, so put the

meaning in names and the prose in the pull request. No `any`, no non-null

assertions. No em-dashes. And a feature is not done until it has a test that

would fail if the feature broke.

Full guide in CONTRIBUTING.md. The repository carries its own

context files, `CLAUDE.md` and `AGENTS.md`, so your

editor picks up the conventions without you explaining them each time.

Contributors

Your face goes here. Genuinely, even for a typo fix.

Community

• **Discussions** for questions and ideas
• **Issues** for bugs and concrete work
• **Security** for anything that should not be public

If Orbit is useful to you, a star helps other people find it.

Sponsor

Noveum AI builds evaluation and observability tooling for AI

systems, and pays for Orbit's hosting and engineering time. Orbit is not a

funnel for it. There is no upsell, no "contact sales" and no gated feature. We

needed a task manager, we could not find a free one that was good, so we built one

and gave it away.

License

Apache License 2.0. Use it, run it, change it, ship it, commercially

or otherwise. The patent grant protects you, and the NOTICE asks only

that a public fork picks its own name so nobody confuses your build with this

one.