Run Your App Locally
Pull your app's sandbox environment and run it with npm run dev.
Your app's data store, storage and secrets live on Stardeck, not in the repo. stardeck env pull
writes them to .env.local, so npm run dev runs against your sandbox data. This page is the
reference for that. To create an app and run it for the first time, follow
the Quickstart.
- You need the Admin role in the app's organization, because the pull returns decrypted secrets.
npm run setupdoes this for you, along with connecting your agent.- Local writes land in the sandbox's data. On a new app that is also production's data until you give the sandbox its own branch. See Branches and environment routing.
- Never commit or share
.env.local.
Clone an app
npx @stardeckai/cli@latest clone my-appIt signs you in, finds the app by its slug (or id) in your organizations, clones it into a folder
named after it, installs dependencies and runs setup,
which connects your agents and pulls .env.local. Your role needs agent:repos:write and edit
access to the app. Without the Admin role, clone stops before cloning unless you pass
--no-setup.
| Option | What it does |
|---|---|
[dir] | Folder to clone into. Must be empty or missing. |
--org <id or slug> | Look for the app only in this organization. |
--agents <ids> | Agents to add the MCP server to. Skips setup's picker. |
--no-setup | Clone only. |
Cloned it with git yourself? Run npx @stardeckai/cli@latest setup inside the clone.
Pull by hand
npx @stardeckai/cli login
npx @stardeckai/cli env pull --port 3383
npm run dev--port sets your app's own URL to your dev server: 3383 in current apps, 3333 in older apps. The npm run env:pull script in your app sets
it for you.
How the project is chosen
The first of these that applies:
--projectorSTARDECK_PROJECT_ID.- The app's
stardeck.project.json. - The project you last picked in this repo.
- A prompt, if there's a terminal. Otherwise the pull fails.
Link an app to its project
New apps have a committed stardeck.project.json naming their project per Stardeck server. Older
apps don't. To add one, sign in and run this from the app's root, then commit the file:
npx @stardeckai/cli link --project my-app- If you forked the repo yourself on GitHub, it still names the original app. Add
--force. - A malformed file, or one with no entry for your server, stops the pull.
--projectoverrides it. - An app nested in a larger repo uses its own file.
CI
Use an Admin org API key from Settings → API Keys:
STARDECK_API_KEY=sk-org-... STARDECK_PROJECT_ID=my-app npx @stardeckai/cli env pull --port 3383What gets pulled
Your sandbox's variables, plus these local ones:
| Variable | Value |
|---|---|
BASE_URL, NEXT_PUBLIC_BASE_URL | http://localhost:<port> |
DATABASE_URL | Your sandbox data store |
DEPLOYMENT_ID, DEPLOYMENT_SECRET | Your own local deployment, revocable on its own |
STARDECK_AI_API_KEY | Only when Settings → Generative AI → AI Proxy is on |
NEXT_PUBLIC_ENVIRONMENT | development |
Webhooks, scheduled jobs and cross-app calls go to your cloud sandbox, never localhost. Test
those in the cloud sandbox.
env pull options
Flags win over environment variables.
| Flag | Environment variable | Default |
|---|---|---|
--control-plane-url | STARDECK_CONTROL_PLANE_URL | https://www.stardeck.ai |
--api-key | STARDECK_API_KEY | |
--project | STARDECK_PROJECT_ID | See above |
--branch | STARDECK_BRANCH_ID | main branch |
--data-store-branch | STARDECK_DATA_STORE_BRANCHES | sandbox routing |
--port | 3000 | |
--out | .env.local | |
--verbose | off (prints names, never values) |
--data-store-branch <store>=<branch> (repeatable) points one store at a branch for this pull only.
Protected branches are refused; fork one instead.
Other commands: stardeck logout, stardeck whoami.
Troubleshooting
For Not logged in, project selection, 403 and 404 errors and missing services, see
Troubleshooting: running your app locally.
Next: Ship a change
Push a branch, deploy a preview, then deploy production from your terminal