Problem. A job search runs through find, qualify, apply, research, interview prep and debrief, and each job needs its own documents and next action along the way.
Idea. One self-hostable app tracks every job through seven stages from Saved to Offer. AI is an optional layer that reads postings and scores fit against the user's preferences.
Built. A Next.js 16 and React 19 app on Postgres with Drizzle and Better Auth: a board, companies, job pages with research, document and prep tabs, and a jobsmith command line to pull and push markdown documents. Live at https://jobsmith-lemon.vercel.app. 186 commits on 17 days, Sep 18 to Oct 25, 2026.
Decision. AI stays off unless AI_PROVIDER is set on purpose, instead of switching on whenever an ANTHROPIC_API_KEY is found in the shell. A key left over from another project then never sends a posting anywhere by accident.
Jobsmith is one app for a whole job search: find, qualify and research, apply, research deeper and prepare for each interview stage, debrief. It is open source under AGPL-3.0 and self-hostable with your own database and, later, your own AI provider key.
Captured from a local run with the fictional seed data (pnpm seed), not from a deployment. To
reproduce: docker compose up -d, pnpm install, pnpm db:migrate, pnpm seed, pnpm dev, then
sign in as the seeded demo user.
Next.js 16 and React 19 with Tailwind CSS 4, Postgres through Drizzle ORM, Better Auth for sign-in, and
the Vercel AI SDK for the optional AI features (package.json).
Pages: /board (jobs by stage), /companies, /jobs/<slug> (one job), /settings, and / (Home).
/preferences holds the filters that new jobs are checked against. /library is a placeholder until interview prep lands. Without a session, every page
redirects to /login, except /setup and /login themselves.
- Node.js 24 (see
.nvmrc) - pnpm
- Docker, for the local Postgres in
docker-compose.yml
cp .env.example .envFill in .env:
DATABASE_URL: leave the default if you usedocker-compose.yml.BETTER_AUTH_SECRET: generate one withopenssl rand -base64 32.APP_URL: required for local development and self-hosting. Usehttp://localhost:3000here. On Vercel it can be left unset for Preview, and for Production unless a custom domain is used, because the app derives it from Vercel's system environment variables.SETUP_TOKEN: generate one withopenssl rand -base64 24(at least 16 characters). Until the first account exists, the setup page asks for this token, so only someone who can read the deployment's environment can create that account. A production build with noSETUP_TOKENkeeps first-run setup locked. Local development (pnpm dev) works without it.
Set SETUP_TOKEN before you deploy an instance that the internet can
reach.
The database scripts (db:migrate, seed, reset-db) load .env
themselves when the file exists, the same way next dev does. Then:
docker compose up -d
pnpm install
pnpm db:migrate
pnpm devOpen http://localhost:3000. The first visit redirects to /setup, which
creates the only account this instance will accept until you set
ALLOW_SIGNUP=true.
Click "Add job" on the board. Paste a link to the posting, paste the posting text, or both, next to the company and role fields it already had. Company and role are optional when a link or text is given; Jobsmith fills them in when it can read the posting.
A Greenhouse, Ashby or Lever link is read straight from that vendor's own public API. Any other link is fetched and read as a web page. LinkedIn is not read: paste the posting text instead, since LinkedIn requires a login Jobsmith does not have. A link that cannot be read for another reason (blocked, timed out, too large, not found, too short, or simply unreadable) asks for the pasted text too, unless company and role are already typed, in which case the job saves with the link alone.
When an AI provider is configured (below), pasted or fetched text is sent to it to read the company, role, location, work mode and pay. Only the posting text is sent, inside a fixed wrapper that tells the model to treat it as data, never instructions; nothing about your account goes with it. The stored posting itself is never rewritten by the model: it stays the pasted text or the fetched page, turned into plain markdown. When the model is off, fails, or cannot find the company and role, the dialog asks for them directly and the job is saved with a "Check this job's details" notice on its page, cleared by editing the details or by "Mark as checked."
Adding the same company, role and location again while the first one is still active shows "You already have this job." with a link to open it, and "Add anyway" to add a second copy.
"Where is it now" defaults to Saved. The job is always created with all seven stages. Choosing Applied moves it there once. Choosing a column after Applied moves it to Applied first and then to the chosen column, so its history shows two moves, unlike the single drag you would get from adding it plain and moving the card afterward.
Jobsmith works with no AI configured; intake then asks for the company and role by hand, and jobs
get no fit score (the hard filters from Preferences still run, in code). With AI on, each job added
with a posting is scored after it is saved: the posting, your resume and headline from Settings,
and your Preferences go to the model, cut to fixed lengths, and none of that text is ever logged.
Four environment variables turn it on, read in .env.example:
AI_PROVIDER:gateway(Vercel AI Gateway),anthropic(the Anthropic API directly), orfake(the test suite's own stand-in, which never sends text anywhere). Unset means AI stays off.AI_GATEWAY_API_KEY: needed forgateway, except on Vercel, where the project's own OIDC token is used instead.ANTHROPIC_API_KEY: needed foranthropic.AI_MODEL: optional, overrides the provider's default model.
AI_PROVIDER has to be set on purpose: a developer's own shell ANTHROPIC_API_KEY, left over from
another project, must never send a posting anywhere by accident. Every call to the Vercel AI Gateway
asks for zero data retention.
Focus a card (its title is a link, reached by Tab in the normal reading
order) and press a digit 1 to 7 to move it straight to that column, or
c to close it and choose a reason. Every card also has a "Move to" menu
listing the same seven columns and a Close item, for a mouse or a screen
reader user who would rather not remember the numbers. A move that
succeeds is confirmed out loud through a screen reader (a visually hidden
live region); a move the server refuses shows why in a toast and leaves
the card where it was.
Below 768px wide the board is a list grouped by stage instead of columns; each row's "Move to" button opens the same seven choices in a sheet.
Every document on a job's Research, Documents and Prep tabs is markdown, and the jobsmith command
line is the way to get a whole folder of it in, and a fresh copy of a job's own context out, without
opening the app.
Build it once from the repo, then install it globally:
pnpm cli:build
npm install -g ./clipnpm cli:build bundles cli/src into one dependency-free file, cli/dist/jobsmith.mjs (Node 20 or
newer); npm install -g ./cli links the jobsmith command from cli/package.json's own bin entry.
There is no published package yet - reinstall the same way after pulling a newer commit.
jobsmith login --url <base-url> asks for a token (paste it; it is read from standard input and
never echoed on a real terminal) and saves both to ~/.config/jobsmith/config.json (or
$XDG_CONFIG_HOME/jobsmith/config.json, owner-only permissions). Create a token first, in Settings.
Setting JOBSMITH_URL and JOBSMITH_TOKEN in the environment overrides the saved login, for
either variable on its own or both together.
jobsmith list prints your active jobs and their slugs.
jobsmith pull <slug> [--out <dir>] writes <slug>-context.md: the posting, stages, people, a
preferences summary and an index of existing documents, as one markdown file with frontmatter.
jobsmith push <slug> [--dir <dir>] [--prefix <file-prefix>] [--dry-run] reads every
<prefix>-*.md file in --dir (default the current directory; the prefix defaults to the slug),
skips anything that looks like a document already pulled from this app, and uploads the rest. For
each file:
-
The key is the file name with the prefix and
.mdremoved, lowercased. -
Kind, stage, title and scope come from the file's own frontmatter first (
kind: cv,stage: Hiring manager,title: ...,scope: company), then from a suffix map - built in for the common names, or overridden per content folder by ajobsmith.config.jsonnext to the files:{ "suffixes": { "call-card": { "stage": "Hiring manager" } } }A suffix with no match anywhere is still pushed, as kind
other, with a note. Frontmatter is stripped before upload either way. -
A file over 1 MiB stops the push before anything is sent; a push holds at most 50 documents and 4 MB in total, and the CLI splits a larger folder into more than one request on its own.
--dry-run asks the server what would happen and prints it without saving anything. Pushing the
same folder twice is always safe: unchanged content reports unchanged and changes nothing.
Credentials live in a different file from the suffix map on purpose: one is per machine
(~/.config/jobsmith/config.json), the other is per content folder (jobsmith.config.json, next to
the markdown files themselves, so a folder synced between machines carries its own mapping with it).
Every route below needs Authorization: Bearer <token>, a token created in Settings. The bridge
never accepts a session cookie, and the app's own pages never accept a bearer token - the two
authentication paths stay completely separate. Every response carries x-request-id and
cache-control: no-store; there are no CORS headers, so a browser calling this from another origin
is refused by its own preflight check before the request reaches the server at all.
| Method | Path | Purpose |
|---|---|---|
GET |
/api/bridge/opportunities?status=active|closed|all |
List your jobs (slug, company, role, current stage). status defaults to active. |
GET |
/api/bridge/opportunities/:slug/context |
The job's context document, as text/markdown. |
PUT |
/api/bridge/opportunities/:slug/artifacts |
Upsert up to 50 documents; add ?dry_run=true to preview with nothing saved. |
The push body:
{
"artifacts": [
{ "key": "cv", "kind": "cv", "title": "CV", "scope": "opportunity", "stage": "Hiring manager", "body_md": "# CV\n..." }
]
}title, scope and stage are all optional (scope defaults to opportunity; a missing stage
leaves the document unstaged). stage is matched against the job's own stage labels first, then
against stage kinds, case-insensitively. Each body_md is capped at 1 MiB, the whole request body at
4 MB.
The response:
{
"dryRun": false,
"results": [{ "key": "cv", "scope": "opportunity", "status": "created", "version": 1 }],
"warnings": [],
"requestId": "..."
}status is one of created, versioned, updated or unchanged. A per-document problem (an
unknown kind, a stage that does not match, company scope requested for a kind that cannot share)
shows up as a warning, and the rest of the push still saves.
Every error response shares one shape, { "error": { "code", "message" }, "requestId" }:
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_query |
A bad status or dry_run value |
| 400 | invalid_json |
The body is not valid JSON |
| 400 | invalid_payload |
The body does not match the expected shape |
| 400 | duplicate_key |
The same key appears twice in one push |
| 401 | unauthorized |
Missing, unknown or revoked token |
| 404 | not_found |
No job with that slug for this token's account |
| 413 | payload_too_large / too_many_artifacts / artifact_too_large |
Over one of the size limits |
| 429 | rate_limited |
Over 120 requests per token per minute; Retry-After names the wait in seconds |
| 500 | server_error |
Something went wrong; the message names a request id for support |
On Vercel, the build command is pnpm db:migrate && pnpm build (see
vercel.ts): every deployment migrates the database before it builds.
Preview and Production must use separate databases. Sharing one means a Preview deployment's migration can change the schema Production depends on before Production is ready for it.
Migrations only move forward; there is no down migration. Rolling back a deployment restores the old code and leaves the schema as the newest migration made it. A column that a migration removed or renamed stays that way, even when the rolled-back code expects it.
Use the provider's pooled connection string for DATABASE_URL (what the
app itself uses at runtime, many short-lived queries) and keep its direct,
unpooled connection string in DATABASE_URL_UNPOOLED for migrations,
which need a session-scoped advisory lock a pooled connection cannot hold
(see scripts/migrate.ts).
DEMO_MODE=true puts a "Try the demo" button on the login page, for an
instance that exists to show Jobsmith to visitors. Each click creates a
throwaway account under the reserved demo.invalid domain, fills it with
the same six fictional jobs as pnpm seed, and signs the visitor in. The
visitor never sees a password, and nobody sees anyone else's copy.
Copies are deleted 24 hours after they were made: every demo click first
deletes the expired ones, so there is no scheduled job. At most 10 copies
are made per minute and 200 can exist at once (lib/demo/policy.ts).
The demo path opens sign-up only for its own in-process call (a random key
that never leaves the server process), so ALLOW_SIGNUP stays off and a
direct call to the sign-up endpoint is still refused. In demo mode the login
page no longer redirects to first-run setup.
Never turn it on for an instance that holds a real job search: anyone who
opens the login page can create an account on it. Leave AI_PROVIDER unset
on a demo instance unless you are willing to pay for visitors' AI calls.
The login rate limit counts attempts per client address, read from the
X-Forwarded-For header (advanced.ipAddress in lib/auth/index.ts). The
header is trusted only when it holds exactly one valid address. On Vercel
the platform sets it for you. Behind your own reverse proxy, have the proxy
overwrite the header with the address it sees (nginx:
proxy_set_header X-Forwarded-For $remote_addr;). A proxy that appends to a
header sent by the client produces a list, and a list is treated as
unknown.
Behind a chain of proxies (for example a CDN in front of nginx), let each
proxy append to the header and list the proxies' addresses in
advanced.ipAddress.trustedProxies.
Requests with no trusted client address share one counter. That is the
case with no reverse proxy at all, and behind a chain of proxies until
trustedProxies is set. For those requests the sign-in limit rises to at
least 30 attempts per minute, so a handful of failed sign-ins from anywhere
cannot lock every visitor out. Clients with a trusted address keep the
tighter per-client limit below.
AUTH_SIGNIN_MAX_PER_MINUTE is optional and defaults to 5.
| Script | Purpose |
|---|---|
pnpm dev |
Run the app locally |
pnpm build |
Production build |
pnpm start |
Run a production build |
pnpm typecheck |
Generate route types, then check them |
pnpm lint |
ESLint, then the token lint (check:tokens) |
pnpm check:tokens |
Fails on raw colors, palette classes or arbitrary values outside components/ui |
pnpm test |
Unit and integration tests (Vitest) |
pnpm test:e2e |
End-to-end tests (Playwright), resets the database first |
pnpm db:generate |
Generate a SQL migration from the schema |
pnpm db:migrate |
Apply migrations |
pnpm seed |
Create a fictional demo user and profile (only while no account exists) |
pnpm reset-db |
Drop and re-migrate a local database (refuses non-local hosts) |
Two more variables are read only by these scripts, never by the app itself:
ALLOW_DB_RESET=true: required to confirmpnpm reset-db.SEED_PASSWORD: the passwordpnpm seedgives its demo user, instead of generating and printing a random one.
pnpm test runs the unit and integration suite (Vitest).
pnpm test:e2e runs the end-to-end suite (Playwright), using the same
environment as First run. It needs the local Postgres running, resets it,
and starts its own server on port 3000, or on PORT when set, with a
matching APP_URL.
pnpm import:applications <file> [--email <address>] [--dry-run] reads a
JSON array of applications and replays each one through the same rules the
app itself uses to add and move a job, so events and stage history stay
consistent with a job added by hand.
Each entry: company, roleTitle, stageKind (one of saved, applied,
recruiter_screen, hiring_manager, portfolio_case, panel_final,
offer), and optionally appliedAt (a date, landing on the Applied
stage's entered date, honored for every stageKind other than saved),
sourceUrl, notes and nextAction. See
tests/fixtures/applications.sample.json for a complete, fictional
example.
An entry whose company and role already exist for the target account,
active or closed, is skipped, so running the same file twice changes
nothing, even after one of the imported jobs is later closed. --email
chooses which account to import into: optional while the instance has
exactly one account, required once it has more than one. Every run
prints a summary: entries created, entries skipped as already tracked,
and any entry that failed, by its position in the file - including a note
or next action that failed to save after its job was already created.
--dry-run prints the same summary without writing anything.
Tokens, vendored primitives and the re-sync process are documented in
docs/design-system.md. pnpm check:tokens enforces the token rules
outside components/ui.
AGPL-3.0-only. See LICENSE.
Outside pull requests are not merged until a contribution policy exists.



