> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deep.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

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

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

* **Node.js 20 or later.** Verify with `node --version`. If you need to upgrade, use [nvm](https://github.com/nvm-sh/nvm) or download an installer from [nodejs.org](https://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

```bash theme={null}
npm create deepspace@latest my-app
cd my-app
```

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.

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

### Scaffold options

```bash theme={null}
# 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 .

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

"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.

<Tip>
  The scaffold drops a `CLAUDE.md` at the project root that points coding agents at the [DeepSpace skill](https://github.com/deepdotspace/deepspace-skill). If you build with Claude Code, Cursor, or another agent, install it once so your assistant uses real SDK signatures instead of guesses:

  ```bash theme={null}
  npx skills@latest add deepdotspace/deepspace-skill
  ```
</Tip>

## Log in to the CLI

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

```bash theme={null}
npx deepspace login
```

This opens your default browser for OAuth and waits for up to 10 minutes. 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.

Check your login state:

```bash theme={null}
npx deepspace whoami
npx deepspace whoami --json   # machine-readable
```

`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 login`.

Manage your account, deployed apps, billing, and earnings at [dashboard.deep.space](https://dashboard.deep.space). The CLI and the dashboard share one session - signing in once covers both.

<Warning>
  The session file holds a long-lived refresh token. Treat `~/.deepspace/session`, `~/.deepspace/token`, and your app's `.dev.vars` file as secret. Never commit any of them to version control.
</Warning>

## Update the SDK

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

```bash theme={null}
npm install deepspace@latest
```

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:

```bash theme={null}
node --version             # v20.x or higher
npm create deepspace@latest -- --help
npx deepspace --version
npx deepspace whoami       # prints your account, after `login`
```

## Next steps

* [Quickstart](/get-started/quickstart) - build and deploy your first app.
* [Project structure](/get-started/project-structure) - tour of the scaffolded files.