---

A self-hosted project board for teams who just want to get things done. Named after the legendary Chilean hot dog, piled high with everything: avocado, tomato, mayo, sauerkraut. Your project starts the same way — tasks stacked, ideas overflowing, endless opinions. Too much of everything. Completo helps you make sense of the chaos. No setup marathons, no learning curve. Just open a board and go.

Free. Open Source. One command.

Completo costs nothing. Zero. Nil. undefined. It's MIT licensed — fork it, break it, fix it, ship it. No hosted plans. No premium tier. No "let's schedule a call to discuss pricing."

To install completo, the only thing you need is Node 22.18 or newer:

git clone https://github.com/ScaleCommerce-dev/completo.git
cd completo
cp env.sample .env   # set NUXT_SESSION_PASSWORD + ADMIN_USER_EMAIL / ADMIN_USER_PASSWORD
corepack enable      # pnpm ships with Node but isn't on PATH until you do this
pnpm install
pnpm setup           # migrate + create your admin from .env + seed demo project
pnpm dev             # http://localhost:3000

That's it. No Kubernetes manifests. No 14-step setup guide written by someone who clearly hates you. SQLite is baked in — there's no database to provision, no connection string to fumble. Log in with the admin you just configured. Drag. Drop. Completo.

Node 22.18 is the floor because the CLI scripts are plain .ts files run straight through Node's built-in TypeScript support — no build step and no extra tooling to install.

Or if containers are your thing:

docker run -p 3000:3000 \
  -e NUXT_SESSION_PASSWORD=$(openssl rand -base64 32) \
  -e ADMIN_USER_EMAIL=admin@yourdomain.com \
  -e ADMIN_USER_PASSWORD=change-this-password \
  -v completo-data:/data \
  ghcr.io/scalecommerce-dev/completo:latest

One command. One container. Open localhost:3000 and log in with the admin email/password you set above. The demo project is created on first boot, attributed to that admin.

No default accounts ship anywhere — set the env vars or no admin exists.

Running it on another machine over plain HTTP? Add -e NUXT_SESSION_COOKIE_SECURE=false. Reaching Completo at something like http://192.168.1.50:3000 without it, signing in appears to work and then lands you back at the login page — browsers throw away a Secure cookie on an insecure origin, and say nothing about it. localhost is exempt (browsers count it as secure), so the commands above need no change, and neither does HTTPS terminated at a reverse proxy. Put TLS in front if you can; this flag is the fallback when you can't.

Why it exists

Because every ticket system starts as "we just need something simple" and ends as a mass of gantt charts, resource leveling matrices, and a 200-page admin guide that nobody reads, maintained by nobody, understood by nobody.

You didn't want that. You wanted a board with columns and cards. So that's what we built. And then we stopped.

What it does

• Boards — Create as many as you need. Configure the columns yourself. Done.
• Cards — Title. Description. Assignee. Priority. Drag it. That's the feature list.
• Comments — Discuss the work where the work is. Markdown, @mentions, notifications. No second tool.
• Projects — Separate your work. Invite your team. Keep things tidy.
• My Tasks — One checklist. Everything assigned to you. Across all projects. Check it off. Go home.
• Search — ⌘K. Title, description or ticket ID, across every project you're in. Type TK-42 and you're there.
• SSO — Sign in with your existing identity provider. No new password to forget and then reset and then forget again.

What it doesn't do

Gantt charts. Time tracking. Burndown charts. Sprint velocity. Story points. Epics. Dependencies. Custom fields. Webhooks. Integrations. Blockchain-based task verification.

You're welcome.

Configuration

The only required environment variable is NUXT_SESSION_PASSWORD (min 32 characters). Everything else is optional and falls back to sensible defaults.

Variable	What it does	Default
NUXT_SESSION_PASSWORD	Session encryption key (required)	—
NUXT_SESSION_COOKIE_SECURE	Send the session cookie with Secure. Set to false only when serving over plain HTTP from a non-localhost address, or sign-in won't stick. localhost and TLS-terminating proxies both need the default	true
DATABASE_URL	SQLite database path	sqlite.db
UPLOAD_DIR	File attachment storage	data/uploads
SMTP_HOST	SMTP server for email (empty = email disabled)	—
SMTP_PORT	SMTP port	1025
SMTP_FROM	Sender address	—
APP_URL	Public URL (used in emails)	—
AI_PROVIDER	anthropic, openai, or openrouter (empty = AI disabled)	—
NUXT_OAUTH_GITHUB_CLIENT_ID/SECRET	GitHub OAuth (empty = disabled)	—
NUXT_OAUTH_GOOGLE_CLIENT_ID/SECRET	Google OAuth (empty = disabled)	—
NUXT_OAUTH_MICROSOFT_CLIENT_ID/SECRET	Microsoft OAuth (empty = disabled)	—
ADMIN_USER_EMAIL + ADMIN_USER_PASSWORD	Provisioned by pnpm setup (dev) and the Docker entrypoint (prod). Optional ADMIN_USER_NAME. No fallback — if unset, no admin is created.	—

