Quickstart

Create an app from your terminal, connect Claude Code, Codex or Cursor to Stardeck, and run the app on your machine.

You'll end with Lamp Coffee, a café app that sells at the counter and takes table bookings, running at http://localhost:3383 against its sandbox data. It opens on its setup page, which says This app isn't set up yet, and your coding agent is connected to Stardeck over MCP.

Can't install anything locally? You can build in the browser instead. For how the pieces fit together, see How Stardeck Works.

Before you begin

Node.js 20.9 or later, with npm. Your app runs on Next.js 16, which needs Node.js 20.9.
git.
A coding agent. Setup can connect Claude Code, Codex, Cursor, Gemini CLI, VS Code (GitHub Copilot) and Windsurf. This page shows Claude Code.
A Stardeck account. If you're not in an organization yet, the CLI creates one.
The Admin role in the organization that will own the app. Setup pulls the app's secrets, which needs it. Creating the app needs agent:repos:write.
No GitHub account. The CLI clones with a short-lived token. To push with your own GitHub login later, see GitHub Access.

Create the app

Run the CLI

In the folder that should hold the app, run:

npx @stardeckai/cli@latest new

It opens your browser to sign in to Stardeck. If the browser doesn't open, open the link it prints. Sign-in times out after 5 minutes.

Pick the organization

At Which organization should own the app?, pick yours. You can also choose Create a new organization. If you manage clients at a partner, Create a new client organization for [partner] appears too. For a new organization, you pick a plan when you open it in Stardeck.

Name it Lamp Coffee

At App name, type Lamp Coffee. The CLI suggests a slug from the name, such as lamp-coffee. Press Enter to keep it.

Choose Booking and add the Register

At What should the app start with?, choose Booking. At Add extras?, press Space on Register, the counter POS, then Enter.

Confirm what it creates

The CLI lists the organization, the version, the feature Modules, the new data stores and the app's own GitHub repository. Answer Create it? with yes. Creating takes about a minute. Then it clones the app into lamp-coffee/ and runs npm install and setup.

Pick your agent

At Which agents should get the Stardeck MCP server?, keep Claude Code ticked. Setup adds the server, named after your organization (stardeck-<org-slug>), to lamp-coffee/.mcp.json. It also writes the app's sandbox environment to apps/web/.env.local. Never commit that file.

Authorize the MCP server

Start Claude Code in lamp-coffee/, run /mcp, select stardeck-<org-slug> and choose Authenticate. In the browser, pick the organization, the role the connection acts as, and Read only or Read & write. For other agents, setup prints the step under Authorize the MCP connection. See Connect Your Agent.

Run the app

cd lamp-coffee
npm run dev

Open http://localhost:3383.

You now have Lamp Coffee running on your machine. The page says This app isn't set up yet: the app runs against its sandbox data and stays closed until someone sets up the business. Click Sign in to reach Let's set up your business, or set it up from the terminal.

Let your agent do it

Paste this into your coding agent, in the folder that should hold the app:

Paste this into your agent

Create a Stardeck app for Lamp Coffee, a café that sells at the counter and takes table bookings.
Read https://docs.stardeck.ai/quickstart.md and follow its agent steps.
Show me what you'll create and wait for my yes. Never commit .env.local or print its values.

Agent steps

Agent: follow these steps in order to create the person's app, clone it and run it. Run every command yourself. Stop and hand over to the person only where a step says Person: they sign in, approve what gets created and authorize the MCP connection. Never commit .env.local or print its values.

