Getting started

This guide gets Dirework running on your own machine so you can try it before you deploy it anywhere. Going to production instead? Jump to Deployment.

No deep tech knowledge needed. You'll copy a few commands, paste two Twitch keys, and you're done. Take it one step at a time — each step says exactly what to do.

What you need first

Install these once. Click each name if you don't have it yet:

Bun — the toolkit that runs everything (one install command on their site)
Node.js — version 22 or newer
A free Twitch developer application — this is where your two keys come from

That's the whole shopping list. No Docker, no database to install — a local database is created for you automatically.

1. Get the code

git clone https://github.com/mrdemonwolf/dirework.git
cd dirework

2. Install

bun install

3. Create your `.env` file

cp .env.example packages/infra/.env

Open packages/infra/.env and fill in three values:

TWITCH_CLIENT_ID="paste_your_client_id"
TWITCH_CLIENT_SECRET="paste_your_client_secret"
BETTER_AUTH_SECRET="paste_a_generated_secret"

Generate the BETTER_AUTH_SECRET with one command:

openssl rand -base64 32

Don't have the Twitch keys yet? The Twitch integration setup page walks you through getting them — it takes about two minutes. For local use, add both of these redirect URLs to your Twitch app:

http://localhost:3001/api/auth/callback/twitch
http://localhost:3001/api/bot/callback/twitch

Everything else in the .env file already has a sensible default for local use. You don't need to touch it.

4. Start it up

bun run dev

This starts everything at once:

The API → http://localhost:3000 (works behind the scenes)
Your Dirework app → http://localhost:3001
This documentation → http://localhost:4000
A local database — created automatically, with all tables set up for you

✅ You should now see the Dirework welcome screen at localhost:3001.

First start taking a moment? That's the local database being created and the apps compiling. It's much faster after the first run.

5. Claim your instance

The first time you open the app, it sends you to a setup screen. Click Claim with Twitch and sign in. That makes you the owner — one streamer, one instance.

✅ After signing in you land on your dashboard. You're in.

The setup screen only appears once. After you claim the instance, it turns off for good.

Working on the UI and don't want to sign in with Twitch every time? Set both DEV_LOGIN="true" and NEXT_PUBLIC_DEV_LOGIN="true" in your .env, restart bun run dev, and a Dev bypass login button appears on the welcome/setup screen. It signs you straight in as the owner — no Twitch round-trip.

Local development only. Leave both unset in production — with DEV_LOGIN off the bypass endpoint does not exist, and the button never appears. They are not part of the deploy configuration.

Where to go next

Connect your bot account so chat commands work
Add the overlays to OBS — the timer and task list
Learn the chat commands your viewers will use
Make it your own in the Theme Center
Ready for the world? Deploy to production

Handy commands

You'll mostly use bun run dev. These are here when you need them:

Command	What it does
`bun run dev`	Start the API, the web app, the docs, and the local database together
`bun run dev:web`	Start only the web app (standalone, port 3001)
`bun run check-types`	Check the code for TypeScript errors
`bun run test`	Run the unit tests
`bun run db:generate`	Create a new database migration after schema changes
`bun run deploy`	Deploy to Cloudflare from your machine (see Deployment)
`bun run destroy`	Tear a Cloudflare deployment back down