Everything you need to run kamotion

kamotionis a personal kanban-style project manager that turns unstructured input — Slack threads, email chains, Zoom transcripts, meeting notes — into structured cards on a board. It’s built for people drowning in channels who need one place for the work to live.

The app is open source and designed to be self-hosted. You bring your own AI key (OpenRouter, OpenAI, Anthropic, Google, or a local model via Ollama), wire up a Supabase project for data + auth, and it runs anywhere Node.js runs.

Who it’s for

• Personal life — groceries, birthdays, school forms, trip packing, a move. Anything that lives in a group chat or a brain-dump note becomes one clear list.
• Solo operators — freelancers, founders, and makers who need a single pane for a noisy inbox.
• Small teams — up to a handful of members with admin/member/viewer roles.
• Developers — anyone who wants a hackable PM tool they control end-to-end.

Six primitives make up the whole app. Learn these and the rest is configuration.

Roles

• admin — everything, including user and team management, AI settings, and archive admin.
• member — read/write cards, drive the board and Gantt.
• viewer — read-only. Useful for stakeholders.

You’ll have a working local instance in about 10 minutes. The only external dependency is a free Supabase project.

Prerequisites

• Node.js 22 (active LTS). Use nvm use 22 if you have nvm.
• npm (ships with Node).
• A Supabase account — free tier works. Sign up here.
• An AI key — OpenRouter is the default and gives you access to dozens of models with one key. See AI configuration.

1. Clone and install

bashgit clone <kamotion-repo-url>
cd kamotion.io
npm install

2. Create a Supabase project

1. Go to supabase.com/dashboard and create a new project. Pick a region close to you.
2. In Project Settings → API, copy your URL, anon / public key, and service_role secret.
3. In SQL Editor, run each file in supabase/migrations/ in order (01 through 09).

3. Configure environment variables

Create .env.local in the repo root:

.env.localNEXT_PUBLIC_SUPABASE_URL=https://<your-project>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<anon-key>
SUPABASE_SERVICE_ROLE_KEY=<service-role-key>  # optional

NEXT_PUBLIC_APP_URL=http://localhost:3000
LOG_LEVEL=debug

AI_API_KEY_OPENROUTER=sk-or-v1-...
# Or any of:
# AI_API_KEY_OPENAI=sk-...
# AI_API_KEY_ANTHROPIC=sk-ant-...
# AI_API_KEY_GOOGLE=...

# Optional — only needed if you use the n8n processing path
N8N_WEBHOOK_AUTH_USER=
N8N_WEBHOOK_AUTH_PASSWORD=

4. Seed your admin user

1. In Supabase Authentication → Users → Add user, create a user with your email + password. Check auto-confirm user.
2. In SQL Editor, insert a profile row with role='admin' for that user:

sqlinsert into public.profiles (id, email, full_name, role, status)
values (
  '<auth-user-id>',
  'you@example.com',
  'Your Name',
  'admin',
  'active'
);

5. Run it

bashnpm run dev

Open http://localhost:3000, click Log in, use the credentials from step 4. You land on /app with a kanban board and a few seeded demo cards.

The feature that gives kamotion its name. Paste any text — a Slack thread, an email, a meeting transcript — and the AI extracts cards.

How to use it

1. Go to /app/generate via Generate Task(s) in the sidebar.
2. Paste raw text in the textarea.
3. Click Generate. The AI returns a list of suggested cards in a preview modal.
4. Review each suggestion. Uncheck any you don’t want. You can edit titles, priorities, due dates, and assignees inline.
5. Click Add to board. Cards land in the Ready column.

The kanban is where the work lives. Five statuses, drag and drop, per-card detail drawer, filter bar.

Creating cards

• Click + New card in any column header → fill the dialog → save. The card lands in that column.
• Or go to Generate tasks for bulk AI extraction.

Moving cards

• Drag across columns to change status. Blocked is excluded from drag targets — use the drawer to set it.
• Drag within a column to reorder. Positions use midpoint math so you can insert anywhere without rewriting every row.
• At desktop width (lg+), click the collapse chevron on a column header to collapse it into a 56px ribbon. Drop targets still work on collapsed columns.

Editing

• Click any card → side drawer opens with every field editable.
• Cmd/Ctrl+S saves. Closing with unsaved changes prompts a confirm.
• Changing status in the drawer auto-moves the card to the matching column on save.

Filtering

