Karts

Quickstart. From install to a running branch.

karts up runs your branch in its own Firecracker micro-VM, with its own database and a public URL. You need an early-access account and a web app on Postgres, MySQL or SQLite, in Node, Python, Go, Ruby or PHP. Karts applies numbered .sql migrations itself, or runs your migration tool. Limits: The VM and Compatibility.

Short version: install the CLI, run karts login, then tell your agent to read the onboarding prompt. It does steps 3 and 4 for you.

No account yet? karts up --local runs the branch on your own Mac, with no sign-in and no upload. It needs Docker Desktop. See Local mode.

Early access. By invitation. Request early access first. These steps work once your team is set up. Before your first karts up, read What to expect: where Karts runs, which data to use, and how to delete everything.

1. Install the CLI

curl -fsSL https://drivekarts.si/install.sh | sh

The installer picks the build for your OS and CPU (macOS or Linux, amd64 or arm64), checks its sha256, and puts karts in ~/.local/bin. It does not need sudo. Read the script before you run it.

2. Sign in

karts login

The CLI prints a short code and a link like https://app.karts.kartikey.fyi/device?code=XXXX-XXXX. Open it in a browser where you are signed in to Karts, check the code matches, and approve. This works over SSH and on machines with no browser. Once you are in, the CLI links What to expect.

For CI and agents that can't use the keychain, set KARTS_TOKEN instead.

3. Link the repository

karts init

Run it once, at the top of the repository. It creates a project in your team and writes project: <id> into karts.yml. If there is no karts.yml yet, it writes a starter file for you to check. Commit it, so every clone uses the same project, and merge it into your default branch: the template database is built from the default branch's karts.yml, and until it is there every karts up builds its database from scratch.

This is the karts.yml of Tiny Shop, the sample app we measure with:

runtime: node22
database: postgres
migrations: db/migrations    # numbered SQL files; Karts checks and applies them itself
install: npm ci
seed: npm run seed           # demo data; runs once when the template database is built
start: npm start             # listens on $PORT, reads $DATABASE_URL
health: /health

Every key is described in the karts.yml reference.

4. Run the branch

karts up

From the branch you want to run. Karts checks the branch's new migrations and claims their numbers, uploads the working tree, clones main's template database, applies the new migrations, starts your app in a micro-VM, and prints the URL once your health check answers.

With --timings it prints each server step. These are the steps of the measured run of Tiny Shop's feature/refunds branch:

tiny-shop · feature/refunds2.3 s
$ karts up --timings
    disks             1 ms
    restore          16 ms
    clone_init      112 ms
    files             8 ms
    install           0 ms
    migrations      230 ms
    ready           881 ms
  feature-refunds-fc00  https://feature-refunds-fc00.karts.kartikey.fyi   (public; seed data only)

A repeat karts up builds a new revision beside the running one and switches when it is ready. No rows carry over: the new revision's database starts from the template again.

5. Work with it

karts status              # state, URL, revisions and warnings
karts url                  # just the URL
karts logs --follow        # app, install, migration and seed output
karts exec -- npm test     # runs inside the VM, DATABASE_URL set
karts exec -i -- psql < q.sql   # -i sends your stdin
karts list                 # every environment of this project
karts fork                 # a copy of the running app, memory and data included
karts down                 # destroys the VM and its database

Keys your app needs go in karts secret set, not in karts.yml. To test with real data, make a masked copy first.

6. Give it to your agent

Your coding agent can write karts.yml for you. Tell your agent:

read https://drivekarts.si/onboard.md and set this repo up for Karts.

The onboarding prompt has it explore the repository, write karts.yml, check it with karts check-config, run karts up and fix what fails, then report what Karts runs every time and what it could not support. It works with Claude Code, Codex, Cursor and any agent that can run a shell. karts onboard prints the same prompt, matched to your CLI's version.

Agents can run the same commands in a shell. To offer them as MCP tools instead, add karts mcp to Claude Code, Codex or Cursor: see MCP setup.