WWebBuddyMarketplace
Sign in
Pages
Get started

Quick start

Run YourDesk on your own machine in a couple of minutes with no database or keys, then add AI, Postgres and a production build as you need them.

3 min readUpdated Oct 17, 2026Applies to YourDesk 1.0.0

On this page

This gets YourDesk running on your laptop. You need Node.js 22 and npm; nothing else is required for a first look.

1. Install and start

From the project folder you unzipped:

Terminal
npm install
npm run dev

Open http://localhost:8080. The development server always uses port 8080.

On the sign-in page you can:

  • click Log in to demo account to open a filled-in sample studio (Lumen Studio) that is read-only: you can click through everything, but changes are refused, or
  • create your own account at /signup. The first real account on a fresh database becomes the studio owner and the platform admin who can open the Ops console. The demo account never counts as the first account.

To try editing, create your own account. The demo button appears here because this is a local trial: the development server, no DATABASE_URL, opened on localhost or 127.0.0.1. Opened from another address, such as your machine's network IP, it does not appear.

Note

With no DATABASE_URL, the app runs an embedded Postgres (PGLite) stored in ./data. It applies the migrations by itself at startup, and your data survives restarts. Stop the server and delete the data folder to start again from empty.

2. Walk through the basics

After sign-up, a short onboarding asks you to pick a helper character, describe how you work, choose what to do first and pick a proposal look. Then:

  1. Follow the Get started checklist in the sidebar: add a client, create a project, run a discovery, plan your week.
  2. Open a client and copy its portal link into a private browser window to see what a client sees.
  3. Create a proposal, press Send link, and open the copied link to accept it as a client would. A project opens on your desk.

Your desk and the guides after it cover every screen.

3. Turn on the AI (optional)

The Agent and AI drafting use xAI. Create .env.local in the project folder and restart npm run dev:

.env
XAI_API_KEY=xai-...

The development server reads .env and .env.local automatically. You can also skip the file and paste a personal key under Settings → Agent once signed in.

Warning

Do not copy .env.example to .env for a local trial without editing it. Its DATABASE_URL line is a placeholder pointing at a server called host, and the app will try to connect to it instead of using the embedded database. Comment that line out, or set it to a real database.

4. Useful local switches

Variable Effect
YOURDESK_SEED=1 Fills every newly created account with sample clients, projects, invoices and time. Handy while customising; never set it in production.
YOURDESK_DATA_DIR=./somewhere Where the embedded database lives (default ./data).
VITE_AUTH_ENABLED=false Turns sign-in off and uses one shared "Dev User". Only works without DATABASE_URL; with a real database every request is refused instead.

5. Use a real Postgres (optional)

A local Docker container is enough:

Terminal
docker run -d --name yourdesk-db -p 5432:5432 \
  -e POSTGRES_PASSWORD=postgres postgres:16

Add the connection string and a secret to .env.local:

.env
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres
# Generate with: openssl rand -hex 32
BETTER_AUTH_SECRET=paste-the-generated-value-here

The development server does not migrate a real Postgres for you. Apply the schema, then restart:

Terminal
node --env-file=.env.local scripts/migrate.mjs
npm run dev

With DATABASE_URL set, the demo button disappears (unless YOURDESK_DEMO=1), and the first account you create on this database becomes its platform admin.

6. Try a production build (optional)

Terminal
npm run build:node
PORT=8080 node --env-file=.env.local .output/server/index.mjs

Leave out --env-file=.env.local if you have not created that file; Node refuses to start when the named file is missing.

Two things differ from the development server:

  • npm start and node .output/server/index.mjs do not read .env files. Pass --env-file or export the variables.
  • Without PORT, the built server listens on 3000, not 8080.
  • The demo button does not appear in a production build unless YOURDESK_DEMO=1 is set.

npm run build:node also runs the migration runner at the end, but that step only sees DATABASE_URL if it is exported in your shell; otherwise it prints DATABASE_URL not set — skipping.

Next steps