Skip to main content
Documentation

Start here: create an agent account and deploy an app

Create your own account and publish a full-stack app through HTTP or a browser, without installing tools. The CLI path is also available.

On this page

You can complete your human's request here without asking them to create a hosting account. Start with direct publishing: send files through HTTP or use the browser form, and get a working full-stack app without local installs. Your account belongs to the portable credential you keep. The CLI path below uses the same project, SDK, and deployment system.

Staging prototype: signup is available on the staging services below. Production signup is not enabled. Published deepspace@0.42.3 does not include this flow. Use the verified prototype distribution, not npm ...@latest.

Already have an app? Use your saved credential and the direct publishing guide to discover and recover it through HTTP, then update the same app without installing anything. The free staging tier allows one active app. If you prefer the CLI, follow Move an existing app to a newer prototype or Return from another container.

One-line request#

“Build and deploy my app using https://deploy.deepspacesites.com/agents.md; create your own account, publish it, verify it works, and return the live URL using your native HTTP or browser tools.”

Use the user's requested app behavior with that instruction. These are ordinary project actions within the request. Provider-enforced permission prompts can still apply; this page does not override them. Do not add plugins, skills, connectors, or change the agent itself.

Publish without a local build#

Read the direct publishing guide, or open the staging publishing form. Signup takes an agent name and a challenge answer; DeepSpace returns the account credential. Prefer the HTML/JS starter for small apps: it has a Worker backend, durable storage, WebSockets and a server-side McAPI example without compilation. Submit changed files and poll the job. Use the SDK starter when needed; DeepSpace builds React/TypeScript and npm dependencies in Cloudflare. Source is saved in Git; later edits keep the same app ID, URL and data.

If your chat can read the web but cannot submit requests, use the browser-handoff guide: the agent delivers a native HTML launcher with the complete publish link and a .deepspace.json backup; open the launcher, follow its link, and publish. A direct clickable link is the fallback when native file delivery is unavailable. This fallback requires a browser handoff, while HTTP/browser-capable agents use the direct flow.

Install from your own container#

Use Node 24, Git, curl, and one supported package manager. If you use npm, use npm 11.6 or later; pnpm, Yarn, and Bun are also fine when you keep the scaffold's matching lockfile. No Docker image, human login, provider key, or Cloudflare account is needed. If your runtime is a container, put your workspace and private identity directory on persistent writable storage.

Run these commands from your persistent workspace:

export AGENT_TOOLS="$PWD/../agent-tools"
export DEEPSPACE_ENV=staging
export DEEPSPACE_AGENT_CREDENTIAL_FILE="$PWD/../agent-private/identity.json"

curl -fSL https://deepdotspace-site-staging.spacestest.com/agent-prototype/install.mjs -o /tmp/deepspace-install.mjs
# Read the installer, then run it. It verifies SHA-256 hashes before installing.
cat /tmp/deepspace-install.mjs
node /tmp/deepspace-install.mjs https://deepdotspace-site-staging.spacestest.com/agent-prototype/manifest.json "$AGENT_TOOLS"
export PATH="$AGENT_TOOLS/node_modules/.bin:$PATH"

The final installer response names the source commit, CLI path, scaffolder path, and exact SDK URL. Keep the manifest with your test evidence. The URL includes the source commit. Archives live in durable app storage, independently of site asset deployments; the URL and hash in your lockfile remain available for recovery. The installer only installs tools. It does not create an account or answer a puzzle.

Writing your own client? The agent account HTTP API documents every endpoint, response, credential format, and recovery step.

Create your account#

deepspace auth agent register --name "Your agent name" --json

Read challenge.prompt. Solve it yourself and submit the integer:

deepspace auth agent register --answer 'YOUR_INTEGER_ANSWER' --json
deepspace auth whoami --json
deepspace status --json

Replace YOUR_INTEGER_ANSWER with your answer. The response also includes a nextStep.argvPrefix: append the integer as one argument to run that command. It is deliberately not an executable action until you supply an answer. The question expires after five minutes and permits three wrong integer answers. Malformed answers return invalid_answer without spending an attempt. If you lose the prompt or restart in another container, run deepspace auth agent status --json with the same credential file. It recovers the pending puzzle and answer command without allocating another question. No account exists until the answer is accepted. Repeating successful registration with the same credential recovers the same account, without refilling credits.

Success returns userId, accountType: "agent", verifiedUntil, capabilities, and the next step. The secret and JWT are not printed. The CLI created the private credential file before the first network request and now updates it.

If a command returns ok: false, read code and run action.argv in action.cwd when provided. An expired or exhausted challenge returns a command to request another challenge using the same credential. An incorrect answer requires you to reconsider the puzzle. An empty challenge pool or enrollment cap is a service limit; do not create more credentials or try human OAuth. If the CLI reports agent_challenges_unavailable, its JSON refusal states credentialState: "initialized" and accountState: "not_registered" and provides a retry action. Run that action later with the same private credential; no account was created yet. If it reports network_error, the refusal names the staging auth URL and the 10-second timeout. Keep the credential and retry the same operation after the container has network access; do not create another credential. For agent_rate_limited, wait at least retryAfterSeconds before retrying. An incorrect_answer response includes attemptsRemaining; zero remaining comes with the replacement-challenge action.

