Skip to main content
Documentation
Get started

Installation

Set up your environment, create an account, and log in to the CLI.

On this page

You don't install DeepSpace globally. The CLI ships inside the deepspace package, which is added to every new app by the scaffolder. The only thing you need on your machine ahead of time is Node.js.

Prerequisites#

  • A supported Node.js line: 22.15+, 24, or 26. The exact engines range is >=22.15.0 <23 || >=24 <25 || >=26 <27 - the odd-numbered lines (23, 25) are excluded. Verify with node --version. If you need to switch versions, use nvm or download an installer from nodejs.org.
  • npm, pnpm, or yarn. Examples in these docs use npm; substitute your favorite if you prefer.
  • A GitHub or Google account. Used for signing in to the CLI and your deployed apps. There's no separate DeepSpace account.

You do not need a Cloudflare account. DeepSpace deploys to a shared Workers for Platforms namespace operated by the platform. If you want a custom domain, you'll buy it through the CLI (Cloudflare Registrar or Porkbun under the hood) - no DNS setup on your side.

Create a new app#

npm create deepspace@latest my-app
cd my-app
bash

This:

  1. Downloads the latest create-deepspace package on demand (no global install).
  2. Scaffolds a Vite + React app with the worker and Durable Objects pre-wired.
  3. Installs deepspace and the starter's dependencies.
  4. Initializes a git repository.
  5. Runs deepspace app init to register the app and mint its id, then makes the initial commit.

The scaffold takes about 30 seconds. You'll have a working app at the end, but npx deepspace dev start won't start until you've logged in.

Which account the app registers under#

Step 5 registers the app under whatever login the shell already holds, on the plane DEEPSPACE_ENV selects (production when it is unset) - the scaffolder does not ask. It says so as it goes, naming the plane, the account, and the id:

App identity registered on production to you@example.com: app_01J…

Run npx deepspace auth whoami first if more than one account could be logged in on this machine. If registration is attempted and fails, the scaffolder prints the CLI's own refusal and exits nonzero, so a chained npm create … && cd … && npx deepspace deploy stops instead of deploying an app with no identity; recover with npx deepspace auth login and npx deepspace app init in the app directory (app init also makes the initial commit).

To scaffold now and register later - the right move when the shell's login is not the intended owner - pass --no-register:

npm create deepspace@latest my-app -- --no-register
cd my-app
npx deepspace auth login          # as the intended owner
npx deepspace app init            # mints the id and makes the initial commit
bash

Skipping is a deliberate choice, so it exits clean. Until app init runs the app has no id and no initial commit.

Scaffold options#

# Interactive prompt-driven mode
npm create deepspace@latest -- --interactive

# Scaffold into the current directory (must be near-empty)
mkdir my-app && cd my-app
npm create deepspace@latest .

# Scaffold without registering an app id
npm create deepspace@latest my-app -- --no-register

# Print help
npm create deepspace@latest -- --help
bash

The scaffolder is non-interactive by default (--interactive opts in), so there is no --yes flag - passing one is refused with an explanation rather than treated as unknown.

"Near-empty" means the target directory contains only boilerplate (.git, .gitignore, LICENSE, any *.md, etc.). Anything else triggers a guardrail to prevent overwriting an existing project.

Log in to the CLI#

Every CLI command that talks to the platform - dev start, deploy, integrations invoke, test accounts, and the rest - requires a session. Plan to log in once before your first npx deepspace dev start.

npx deepspace auth login
bash

This opens your default browser to sign in with GitHub or Google and waits for up to 10 minutes. DeepSpace accounts are OAuth-only - you never set a password, and your first sign-in creates the account. After you authorize, the CLI writes two files into ~/.deepspace/:

  • ~/.deepspace/session - the long-lived refresh token used to mint new JWTs.
  • ~/.deepspace/token - the current short-lived JWT, refreshed automatically by other commands.

The same session covers every DeepSpace app on the machine - you don't log in per project. It also covers coding agents you run here: they read the same file and act as you. To do that from a container or CI, see agents and CI.

Check your login state:

npx deepspace auth whoami
npx deepspace auth whoami --json   # machine-readable
bash

whoami refreshes the short-lived JWT on demand, so an expired token is handled silently. If ~/.deepspace/session is missing, it prints "Not logged in." and exits 1. If the session can no longer be refreshed, it prints "Session expired." and exits 1. In either case, re-run npx deepspace auth login.

Manage your account, deployed apps, billing, and earnings at dashboard.deep.space. The CLI and the dashboard share one session - signing in once covers both.

Update the SDK#

DeepSpace ships frequently. To pull in the latest SDK and CLI, run:

npm install deepspace@latest
bash

The CLI and the SDK are the same package - bumping the version updates both.

Verify your setup#

You're ready to build when all of these succeed:

node --version             # v22.15+, v24.x, or v26.x
npm create deepspace@latest -- --help
npx deepspace --version
npx deepspace auth whoami       # prints your account, after `auth login`
bash

Next steps#