stardeck env pull fetches them for you and writes a local .env.local, so npm run dev boots a real, wired-up app on localhost — reading and writing the same sandbox data your cloud sandbox uses.
These two guides go hand in hand. Connect Claude Code lets
Claude reach platform services over MCP to help you build. This page lets your running app
reach them over ordinary environment variables to run. Set up both and you have a full local
loop: edit with Claude, run the result locally.
How it works
Both halves talk to the same platform, through different doors. Claude Code connects over MCP for its tools; your running app reads pulled env vars and calls the platform’s SDKs and services directly.stardeck env pull asks the platform to assemble your project’s sandbox environment, rewrites the app’s own URL to point at your local dev server, and returns the result. A few things worth knowing up front:
- It’s your sandbox environment. You get the sandbox data store, secrets, and storage — the same ones the cloud sandbox uses. Writes you make locally land in that shared sandbox, not production.
- Your own local identity. The pull registers a per-developer local deployment for you, with its own secret that authenticates your app’s calls back to the platform. It’s separate from the sandbox and production deployments, and can be revoked without touching them.
- Secrets land in
.env.local. The file holds real, decrypted values. It’s written readable only by you and is already git-ignored — never commit it.
Before you begin
You’ll need:- A local checkout with dependencies installed — follow Connect Claude Code → Before you begin and Installing dependencies first.
- A Stardeck account with access to the organization and project you want to run locally. Env pull returns decrypted secrets, so your account must have an Admin organization role (the same effective gate as an admin-scoped org API key).
Quick start (login + env pull)
1
Sign in with the CLI
From any directory:This opens your browser, signs you into Stardeck, and stores a user-bound CLI credential on your machine. The control plane defaults to
https://www.stardeck.ai; override with --control-plane-url or STARDECK_CONTROL_PLANE_URL when needed.2
Pull the environment
From your app’s root:The CLI prompts you to pick an organization, then a project, and writes Add
.env.local. It remembers that selection for this repository in your local CLI config file (~/.config/stardeck/config.json on macOS/Linux — not your credentials, and nothing is written into the repo).Pass --port to match your dev server’s port so the app’s own URL is correct. The default is 3000; many Stardeck apps use 3333:--verbose to print the variable names it wrote (never the values).3
Run the app
localhost, reading and writing your sandbox data store, using your sandbox secrets and storage.Newer apps ship an
npm run env:pull script that wraps the CLI. It reads the same flags and
environment variables documented below.Interactive selection and remembered defaults
When you’re logged in and don’t pass--project, stardeck env pull:
- Uses explicit flags first, then environment variables (
STARDECK_PROJECT_ID, etc.). - Falls back to the last org/project you chose in this repository (stored in your local CLI config, keyed by repository path).
- Otherwise prompts interactively: organization, then project.
--project <id|slug> to skip project prompting. With OAuth login, the slug is resolved against projects you can access in the selected organization.
If stdin is not a TTY (CI without flags), the command fails with an actionable message — use --project or switch to API key mode.
API key mode (CI / noninteractive)
For automation, export an Admin org API key and project explicitly. Credentials are never written into the repo.What gets pulled
The pulled.env.local is your sandbox environment with local overrides. Notably:
Storage, payments, data store, and any environment variables you’ve set for the sandbox come through as well, so features that depend on them work without extra setup.
What local dev does not do
Running locally covers everything your app initiates — page loads, data store queries, SDK calls, storage. It does not receive traffic the platform sends to your app. You’re also working against shared sandbox data. It’s not a throwaway database — a teammate’s sandbox, the in-product agent, and your local app all read and write the same store. Be deliberate with destructive changes, the same as you would in the cloud sandbox.Command reference
Authentication
stardeck env pull
Every option can come from a flag or an environment variable; flags win when both are set.
The
npm run env:pull script sets --port to your app’s dev port for you; when running the CLI directly, pass --port yourself.
Troubleshooting
Not logged in
Run stardeck login, or use --api-key / STARDECK_API_KEY for CI.
Cannot select a project interactively because stdin is not a TTY
Pass --project / STARDECK_PROJECT_ID, or use API key mode.
403 — env pull requires an admin-scoped organization role / API key
Pulling an environment returns decrypted secrets. You need an Admin role on your Stardeck account (OAuth login) or an Admin org API key.
404 — Project not found / Branch not found
- The project ID or slug doesn’t match a project you can access in the selected organization.
- For a branch, the name must exist on that project. Omit
--branchto fall back to the main branch.
The app starts but can’t reach the data store or a service
Your.env.local may predate a change to the sandbox — for example a new environment variable or a rotated secret. Re-run stardeck env pull to refresh it, then restart npm run dev.
Next steps
Connect Claude Code
The other half — give your local Claude Code tools that reach platform data
Tools & Permissions
What Claude can do through the gateway, and how the role controls it
Cloud Sandbox
Test inbound traffic — webhooks, schedules, cross-app calls
Environment Variables
Set the sandbox variables your app pulls