Quickstart

One command scaffolds an app. A few more start Postgres and Redis and open a working admin UI with login, a sidebar, and a Tasks list with demo rows. You do not need to clone a repository or write screens.

You do not need to install anything first. The installer fetches Bun if it is missing (Requirements for details).

1. Scaffold your app

curl -fsSL https://kumiko.rocks/install.sh | bash -s -- my-app
cd my-app
bun install

The installer checks for Bun (installs it via the official bun.sh script if missing), then runs bun create kumiko-app my-app. The scaffolder asks which features to include, pick what you need, dependencies between features resolve automatically. Non-interactive: append --yes for the recommended set (bash -s -- my-app --yes).

This generates the whole workspace, package.json, src/run-config.ts, demo features you picked (with list + edit screens), bin/dev.ts, src/client.tsx, .env.example, docker-compose.yml, and README.md.

You already have UI

The starter mounts foundation features (secrets, sessions, auth stack) and a tasks demo you can click immediately after login, not an empty shell.

2. Configure secrets

cp .env.example .env

Set two values the boot and dev server need:

JWT_SECRET=$(openssl rand -base64 32)
KUMIKO_SECRETS_MASTER_KEY_V1=$(openssl rand -base64 32)

Paste them into .env. Postgres and Redis URLs in .env.example already point at the local docker-compose.yml services.

Two secrets required

Without JWT_SECRET and KUMIKO_SECRETS_MASTER_KEY_V1 in .env, boot and bun dev fail fast, generate both before starting services.

3. Start services + dev server

docker compose up -d
bun dev

bun dev prints a welcome banner with:

• the app URL (default http://localhost:4173, or $PORT if set)
• admin login: [email protected] / changeme

Open the URL, sign in, and click Tasks in the sidebar. Demo rows are pre-seeded, create another task and it appears in the list over SSE.

That’s it 🎉

You scaffolded an app, logged in, and clicked through a generated admin UI. Next: Tutorial, see what’s inside the starter tasks feature and customize it.

Boot-only smoke (CI, no browser)

Validates feature composition without touching a database:

bun run boot

[runProdApp] boot validation OK (8 features, 8 registry entries)

CI only

Use bun run boot in pipelines after bun install && cp .env.example .env : no Postgres, Redis, or browser needed.

Make it yours

After login you see default Kumiko chrome, neutral tokens from @cosmicdrift/kumiko-renderer-web. Re-skin the whole admin (and any public surfaces that share the same stylesheet) with one file at the app root: src/styles.css is injected automatically by the dev server.

Import the renderer stylesheet, then override design tokens in @theme:

@import "@cosmicdrift/kumiko-renderer-web/styles.css";

@theme {
  --color-primary: #ff2a6d;
  --color-primary-foreground: #ffffff;
  --color-ring: #05d9e8;
}

Save and let bun dev reload, buttons, links, and focus rings follow --color-primary everywhere. The kumiko.rocks hero demo uses the same pattern with a Vice City palette.

Full example (background + accent overrides for a dark neon look):

@import "@cosmicdrift/kumiko-renderer-web/styles.css";

@source "./**/*.{ts,tsx}";

@theme {
  --color-primary: #ff2a6d;
  --color-primary-foreground: #ffffff;
  --color-ring: #05d9e8;
}

/* Vice City: deep purple chrome + hot pink CTAs + cyan focus — hijack
   :root:not(.dark) so the hero GIF pops without a theme-toggle step. */
@layer base {
  :root:not(.dark) {
    --color-background: #1a0533;
    --color-foreground: #f0e6ff;
    --color-card: #240b45;
    --color-card-foreground: #f0e6ff;
    --color-popover: #240b45;
    --color-popover-foreground: #f0e6ff;
    --color-border: #4a2080;
    --color-input: #4a2080;
    --color-muted: #2d1055;
    --color-muted-foreground: #c9b8e8;
    --color-secondary: #2d1055;
    --color-secondary-foreground: #f0e6ff;
    --color-accent: #05d9e8;
    --color-accent-foreground: #1a0533;
    --color-destructive: #ff006e;
    --color-destructive-foreground: #ffffff;
    --color-primary: #ff2a6d;
    --color-primary-foreground: #ffffff;
    --color-ring: #05d9e8;
  }
}

Show Pony uses the same mechanics with a full lavender/violet palette (background, sidebar, borders, not just primary buttons) in Look and feel. That keeps the tutorial app visually distinct from both neutral Kumiko chrome and the Vice City hero demo.

Next steps

→ Make it yours, default chrome, then one styles.css edit (same pattern as the kumiko.rocks hero demo).

→ Tutorial, what the starter tasks feature contains and how to customize it.

→ bunx @cosmicdrift/kumiko-cli add feature <name>, scaffold another domain feature (bare entity; add screens when you need UI).

→ Prefer exploring a real app first? Show Pony tutorial : a complete multi-tenant RSVP app, chapter by chapter.

→ What you get, every built-in capability at a glance.

→ Concepts, why Kumiko works the way it does.