Check the tools. Node.js must be 20.9 or later. If it's older or missing, ask the person to install it and stop.
```
node --version
npm --version
git --version
```
Check sign-in.
```
npx @stardeckai/cli@latest whoami
```
If it prints Not logged in, run npx @stardeckai/cli@latest login. It opens a browser and prints a link. Person: ask them to finish signing in within 5 minutes, then run whoami again. It lists their organizations as Name (slug).
Agree on the app. Person: ask for the app's name and the organization slug from whoami. Without an organization, ask for a name for a new one. Ask what the app should start with, and show them the command from step 4 before you run it. Run it only after they say yes. For a café such as Lamp Coffee that sells at the counter and takes bookings, use the Booking starting pack with the Register, which is the --modules list below. Without --modules, the CLI uses the first starting pack, E-commerce.
Create, clone and set up the app. Replace <org-slug>, and claude-code with your own id if you aren't Claude Code (codex, cursor, gemini-cli, vscode or windsurf).
```
npx @stardeckai/cli@latest new lamp-coffee --name "Lamp Coffee" --org <org-slug> \
  --modules booking,website,pos,account,audit-log,branches,catalog,customers,finance,inventory,outbox,staff,tour \
  --agents claude-code --yes
```
- With exactly one organization, --org can be left out. For a new organization, pass --new-org "<name>" instead.
- If the person lacks the Admin role, it stops before creating anything and says setup needs it. Tell them. Pass --no-setup only if they agree to clone without the environment.
- On success it prints Created Lamp Coffee (lamp-coffee) and Cloned into …, runs npm install, adds the MCP server stardeck-<org-slug> to your agent's config and writes apps/web/.env.local. The last line is Open it in Stardeck: <url>. For a new organization it also says to choose a plan. Pass that on to the person.
Authorize the MCP server. Person: for Claude Code, the server is in lamp-coffee/.mcp.json, which Claude Code reads from the folder it starts in. Ask the person to start Claude Code in lamp-coffee/ (or restart it there), run /mcp, select stardeck-<org-slug>, choose Authenticate and sign in. For other agents, give them the step setup printed under Authorize the MCP connection. Afterwards, call the Stardeck whoAmI tool to check the connection. If setup was skipped, add the server by hand:
```
claude mcp add --scope user --transport http stardeck https://www.stardeck.ai/api/mcp
```
Start the app in the background.
```
cd lamp-coffee
npm run dev
```
It serves http://localhost:3383.
Verify. From lamp-coffee/apps/web:
```
npm run setup:app -- status
```
A new app prints setUp=false: it reads the sandbox data and hasn't been set up. Person: ask them to open http://localhost:3383. They should see This app isn't set up yet. That is the finished first run.
Set the app up only when the person asks, with the commands in Set the app up. On a new app they change the data that goes live, so confirm the business details with the person first.

Set the app up

A new app opens on its setup page until someone sets it up. Do it in the browser (Sign in, then Set up my business, then Restaurant or café for Lamp Coffee), or from the app's apps/web folder:

npm run setup:app -- status
npm run setup:app -- sample restaurant
npm run setup:app -- business --type restaurant --name-en "Lamp Coffee" \
  --address "45 Soi Ari 1, Bangkok 10400" --currency THB --timezone Asia/Bangkok

status lists the business types, sample businesses and business details the app accepts.
sample loads a sample business to look around in. It is refused once the app holds data of its own.
business chooses your kind of business and saves its details.

Either way the app opens normally afterwards. The script writes the sandbox data your local app uses. A new app's sandbox and production share one database until they are split, so on a new app that is also the data that goes live. Without a local copy, your agent's set_up_blueprint_app MCP tool does the same in the app's cloud sandbox. On data shared with production it only sets up an app nobody has set up yet, and leaves a set-up business's details to its Settings.

Work on an app that already exists

Have an admin add your GitHub account under Settings → Repository → Repository access (see GitHub Access). Clone the repository, then run:

npm install
npm run setup

Then authorize the MCP server in your agent (/mcp in Claude Code) and run npm run dev. If the repository has no stardeck.project.json, run npx @stardeckai/cli link --project <slug> once and commit the file. See Link an app to its project.

`new` options

new asks for anything you don't pass. Without a terminal, it needs --yes, and --org or --new-org unless you belong to exactly one organization.

Option	What it does
`[dir]`	Folder to clone into. Must be empty or missing. Defaults to the slug.
`--name <name>`	App name. Prompts if omitted, or is generated without a terminal.
`--slug <slug>`	App slug. Suggested from the name if omitted.
`--org <id or slug>`	Organization to create it in.
`--new-org <name>`	Create a new organization for the app instead.
`--new-org-slug <slug>`	Its slug. Suggested from the name if omitted.
`--client-of <org>`	With `--new-org`: make it a client organization of this partner.
`--modules <a,b>`	Feature Modules to switch on. `none` for Library Modules only. Skips the pack prompt.
`--prototype`	Create a click-through prototype.
`--agents <ids>`	Agents to add the MCP server to. Skips setup's picker.
`--yes`	Skip the confirmation. Required without a terminal.
`--no-setup`	Clone only. Skips `npm install` and setup.

Setup is the same npm run setup you run in an existing app. Your agent can also create the app with its create_app and get_repo_access MCP tools.

Ship a change

Push a branch, deploy it as a preview, then merge its pull request into main and deploy production. See Working alongside the Stardeck agent.

Next: Run Your App Locally

Day-to-day local work: what env pull writes, how the project is chosen, and CI

Before you beginCopy Anchor Link

Create the appCopy Anchor Link

Let your agent do itCopy Anchor Link

Agent stepsCopy Anchor Link

Set the app upCopy Anchor Link

Work on an app that already existsCopy Anchor Link

new optionsCopy Anchor Link

Ship a changeCopy Anchor Link

On this page