CLI commands

Manage your instance from the command line. The individual commands below work with either npm run or pnpm — they just invoke node scripts/<name>.ts. The one exception is setup, which chains the others via pnpm, so it needs pnpm on your PATH.

# Setup (chains migrate → init-admin → seed)
pnpm setup               # First-time / fresh-DB bootstrap

# Or step by step:
pnpm db:migrate          # Apply pending migrations
pnpm db:init-admin       # Provision admin from ADMIN_USER_* env (.env or shell)
pnpm db:seed             # Seed demo project (attributed to admin if one exists)
pnpm db:cleanup          # Drop orphaned rows + expired invites/tokens, prune unused uploads, VACUUM

# User management
pnpm user:create <email> <password> [name] [admin]   # Create a user ("admin" = admin role)
pnpm user:set-role <email> <admin|user>               # Promote or demote a user
pnpm user:verify-email <email>                        # Manually verify a user's email

Development environment (zdev)

pnpm dev above is all you need to run Completo on your own machine. The repo also ships a containerised dev environment for zdev — Docker-based, with HTTPS and a mail catcher wired up — and that is what contributors to this repo use.

If you develop in zdev, run every command through it: zdev exec app <command>, never bare pnpm on the host. The container has its own node_modules (excluded from the file sync), its own database (/app/data/sqlite.db in a named volume), and its own injected secrets. A host-side pnpm install, pnpm test, or pnpm db:* operates on a different dependency tree and a database the app never reads, so results mislead you.

zdev start           # build, install deps, migrate, seed, run the dev server

That serves the app at https://completo.0ploy.dev. Everything is configured in .zdev/ — on every start the container installs dependencies, applies pending migrations, and seeds the demo project plus two fixed logins:

Role	Email	Password
Admin	admin@completo.local	admin1234
User	demo@completo.local	demo1234

These exist only inside your local dev container — production provisions its admin from ADMIN_USER_* and ships no default accounts. zdev info prints them any time.

zdev logs -f app         # follow the dev server
zdev exec app pnpm test  # run anything inside the container
zdev migrate             # apply migrations; also generate | seed | cleanup
zdev mail                # Mailpit — catches every outgoing email
zdev info                # URL, service status, dev logins

Changing the database schema? Edit server/database/schema.ts, run zdev migrate generate, and commit the generated migration — the container applies pending migrations on every boot.

Source edits sync live, so there's no restart loop. After changing .zdev/config.yaml run zdev update (not restart) to apply it. The container is supervised by zpinit and deliberately stays alive even if the dev server or the dependency install fails, so there's always something to shell into — check zdev logs for the error.

Agent Integration

Completo is agent-compatible. AI coding agents (Claude Code, Cursor, Cline, etc.) can pick up cards, move them through your workflow, and update descriptions as they work.

1. Install the CLI:

curl -fsSL https://raw.githubusercontent.com/scalecommerce-dev/completo/main/install.sh | sh
completo config  # Set your URL, API token, and email

2. Install the skill:

npx skills add scalecommerce-dev/completo

3. Add a .completo file to your project:

PROJECT=my-saas-app
TODO_STATUS=To Do
IN_PROGRESS_STATUS=In Progress
HANDOFF_STATUS=Review
INSTRUCTIONS=Create feature branches named <ticket-id>-<slug>. Run tests before handing off.

Now tell your agent: "grab the next ticket", "work on TK-27", or "what's a quick win I can knock out?".

Local development: To point the CLI at a local dev server instead of production, create a .completo.local file (gitignored) alongside your .completo:

COMPLETO_URL=http://localhost:3000
COMPLETO_TOKEN=<your-dev-api-token>

This overrides the global credentials in ~/.completo/.env without modifying them. You can also use --env-file path/to/env for one-off overrides. Full precedence: ~/.completo/.env → .completo → .completo.local → --env-file → environment variables.

The philosophy

Your board should be empty at the end of the week. That's it. That's the philosophy. Every feature in Completo exists to help you get there faster. Everything that doesn't was never added in the first place.

All the toppings. None of the mess.