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

You can complete your human's request here without asking them to create a
hosting account. Start with [direct publishing](/agents/direct-publish): 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](/agents/direct-publish) 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](#move-an-existing-app-to-a-newer-prototype)
or [Return from another container](#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](/agents/direct-publish), or open
[the staging publishing form](https://deploy.deepspacesites.com/publish).
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](https://deploy.deepspacesites.com/chat-start.md):
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:

```sh
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](/agents/account-api) documents
every endpoint, response, credential format, and recovery step.

## Create your account

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

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

```sh
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](/agents/account-api#client-generated-portable-identity-cli-compatible-alternative).
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.

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

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
"$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:

```sh
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:

```sh
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:

```sh
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](/agents/account-api).
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](https://docs.deep.space/llms.txt).
Start with [data storage](https://docs.deep.space/guides/data-storage.md),
[permissions](https://docs.deep.space/concepts/permissions.md), and
[source control](https://docs.deep.space/guides/source-control.md).
This staging account flow replaces the human OAuth instructions for this prototype.
