# Deepspace

> >

- **Type:** Skill
- **Install:** `agentstack add skill-deepdotspace-deepspace-skill-deepspace`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [deepdotspace](https://agentstack.voostack.com/s/deepdotspace)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [deepdotspace](https://github.com/deepdotspace)
- **Source:** https://github.com/deepdotspace/deepspace-skill/tree/main/skills/deepspace
- **Website:** https://deep.space

## Install

```sh
agentstack add skill-deepdotspace-deepspace-skill-deepspace
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

DeepSpace builds and deploys real-time collaborative apps on Cloudflare Workers in one package — auth, RBAC, live data subscriptions, messaging, payments — and ships them to `.app.space`.

Two hard gates come first: the user must be **logged in**, and the app must be **scaffolded** rather than hand-built.

## 1. Log in first

Every command that *runs* anything — `dev`, `test`, `deploy` — needs a signed-in DeepSpace account. There's no local-only mode: `dev` connects to deployed dev workers.

```bash
npx deepspace whoami     # probe (--json for agents)
npx deepspace login      # only if whoami says signed-out
```

`login` opens a browser OAuth tab and polls up to 10 minutes — **pause and let the user finish it at the keyboard.** Don't wrap it in `timeout` / `sleep` / `kill` (that aborts the OAuth poll), and don't ask for their password. One login covers every app on the machine. Full login + CLI contract → `references/cli.md`.

## 2. Scaffold the app

```bash
npm create deepspace@latest    # no login needed;  seeds the dir AND wrangler `name`
cd                             # (= deploy subdomain). Edit it later in wrangler.toml, not by moving the dir.
npx deepspace dev                        # Vite + worker, HMR on localhost:5173
```

The two import surfaces:

```typescript
import { RecordProvider, RecordScope, useQuery, useMutations, useAuth } from 'deepspace'        // frontend
import { RecordRoom, verifyJwt, CHANNELS_SCHEMA } from 'deepspace/worker'                        // worker
```

## 3. Build — discover before you hand-build

Run both catalogs *first thing* in any build — *never* skip on a hunch that nothing fits. The one-line names can't tell you what a block does; only `add --info` / `integrations info` can, so don't rule one out from the list alone.

```bash
npx deepspace add --list           # 17 UI features — landing, topbar, file-manager, kanban, messaging… with auto-wired schema/routes/nav
npx deepspace add --info     # inspect a feature before installing
npx deepspace add            # install it
npx deepspace integrations list    # external APIs (weather, LLMs, stocks, sports…) via owner-pays proxy, no keys to manage
```

When you build by hand, where things live (load the matching reference from the table below as you touch each):

| Path | Purpose |
|---|---|
| `src/schemas.ts` + `src/schemas/` | Collection schemas. Ships `usersSchema` (required, don't rename) + `settingsSchema`. |
| `src/pages/` | File routes (generouted). Top level = static, `(app)/` = providers + data hooks, `(app)/(protected)/` = sign-in gated. `_app.tsx` is the root shell — **extend, don't replace.** → `references/auth.md` |
| `src/themes.ts` + `src/themes.css` | Theme tokens, set on ``. Ships two placeholders (`slate` dark default, `paper` light example) — **create the app's own theme; don't ship a placeholder.** → `references/uiux.md` §2 |
| `src/constants.ts` | `APP_NAME`, `SCOPE_ID`, role re-exports. |
| `worker.ts` | Hono worker; `__DO_MANIFEST__` declares the DO classes. AI chat routes live in `src/ai/chat-routes.ts`. → `references/architecture.md` |

The three hooks you'll reach for constantly:

```typescript
const { records, status } = useQuery('items', { where: { status: 'published' }, orderBy: 'createdAt' })
const { create, put, remove } = useMutations('items')   // create returns the new recordId
const { isSignedIn, isLoaded } = useAuth()
```

Records are envelopes — `{ recordId, data: T, createdBy, createdAt, updatedAt }`. User fields live under `.data` (`r.data.title`, never `r.title`). `put(recordId, patch)` takes a `Partial` and merges server-side. For any other hook (messaging, presence, Yjs, canvas, cron, jobs), read `references/sdk-reference.md` before guessing.

## 4. Test, then deploy

```bash
npx deepspace test       # after runtime-affecting changes; multi-user features need a 2-user spec → references/testing.md
npx deepspace deploy     # → .app.space
npx deepspace deploy --env staging   # → isolated staging instance (v0.4+); rehearse risky changes first
npx deepspace kill       # if your own dev port is stuck (never kill a sibling session's)
```

Deploy's subdomain is `wrangler.toml`'s `name`, not the folder. On a **first** deploy, clear the pre-deploy checklist in `references/uiux.md` §5 (real home replacing the placeholder stub, an own theme created — not `slate`/`paper`, no browser-default primitives). Deploy mechanics, the `.dev.vars` contract, secret handling, and **multi-env / staging (`--env`, incl. the client-`APP_NAME` sync gotcha)** → `references/deploy.md`. The full CLI catalog (`integrations`, `test-accounts`, `screenshot`, `domain`, `library`, dev/kill flags) → `references/cli.md`.

App secrets live in the platform's encrypted store, not in files: `npx deepspace secrets set KEY=value` — no setup step; worker code reads `env.KEY` in dev and prod alike, and the store (keyed by the app's immutable `DEEPSPACE_APP_ID` in `wrangler.toml`) is the **only** deploy input — never hand-edit `.dev.vars`. → `references/secrets.md`. The id is the app; the `name` is just the URL (renames, forking a cloned repo with `init --new-id`, ownership transfer → `references/app-identity.md`). Teammates the owner adds with `npx deepspace collaborators add ` can deploy the app and manage its secrets (not undeploy or transfer it). → `references/collaborators.md`.

## Load a reference when you reach its surface

Before editing files, scan this table and `Read` every row whose trigger matches — in the same turn, before the first edit. Each reference also declares its own "Load when…" gate on line 1; that gate is authoritative.

| Reference | Read before |
|---|---|
| `references/workflow.md` | Starting an end-to-end app build — a new product, a clone, or any multi-feature request. |
| `references/cli.md` | The login contract, the full CLI command catalog (`dev`/`kill`/`integrations`/`test-accounts`/`screenshot`/`library`), and the `test` command. |
| `references/deploy.md` | Deploy mechanics, the `.dev.vars` contract, secret handling, and multi-environment / staging deploys (`deploy --env`). |
| `references/secrets.md` | Managing app secrets, using `npx deepspace secrets`, migrating a legacy `.dev.vars` app, configs/environments, or generated-cache behavior. |
| `references/app-identity.md` | App ids (`DEEPSPACE_APP_ID`), forking a cloned repo (`init --new-id`), renames, `apps`/`undeploy`, ownership transfer. |
| `references/legacy-migration.md` | A pre-app-id app (name-based id in `apps`, no `DEEPSPACE_APP_ID`), or your own deploy failing with "name … taken by another app". |
| `references/collaborators.md` | Adding teammates to an app, deploying an app you don't own, or a 403 on deploy/secrets as a non-owner. |
| `references/sdk-reference.md` | Any hook / type / export beyond `useQuery` / `useMutations` / `useAuth` — messaging, game rooms, presence, Yjs, canvas, R2. Open before `node_modules/deepspace/dist/*.d.ts`. |
| `references/schemas.md` | Defining a collection, picking a permission rule, debugging "why can't this user see/edit X." |
| `references/auth.md` | Choosing the auth model (public / gated / mixed), adding ``, customizing the sign-in fallback. |
| `references/architecture.md` | Editing `worker.ts`, adding DO classes / cross-app scopes (`workspace:*` / `dir:*` / `conv:*`), the identity-strip security model, app-name rules. |
| `references/server-actions.md` | Privileged writes that bypass the caller's RBAC. |
| `references/ai-chat.md` | A streamed chat UI with tool use over the app's records. |
| `references/cron.md` | Scheduled tasks via `AppCronRoom` + `useCronMonitor`. |
| `references/jobs.md` | Durable background work via `AppJobRoom` + `useJobs` (AI generation, exports, renders). |
| `references/bindings.md` | Custom Cloudflare bindings (Vectorize / R2 / KV / D1 / Queues / AI / Browser / Hyperdrive), `"auto"` autoprovisioning, per-tenant metering. |
| `references/integrations.md` | Calling external APIs through `integration.post(...)` and the discovery CLI. Itself points to `integrations/livekit.md` (audio/video rooms) and `integrations/google-oauth.md` (Gmail / Calendar / Drive / Contacts) when you reach those. |
| `references/payments.md` | Anything involving money — Stripe, paywalls, subscriptions, pricing, "Upgrade" buttons, tips, refunds. **Never hand-roll Stripe.** |
| `references/domain.md` | Buying / attaching / managing a custom domain. |
| `references/uiux.md` | Theme, home page, primitives, "feels generic" feedback. Before `` / `window.confirm` / `window.alert`. |
| `references/testing.md` | Writing/extending specs, multi-user flows, debugging flaky tests. |
| `references/preview.md` | Using the Claude desktop preview tool (`preview_start`), or when the preview shows stale code / edits never appear — especially inside a `.claude/worktrees/*` worktree. |
| `references/landing-design.md` | Marketing / landing / splash pages. |

## Traps worth knowing up front

- **The scaffold shell is a placeholder, not a design.** The stub home page, minimal nav bar, and `slate`/`paper` themes are deliberately bare — never extend or imitate them as "the house style." Design the app's own look and theme (→ `references/uiux.md`; landing pages → `references/landing-design/`).
- **Scaffold's UI primitives shadow the SDK.** `_app.tsx` uses `ToastProvider` from `src/components/ui/`, not `deepspace`. Importing `useToast` (or any local primitive) from `deepspace` throws at runtime. **Import from `../components/ui`.**
- **Page files belong in `src/pages/`** — generouted scans only there; pages under `src/features//` 404.
- **Data/auth hooks only work under `(app)/`** — providers mount in `(app)/_layout.tsx`, so a top-level (static) page calling `useAuth`/`useQuery` crashes at render. Details: the scaffold's CLAUDE.md § "Static vs dynamic pages" and `references/auth.md`.
- **Don't kill or assume a clean port 5173.** `tests/playwright.config.ts` ships `reuseExistingServer: true`, so if a sibling session already holds 5173 your tests silently run against *its* app. Don't kill another session's processes — use `npx deepspace dev --port 5174` and match `webServer.port` + `use.baseURL` in the config. → `references/testing.md`
- **Never put identity in WebSocket URLs or `/api/*` headers** — the starter strips `userId`/`role`/etc. and re-applies them only from a verified JWT. Caller identity is always the JWT subject. → `references/architecture.md`
- **Preview tool shows stale code / your edits never appear** — if you're editing in `.claude/worktrees/*`, the desktop preview tool serves the MAIN repo, not the worktree. Run `npx deepspace dev` once in the worktree and use the `wt-` preview config it prints. → `references/preview.md`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [deepdotspace](https://github.com/deepdotspace)
- **Source:** [deepdotspace/deepspace-skill](https://github.com/deepdotspace/deepspace-skill)
- **License:** MIT
- **Homepage:** https://deep.space

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-deepdotspace-deepspace-skill-deepspace
- Seller: https://agentstack.voostack.com/s/deepdotspace
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.