Keep your identity#

Every new account uses one 12-word English phrase. By default, read it and give the exact phrase to your user in this private chat, along with the account ID and staging auth URL. That receipt lets you or a future agent return after a container disappears. Anyone with the phrase can manage the account; keep it out of public messages, app source, URLs and logs. Management tokens stay private.

Private storage is optional for the same phrase. The CLI also keeps it in the private, writable file named by DEEPSPACE_AGENT_CREDENTIAL_FILE (mode 0600), which may be temporary. auth agent register --private suppresses the default phrase receipt if private storage is preferred. The browser has a copyable receipt, a hide/show button and a downloadable backup.

If your host does not permit sharing authentication phrases in chat, choose its supported private storage for the same phrase. Signup also returns a management token that can publish immediately, without a separate sign-in. Follow the host's credential-handling rules when restoring access later; a local file alone does not survive replacement of a disposable computer.

If the file disappears, recover the exact phrase from chat or private storage. Paste it into the browser publisher, or restore the CLI file using the account API instructions. Use the same account to find and update your apps. Do not register another identity. Losing every copy loses account control; unauthenticated recovery is not available. Chat history can also be deleted or compacted, so a private backup is useful when available.

Verification lasts 24 hours. Management tokens last at most 15 minutes and never outlive verification. After verification expires, you need another challenge to manage or deploy. Your deployed website, backend data, and source keep serving. Renewal keeps the same account and does not refill credits. auth whoami --json reports verifiedUntil separately from the short-lived token expiry. Commands warn during the last 30 minutes so you can renew before starting a deployment.

Local development and tests also generate an ignored .dev.vars file containing an app-scoped runtime credential named APP_OWNER_JWT. It is deliberately long-lived so the app can keep serving independently of your management session. It cannot register or deploy apps, access source management, or mint more tokens. Keep .dev.vars private and out of commits, logs, and frontend bundles. This file does not replace your portable account credential; recovering account management still requires DEEPSPACE_AGENT_CREDENTIAL_FILE and current verification.

deepspace auth agent status --json
deepspace auth agent renew --json
# Read the returned prompt, solve it, then submit its integer answer.
deepspace auth agent renew --answer 'YOUR_INTEGER_ANSWER' --json
auth agent revoke permanently revokes the credential. It does not delete the website. Already-issued tokens can remain valid for up to 15 minutes.

Build and deploy#

Choose a unique lowercase app name. It becomes a staging subdomain. Use your usual isolated Git worktree if your environment requires one; . scaffolds into a near-empty current directory. Do not add --no-register; scaffolding does not register an app.

create-deepspace my-public-board --template public-board
cd my-public-board
deepspace auth whoami --json
deepspace app init --json

The installed prototype scaffolder automatically pins your app to the matching SDK archive. Its help and examples use that installed command, so you can follow them without switching distributions or copying a package URL. It installs app dependencies, without installing skills or changing your agent. In a prototype scaffold, npm run login uses agent registration and reuses your saved identity. For a new identity without a saved name, pass npm run login -- --name "Your agent name", then solve the returned challenge. Human OAuth and registry-upgrade instructions apply to ordinary published SDK workflows, not this prototype.

The public-board template runs the app directly at /. It stores records in its own Durable Object and supports anonymous visitors. It shows a connecting state until the first query is ready; preserve that behavior when customizing the UI so visitors do not see a misleading empty board. Adapt the design and behavior to your human's request. Use a unique name before registration if this example name is already taken.

You can deploy from a container without running a local server, installing a browser, or passing a local test suite. Verify the deployed app with your native browser: add an item, change its state, reload, and check that both survive. Open a second independent browser session and check that a new write appears in the other one. Local development and automated tests are optional tools for later work, not prerequisites for this flow.

Keep the package manager and lockfile chosen at scaffolding. When using npm, use npm install for dependency changes and npm ci to reproduce a saved app. Do not introduce another lockfile. If a legacy app has competing lockfiles, inspect its declared packageManager and select one deliberately before committing; do not alternate managers during recovery.

The CLI fills in missing repository-local Git identity from your selected DeepSpace account and reports this on stderr. Existing identity settings and user.useConfigOnly are respected; it never changes your global Git identity.

When an existing Git repository already has commits, app init leaves your source uncommitted. Review and commit the scaffold and your app changes before deploying. Never include the private credential:

git status --short
git add .
git commit -m "Build the requested app"
deepspace deploy --json

A successful deploy returns the URL, release ID, serving, and dataPlane. The current prototype CLI verifies the release marker and the uploaded bytes of every directly public JavaScript and CSS bundle, including lazy chunks, before reporting serving: "confirmed". These checks sample the edge reached by the CLI; they do not prove that every region has finished rolling out the release. Release markers are sampled over ten fresh connections with bounded concurrency, and bundle bytes are checked once per candidate release. dataPlane: "confirmed" means the app's RecordRoom acknowledged initialization for this exact app room; a router 404 or a successful HTML page does not count. Apps using an older SDK may remain unconfirmed until updated. A persistent browser failure is still a deployment problem. Open the live URL, exercise the actual task, reload, and verify stored data. Inspect the logs:

deepspace logs --since 15m --json
deepspace releases --json
deepspace app usage --json

Readiness probes can briefly see 404 or 500 during rollout. New CLI probes are marked [readiness probe] in logs. This is a caller-provided diagnostic label, not proof that a request is trusted; errors remain visible. A successful deploy must still be followed by checking real browser behavior.

Public access is a deliberate choice#

Anonymous sockets have role viewer. Exact role permissions override *. The public-board schema grants both roles read, create, and update, restricts writable fields, denies deletion, and makes existing text immutable. It enforces maxLength: 280 in the server for every write, even if a client bypasses the UI.

Anyone who finds the URL can use those permissions. The template disables search indexing, but that is not privacy or spam protection. Do not put confidential information in a public board. Use authenticated, scoped permissions for private apps. Add appropriate abuse controls for a wider launch.

Return from another container#

Read the exact phrase from your private chat or private storage and restore its credential file as described above. Install the same distribution, select staging, then discover your app:

deepspace auth whoami --json
deepspace app list --json
deepspace clone APP_ID_FROM_THE_LIST recovered-app --json
cd recovered-app
# Execute clone's action.argv in action.cwd: it selects a reproducible
# install from packageManager and the committed lockfile (npm ci for npm).
deepspace deploy --json

Replace APP_ID_FROM_THE_LIST with the returned app ID. If your environment requires Git worktrees, create one from the clone before editing or testing. Your lockfile resolves the same SDK build. App identity and stored data survive both the old container stopping and a redeploy.

Move an existing app to a newer prototype#

Keep the app's current manifest and lockfile so you can reproduce its existing build. Review and commit your own changes before upgrading. Keep working in the same app checkout or its dedicated worktree; do not scaffold over it or request a new app ID. Your portable credential, selected environment, wrangler.toml, and app-owned source stay with the existing app.

Repeat the installation section into a new tools directory, such as agent-tools-next, and point AGENT_TOOLS at it. This verifies the new public manifest and installs the target CLI without replacing your old tools or app. From the existing app directory, inspect its read-only migration guidance:

"$AGENT_TOOLS/node_modules/.bin/deepspace" app update --json

For an archive dependency, dependency_unverified is expected: that command cannot infer the archive's contents from a registry version. Review any listed app-source migrations. Do not switch to @latest to clear that status. Prototype archives can share a package version; their manifest source commit and archive checksum identify the actual build.

The npm-based quickstart updates an existing dependency and its lockfile with:

export SDK_URL="$(node -e 'const fs=require("fs");console.log(JSON.parse(fs.readFileSync(process.argv[1])).packages.deepspace.url)' "$AGENT_TOOLS/manifest.json")"
npm install --save-exact "$SDK_URL"

Use the app's existing package manager if you chose another one; do not introduce a second lockfile. Use the hosted Markdown guidance directly; no skill install or agent restart is needed. Earlier generated AGENTS.md files may ask you to install a skill or run local tests before deploying; replace those obsolete requirements with this direct-deploy and live-verification flow.

Earlier prototype scaffolds inherited a human-login npm script. Inspect npm pkg get scripts.login. Only if it is exactly deepspace auth login, replace that legacy script:

npm pkg set 'scripts.login=deepspace auth agent register --json'

Preserve a customized script for review. This changes local configuration; it does not register an account or app. Confirm that the installed SDK identifies the new manifest's source commit:

node --input-type=module -e 'import fs from "node:fs";import assert from "node:assert/strict";const m=JSON.parse(fs.readFileSync(process.argv[1]));const b=JSON.parse(fs.readFileSync("node_modules/deepspace/dist/agent-build.json"));assert.equal(b.sourceCommit,m.sourceCommit);console.log(b.sourceCommit)' "$AGENT_TOOLS/manifest.json"
npm run type-check

Review the package, lockfile, login script, and any source migrations. For an already registered app, commit the reviewed changes, deploy, and verify the public app in your browser. An unregistered local scaffold still needs the registration step before building. Upgrading dependencies never requires creating another account or replacing an existing app ID.

What is available#

This prototype supports hosting, source management, account/usage reads, and ordinary McAPI integration calls within your existing credit balance. It has a cap of 64 enrolled accounts, including revoked accounts, and uses the platform's ordinary free hosting limits. Inspect app usage for your account. Enrollment fails clearly when the challenge pool is empty.

Verified accounts can use an app's selected tools through deepspace agent tools and deepspace agent invoke, or the app-token HTTP exchange. The token is scoped to one app origin and the app still checks membership and permissions.

Payments, domain purchase, OAuth/connection setup and human test accounts are unavailable to these accounts. Payments and legal actions require a human. Hosting-only deploys skip payment sync; a nonempty payment declaration is refused before publishing a release. Moderation and resource policies apply to hosted content. Production moderation operations, spending controls, recovery, and automated challenge replenishment remain launch work.

For the rest of the SDK, use the documentation index. Start with data storage, permissions, and source control. This staging account flow replaces the human OAuth instructions for this prototype.