The filter bar above the board lets you scope by search term, assignee, and a combined priority + blocked-flag dropdown. Filters are session-only and clear on reload.

Same data, different lens. Gantt shows scheduled cards as bars positioned by due_date and sized byestimated_duration.

Interactions

• Drag a bar left or right to shift the card’s due date. Duration is preserved.
• Click a bar (or the label on the left) to open the card drawer.
• Today line is a vertical marker so you can see what’s late.
• Weekend tint on Sat/Sun columns — a visual cue, not a constraint.
• Unscheduled cards (no due date) are listed below the chart as clickable chips. Open one and set a date to pull it into the Gantt.

/app/team is admin-only CRUD for the team_memberstable. Think of team members as the roster of people you can assign work to — they don’t need to have login access to kamotion.

• Click + Add member → fill name/email/role → save.
• Toggle the active switch to hide a member from assignee pickers without deleting them.
• The Link2 icon next to a row means that member is tied to a kamotion user account (created via the Users page). Name and email lock when editing a linked row — edit those on the Users page instead.

/app/settings/users is admin-only CRUD for login accounts. It uses the Supabase Admin API, which requires SUPABASE_SERVICE_ROLE_KEY in your env.

What you can do

• Create — email, password, role, status. kamotion auto-creates a linked team_member row so the new user is immediately assignable.
• Edit — name, role, status. Name changes mirror to the linked team_member.
• Password reset — set a new password for the user directly.
• Delete — removes the auth user; the linked team_member stays (with user_id nulled out) so historical assignments remain intact.

Deleting a card doesn’t erase it immediately. Cards go to /app/archive (admin-only) as a soft delete. You have 30 days to restore, then a daily pg_cron job purges them.

• Restore — puts the card back in the column its status points to.
• Delete permanently — bypasses the 30-day window for cards you know you’ll never need.

All AI behavior is configured at /app/settings (admin-only). Two paths are supported:

In-app path setup

1. Add your provider key to .env.local (AI_API_KEY_OPENROUTER, etc).
2. Go to /app/settings.
3. Pick a provider. Each provider has a curated model dropdown plus a Custom... option for any model slug.
4. Optionally tune the system prompt and JSON schema. Defaults are production-ready.
5. Hit Test parse at the bottom of the page to validate end-to-end with a sample input.

The n8n processing path offloads AI work to a self-hosted n8nworkflow. It’s optional, but unlocks a few things:

• Swap models without redeploying kamotion.
• Chain the AI call with other steps — enrichment, routing, conditional branching, downstream webhooks.
• Use local models via Ollama (keep all AI on-device, zero cloud AI cost).
• Centralize AI prompts if you run multiple internal tools that need the same parser.

Setup summary

1. Install and run n8n (Docker one-liner works, see their docs).
2. Import docs/n8n-sample-workflow.json from this repo. It’s a 4-node starter: Webhook → AI Agent (with Structured Output Parser) → Respond to Webhook.
3. Attach any Chat Model sub-node to the AI Agent — OpenAI, Anthropic, Gemini, Ollama, anything n8n supports.
4. Enable the webhook and copy its URL.
5. In kamotion /app/settings, switch the processing path to n8n and paste the URL.
6. Optional: set N8N_WEBHOOK_AUTH_USER and N8N_WEBHOOK_AUTH_PASSWORD in kamotion’s env to send Basic Auth to the webhook.

Full setup guide with troubleshooting is at docs/00_N8N_SETUP.md in the repo.

Pick whichever matches your preference for control vs. convenience. All four recipes use the same codebase and environment variables — only the hosting layer changes.

Recipe A — Vercel + Supabase (free)

1. Push your fork to GitHub.
2. Go to vercel.com/new, import the repo, accept the Next.js defaults.
3. Add the same env vars from your .env.local in the Vercel project’s Settings → Environment Variables. The NEXT_PUBLIC_* ones must be set before the first build.
4. Click Deploy. Vercel builds and deploys to a *.vercel.app URL. Push to main auto-deploys.
5. Add your custom domain in Settings → Domains.

Recipe B — Dokploy on your VPS

The current production deployment. Dokploy is an open-source self-hosted PaaS (Heroku-alike) that runs on any Linux box. Nixpacks auto-generates the Dockerfile — you don’t write one.

