Quickstart: the demo sandbox

The fastest way to understand kanman is to watch it finish one story from start to end. The demo sandbox is a small public repository built for exactly that. It is safe to experiment with: it has no secrets, no production data and no users.

By the end of this quickstart you will have:

• a team connected to your copy of the sandbox repository
• three drafted stories with acceptance criteria, two of them approved and written to GitHub Issues
• one story that kanman built, verified against an executable acceptance spec and handed over as a pull request with an evidence pack

What you need

• A kanman account. If your company already uses kanman, you may already be invited: sign in at app.kanman.ai. Otherwise create an account at app.kanman.ai/signup and open the link in the confirmation email. The same card then asks for your workspace’s name and web address, and Create workspace opens your workspace, where kanman introduces itself and offers Set up a team. A new team starts with a 14-day trial of the Team plan, without a credit card (see Plans and billing).
• A GitHub account that can create repositories (personal or in an organization).
• About 15 minutes. Most of it is waiting while kanman works.

You do not need Docker or Node on your machine. kanman provisions everything it runs in its own sandbox.

The sandbox repository

kanman-ai/pilot-sandbox is a small invoicing service in TypeScript: a Fastify API, a plain HTML invoice list, unit tests and a CI workflow. Amounts are integer cents, and the data is seeded in memory on every start.

What makes it a good first repository is the .kanman folder:

Because the manifest exists, the full outcome gate runs: kanman writes a spec that fails before any code exists, and the story only reaches Review when that spec passes on a clean checkout.

Step 1: Copy the sandbox into your account

1. Open github.com/kanman-ai/pilot-sandbox and click Use this template (or Fork).
2. Create the copy in your account or organization. Keep the name pilot-sandbox.
3. In the new repository, open Settings > General > Features and make sure Issues is turned on. GitHub turns Issues off for forks by default, and kanman writes stories to GitHub Issues.

kanman opens pull requests against your copy, never against the original.

Step 2: Create the team

1. Open the team setup. If you just created your workspace, click Set up a team under kanman’s first message. Otherwise click the workspace name at the top left and choose New team.
2. Tracker: click Connect on the GitHub card. GitHub’s sign-in opens in a small window; authorize kanman with the GitHub account that owns your copy. When the window closes, your GitHub connection appears in the list and is selected. (If your browser blocks the window, click Open in this tab: you come back to the same step with everything you entered.) See Connect GitHub for the permissions.
3. Repositories: enter <your-account>/pilot-sandbox as the tracker project, name the team, for example “Sandbox Team”, add the repository <your-account>/pilot-sandbox and keep the base branch main.
4. Columns: click Use suggested roles and check that one status is Ready.
5. Policy: keep the preselected Balanced preset. Every new team starts with a run budget of 2.00 EUR and plan approval for every story.
6. Executor: choose Claude Code and Pay through kanman.
7. Skip Look, then click Create team on the last step.

The team’s own chat with kanman opens, with the team’s board beside it (every team has its own chat; General is the conversation across all teams). Its header says Idle and shows the preset Balanced, and a Setup card pinned at the top of the team’s chat shows your progress: workspace, connection and team are done, the next step is your first story. The Setup card leads you through the rest of this quickstart; it is the same in every browser, and Hide removes it for everyone in the workspace.

Step 3: Turn a requirement into stories

1. In the Setup card, click Describe it (or press N). The box of your sandbox team’s chat takes the focus; the chip under it names the team. If you write a requirement in General instead, kanman offers to Continue in your team and takes your request along. See Talk to kanman.

2. Paste this requirement and press Enter:

   Customers need to export their invoices as CSV, filtered by date range.
   

3. After a few seconds kanman answers with a card of three drafted stories. Click Open review to read them in full: each has Given/When/Then acceptance criteria, a test plan, a size, and a Demonstrate block: the concrete steps that show the outcome, such as “open the invoice list, pick March 2026, click Download CSV, the file has the columns date, number, amount”.

4. Edit a criterion if you want to, then click Back to the conversation. In the card, Reject the story you do not need and Approve the other two.

5. Click Write 2 stories. The card says “2 stories written”.

kanman writes the approved stories to GitHub Issues in one batch, with the kanman label. They appear in the Backlog column with the badge “Ready for kanman”.

Step 4: Move a story to Ready

Click Pick a story in the Setup card: the Ready column lights up. Drag the story “Export invoices endpoint” (the exact title may differ) into it, or use Move to on the card.

The card waits in Refining with the note “Checking the acceptance spec”. Before kanman starts building, it writes an executable acceptance spec from the Demonstrate block into .kanman/acceptance/<KEY>/ and runs it against a fresh copy of the app. The spec must fail at this point, because the feature does not exist yet. Then the story moves to Ready, the story page shows Spec: red (expected) and the run starts. If the spec passed already or mocked its own target, the story would stay in Refining with a plain reason.

Step 5: Approve the plan

The team asks for plan approval before any code is written. The decisions icon in the top bar shows 1, and the Setup card says that kanman needs your OK on the plan.

1. Click Review the plan in the Setup card. The run page opens with the decision at the top.
2. Read the plan: which files kanman intends to change and how it will show the outcome.
3. Click Approve plan. The decision folds away and the run moves on to Implementing.

The same decision is also listed under Decisions (the inbox icon); answering it there or on the run page is the same.

Step 6: Watch the run

Open the run from the story card, or from the Runs tab. The run page’s overview says what kanman is doing right now and shows the steps Plan, Code, Acceptance tests, Clean room, Review, CI and Merge, each with its state and time, the cost against the 2.00 EUR run budget and the latest progress.

During Verifying, kanman runs the spec on a clean checkout in a fresh environment, waits for CI and has an independent reviewer check every acceptance criterion against the diff. The run’s Evidence tab fills in check by check as they finish. If something fails, kanman makes one automatic rework attempt with the findings.

Desktop Mobile

Step 7: Review the evidence pack

When the run reaches Review, you get:

• a pull request in your pilot-sandbox copy
• the evidence pack as one comment on the pull request and one on the GitHub issue: the plan, every acceptance criterion with its result and file references, the gate results with the Playwright trace and screenshots, the test and CI results, the policy decisions, cost and duration

Open pull request is the one main button on the run page. Review the pull request like any other and merge it if you are happy. With the default merge policy, kanman never merges by itself.

When the pull request is merged, the card moves to Done and the Setup card completes with a short summary, for example “Your first verified change is merged: 3 criteria, 12 tests, €0.80”, and two next steps: Invite your team and Set budgets. Click Done to fold the card away.

What to try next

• Move the second approved story to Ready and watch two runs side by side. Balanced allows two runs at a time, and the 14-day Team trial allows up to five.
• Open the Audit log (from the workspace name at the top left) to see every policy check, approval and run state change with its actor and result.
• Read How a story flows for the full picture, then Set up a team on one of your own repositories.