1. Install Dokploy on your VPS (one-liner from their docs).
2. Connect your GitHub account in Dokploy.
3. Create an app → point it at your kamotion fork → branch main.
4. Paste your env vars in the Dokploy env panel.
5. Add a domain, turn on HTTPS (Traefik + Let’s Encrypt auto-issues).
6. Enable the GitHub webhook → every push to main triggers a rebuild and container swap.

Full walkthrough at docs/00_DEPLOY.md in the repo — including the engines.node: "22" pin (Nixpacks tops out at Node 23 currently), the $-in-password gotcha, and rollback via Dokploy’s last-10-deployments list.

Recipe C — Docker Compose self-host

If you want to run on your own hardware without a PaaS layer, use Docker Compose. The repo ships a Dockerfile suitable for a standalone Next.js build. Pair with a reverse proxy (Caddy or nginx) for HTTPS. You can also run your own Supabase locally via Supabase’s self-host Docker setup for a fully offline stack.

Recipe D — Local only

For evaluation or personal single-machine use, npm run dev against a free Supabase project is enough. No deployment layer at all.

kamotion can run end-to-end with zero recurring cost. Here’s a full free-tier recipe:

Not every team wants to run their own server. If you’d rather skip the infrastructure and just use kamotion, there’s a managed-hosting path — the project author will host an instance for your team and hand you the keys.

Same product, same AI configuration options, same kanban + Gantt surface — your data lives on a Supabase project provisioned for you, and you get an admin login to manage your own users.

Hosted access is a good fit if any of these apply:

• You want kamotion's value but your team doesn't have a backend engineer.
• You'd rather pay for a managed instance than spend hours on Supabase + Dokploy + DNS.
• You want a single point of contact when something breaks, instead of debugging Postgres yourself.

If you’d rather self-host (and you have the technical chops), everything you need is in this doc — see Deployment and Run it for $0.

The repo is public at github.com/edwrdcrpio/kamotion.io — open issues for bugs and feature requests, send PRs for fixes. Conventions:

Commit style

Conventional commits. Every message starts with a type:

feat(E.3): mobile responsive — sidebar drawer, collapsible kanban
fix: resolve C.2 typecheck errors in settings route
docs: add n8n setup walkthrough
refactor: extract site nav and footer into shared components

And ends with Authored By: Edward Carpio <https://github.com/edwrdcrpio> & Claude for AI-pair-programmed work.

Dev loop

bashnpm run dev          # start dev server
npx tsc --noEmit     # typecheck
npm run build        # production build
npm run lint         # eslint

PR expectations

• Typecheck clean, build clean.
• One feature per PR — no drive-by refactors on unrelated code.
• Update the relevant doc (this page, or docs/*.md) in the same PR.
• If you change a DB schema, add a migration under supabase/migrations/ with a zero-padded prefix.

Can I switch AI models without redeploying?

Yes — everything is configured at /app/settings. Change provider or model, save, and the next parse uses the new config. No code change, no restart.

Does it work offline?

The app itself needs the Supabase connection to run. But if you self-host Supabase locally (via Docker) and use Ollama for AI via the n8n path, the entire stack runs on your LAN with no internet.

How do I back up my data?

Supabase provides daily backups on paid tiers and manual point-in-time exports on free tier via pg_dump. Since kamotion is pure Postgres + auth, any standard Postgres backup tool works.

Can I use it for a team?

Yes. It’s optimized for solo-first but supports up to a handful of members with role-based access (admin / member / viewer). There’s no built-in billing or org separation — it’s one board per instance.

Will there be public signup?

Not planned. kamotion is invite-only by design — admins provision users. If you want a SaaS with public signup, fork the repo and wire it up.

Why “kamotion”?

Slang for commotion— the organized chaos of messages, threads, and calls that become clarity once they’re on a board.

kamotion today is the kanban and the parser. Here’s what’s on deck — what you’ll see land in the repo next.

• Inbox sync — kamotion pulls new emails on its own and queues them for parsing. Skip the paste step entirely.
• Slack & Telegram bots — tag @kamotion in a channel and the thread becomes cards without anyone leaving the conversation.
• Active comms — due-date nudges, team pings, and drafted follow-up emails routed to whoever owns the card.
• Delegate to AI — assign a card to an agent to write the blog, email the vendor, plan the event, or fix the site bug. You review the output before it ships.

Roadmap is best-effort, not a contract — but the order roughly reflects how we’re sequencing them. Each lands behind a feature flag so you can opt in when you’re ready.