# Create and publish an ordinary DeepSpace app You can create your own account and publish a full-stack app through your existing HTTP or browser tools. DeepSpace handles building and Cloudflare deployment. No plugin, local installation, Git client, or human hosting signup is required. This is staging; apps live on spacestest.com. Do not finish with only a source archive or a blocked report. If your code cannot reach this host and you have no interactive browser, read the fresh chat.md link in the unreachable-host bullet below with your web reader in the same reply and return its publish link; the person opens it and presses Publish. ## Choose your existing tool - If you can send HTTP requests, follow the HTTP flow below. - If you have an interactive browser, open https://deploy.deepspacesites.com/publish. Solve signup, load the HTML/JS starter (or the SDK starter when needed), edit a file, choose a subdomain, and publish. The editor handles the same API. - A web reader such as web_fetch or a search tool can read pages; that is not an interactive browser or a POST client. If these are your only web tools, go directly to the self-contained chat guide below. Otherwise check your existing code or browser tools. If neither can write, follow the self-contained guide at https://deploy.deepspacesites.com/chat-start.md for a source-carrying link that the person can open and publish without installations or hosting signup. This requires a browser handoff; do not claim autonomous deployment. - If your code tool cannot reach this host (DNS failure such as "Could not resolve host", an egress allowlist or proxy refusing it, often HTTP 403 from the proxy, or a connection error) and you have no interactive browser, do not stop at a blocked report. In the same reply, read https://deploy.deepspacesites.com/chat.md?kind=raw&refresh=3ae6ad51-2a67-4e8f-8386-e77316ba8343 with your web reader (or a URL with your own new random refresh value) and deliver its publish link or launcher file. Say plainly that publication needs the person to open it. https://deploy.deepspacesites.com/chat-start.md explains the same path at more length. Fresh signup starts with a name and a challenge, not an existing password or a browser sign-in handoff. Use the management token returned by signup immediately; a separate sign-in is unnecessary. If your host does not permit sending an account phrase in chat, keep the same phrase in its supported private storage and continue publishing. Respect your host's credential-handling rules. A browser user can retrieve their own receipt with Download credential backup; a file on a disposable agent computer alone is not a durable backup. Bound individual auth/HTTP requests (15 seconds is a useful starting point). If a native tool stalls before returning an HTTP result, cancel that call when supported and use another available native tool. Keep any existing enrollment IDs, account and publication job; do not restart signup or publication just because observation stalled. Report the actual tool error separately from a DeepSpace HTTP error. ## HTTP flow Already have an account phrase in this chat or private storage? Skip signup: exchange it at /api/publish/auth/token, then GET https://deploy.deepspacesites.com/api/apps with the returned management bearer to discover your apps. The free staging tier allows one active app, including registered apps awaiting their first deployment. Update that app when continuing your user's request. Do not enroll again to get around a limit. A new-app publish whose name is already your app answers 409 app_exists with its appId and currentRevision; resend it as an update with those values and without starter. 1. POST https://deploy.deepspacesites.com/api/publish/auth/enroll with JSON {"name":"Your agent name"}. Save enrollmentId and challenge.id privately and solve challenge.prompt yourself. 2. POST https://deploy.deepspacesites.com/api/publish/auth/enroll-complete with {"enrollmentId":"RETURNED_ID","challengeId":"RETURNED_CHALLENGE_ID","answer":"YOUR_ANSWER"}; answer may be the integer as a JSON number or string. No Authorization header is needed. The JSON response contains userId, credential (the 12-word account phrase), and token (the short-lived management bearer). Immediately give the exact phrase to the user in this private chat, with userId and auth URL https://auth.deepspacesites.com. This is the default account receipt, so access survives disposable containers. You may instead keep the same phrase in private storage the person can reach later, such as a host vault or library. A file on your own disposable computer does not count on its own: if that is your only private storage, also give the phrase in this private chat unless your host forbids it, and say which you did. Anyone with it can manage the account. Completion is replayable until the five-minute challenge expires. 3. Use the management token as Authorization: Bearer TOKEN for publishing. Later, POST https://deploy.deepspacesites.com/api/publish/auth/token with {} and Authorization: Bearer PHRASE_WITH_HYPHENS to obtain a fresh 15-minute management token. For the Authorization header, trim the phrase and replace whitespace with hyphens. Capitalization and extra whitespace are accepted; word order is exact. Existing dsa_ credentials also work unchanged. Keep management tokens, credentials and enrollment nonces out of app source, URLs, public messages and logs. 4. GET https://deploy.deepspacesites.com/api/publish/starter?kind=raw&path=public%2Findex.html for {path,content}, then customize that page. The backend contract is below. If your reader drops query strings or summarizes JSON, GET https://deploy.deepspacesites.com/api/publish/starter/raw/public/index.html returns the same file as plain text (also /raw/worker.js); ask the reader for it verbatim. Read ?kind=raw&path=worker.js when changing server behavior and ?kind=raw&path=schemas.js when adding fields or collections; ?kind=raw&summary=1 lists paths. Omitting path/summary downloads the whole starter, including generated adapter bundles you do not need to read or resubmit. DeepSpace supplies those unchanged files during publication. The SDK option below is available when useful. 5. POST https://deploy.deepspacesites.com/api/publish with a fresh idempotencyKey, name (unique lowercase subdomain), expectedRevision: null, starter: "raw", and files mapping only the paths you changed to their full text. DeepSpace fills in the other starter files. To submit your own existing project, omit starter and submit its source including wrangler.toml. 6. The response is HTTP 202 with a job id and statusUrl. For a new app, appId appears in later receipts after registration; do not wait for it before polling. Resolve relative statusUrl against https://deploy.deepspacesites.com, and GET it with the management bearer using pollAfterMs. queued, saving, building, and publishing are nonterminal (done: false). published and failed are terminal (done: true). On success, url, releaseId and revision identify the result. Receipts include createdAt, startedAt and finishedAt (Unix milliseconds when known), elapsedMs and queueMs; elapsedMs stops when the job finishes. If observation disconnects, resume the same job; do not create another app. SDK builds have recently taken about a minute; other dependencies may take longer. If a token expires, refresh it and continue polling the same statusUrl. 7. Open the actual live URL. A published receipt confirms the release was accepted; edge rollout can take another few seconds. During rollout the page can briefly show an older revision or the backend can return a transient error. Retry the same URL after a few seconds before editing or republishing. Rollout has taken up to about 20 seconds, during which /_deepspace/agent routes can hang even though the page returns 200; time-bound those requests and retry rather than changing source. Create a record, verify reload persistence and second-session visibility, and then update an observable detail through the same API. Without a browser, a second session means a separate client: in a raw app, hold a second WebSocket open on /api/live (or poll GET /api/items from another process); in an SDK app, call its read-only list tool on /_deepspace/agent/tools with an app token (described below) from another process. Confirm it sees the write. Use your native browser; no browser or testing-suite installation is needed. ## Choose the shortest path For a new board, tracker, form, dashboard or small tool, prefer plain HTML/JS: read /api/publish/starter?kind=raw&path=public%2Findex.html, edit public/index.html, then POST with starter: "raw". It has a real Cloudflare Worker backend, durable SQLite, WebSockets, and a working server-side McAPI example at GET /api/inspiration. Recent raw publications took about 5–16 seconds; SDK builds took about a minute. Publishing needs no local installs, scaffold commands, GitHub access or test-suite setup on either path. Visual checks need a browser you already have; without one, verify through HTTP and a second WebSocket and report visual checks as unverified. Use the SDK starter when React hooks, ready-made auth UI or installable features help the requested app. Existing apps keep their current runtime and schema; do not switch them to a new starter during an update. ### Raw app contract This HTML/JavaScript starter uses the ordinary DeepSpace RecordRoom: SQLite records, schema validation, permissions and live subscriptions, with no local install or build. GET /api/items returns an array of {id,text,done,created}, newest first. POST /api/items with {text} creates a note; POST /api/update with {id,text} edits it in place, and {id,done:0|1} sets completion. POST /api/toggle with {id} toggles completion; POST /api/delete with {id} removes the note. Writes return the full updated array. Address notes by id. Text is 1–240 characters; done is numeric 0/1; created is Unix milliseconds. Edits preserve identity and creation time. WebSocket /api/live uses the SDK protocol, not bare arrays. On every connection send {"type":"core.subscribe","payload":{"subscriptionId":"items","query":{"collection":"items","limit":500,"orderBy":"createdAt","orderDir":"desc"}}}. A core.query_result message contains payload.records: each record has recordId, data and createdAt. Map it to the HTTP shape with {id:record.recordId,...record.data,created:Date.parse(record.createdAt)}. On core.record_change, reload GET /api/items. Ignore unrelated protocol messages; resubscribe on reconnect. Load GET /api/items immediately alongside the socket; enable HTTP writes once data is loaded, even while live updates reconnect. To add fields or collections, edit schemas.js using the standard CollectionSchema contract, then update the app's HTTP handlers and tool definitions. RecordRoom owns database changes and validation; do not add SQL tables or a second synchronization layer. The starter intentionally grants public access. Narrow schema permissions for private collections; verified human and target-bound agent tokens use the same permissions. React hooks and ready-made login UI remain available in the SDK starter. Give the app its own responsive design, labeled inputs, per-row controls whose accessible names include the item text ("Mark done: Buy milk", not a repeated "Mark complete"), visible keyboard focus, helpful empty states and retryable errors that preserve typed input. Keep a public-data notice. Verify a real create, edit and completion, then a second-session live update and a reload. Return the working URL and report any checks your host cannot perform. For raw apps, load GET /api/items immediately alongside the WebSocket connection. Once either returns a valid snapshot, enable HTTP writes; a reconnecting socket should not disable a usable HTTP backend. Keep loading, saving and live-connection state separate. Recompute button state on input, initial load, successful or failed saves and reconnects; restore controls in finally. Preserve an open edit and typed text when another session broadcasts. Give checkbox/button controls an explicit nonzero size and prevent flex shrinking. Ensure display:flex/grid styles do not override hidden error panels; use [hidden]{display:none!important} and show retry controls only after a failure. On phones, put the main task input and list before secondary charts or inspiration panels. Keep test-run budgets and verification notes in your report rather than the app’s end-user copy. Check the rendered create/edit/complete controls, not only their API endpoints; report visual checks as unverified when your host has no browser. GET /api/inspiration returns {success:true,data:{title,description,extract,url,...}} through server-side McAPI for the fixed Wikipedia article Kindness. Show data.extract and link data.url; returned data.title may reflect a redirect. Successful results are cached for 24 hours. Do not promise random articles without changing the server route, or describe an offline fallback as a live integration result. If you extend server operations, update the same app-owned tool definitions and their input schemas so independent agents can use every supported action. When writing a new page or Worker from scratch, retain the raw starter’s deepspace-agent.js and public/deepspace-agent.js files, registerAgentToolTransports wrapper and /_deepspace/agent routes. Keep the page’s connectAgentTools({basePath:"/_deepspace/agent",getToken:async()=>null}) module registration for this public board. Use the shared adapter, not a second tool implementation. Both raw adapters use basePath: "/_deepspace/agent" explicitly; keep this matching on the page and Worker. After deployment GET /_deepspace/agent/tools returns {ok,app,tools:[{name,description,inputSchema}]}. Choose the returned read-only list tool and POST /_deepspace/agent/tools/TOOL_NAME with Content-Type: application/json and {"input":{}}. The body wraps tool arguments under input, even when empty. Keep unsupported native WebMCP invocation marked unverified. ## Optional SDK project For an SDK app, GET /api/publish/starter?path=src%2Fpages%2F(app)%2Findex.tsx and submit starter: "public-board". Its page uses the `ideas` collection with `text: string` and `done: boolean`. Preserve those names for page-only edits. Records store fields under `record.data`. Keep existing loading, reconnect and pending-write feedback. To introduce a different collection or extra fields, include matching schema changes; a successful build does not prove a database write works. POST /api/publish with the management bearer and JSON: {"idempotencyKey":"YOUR_FRESH_UUID","name":"your-unique-name","expectedRevision":null,"starter":"public-board","files":{"src/pages/(app)/index.tsx":"YOUR COMPLETE CUSTOMIZED PAGE SOURCE"}} The source is the same project produced by create-deepspace: wrangler.toml, package.json, Worker, schemas, React pages, and Git history. The hosted runner invokes the same builder used by deepspace deploy; it does not invent a separate database or sync protocol. ## Plain HTML and JavaScript Raw files still publish without a build. GET https://deploy.deepspacesites.com/api/publish/starter?kind=raw returns a Worker/HTML example with standard wrangler.toml and no_bundle = true. Submit its files, or use starter: "raw" with your changed files. Its Board extends the same RecordRoom as SDK apps, and schemas.js owns fields and permissions. Use the SDK starter for React hooks, ready-made auth UI and installable SDK features. Both paths use the same Cloudflare deployment, app identity, source history and McAPI catalog. Wrangler's main, assets.directory, durable_objects.bindings, migrations, compatibility settings and routing describe the app for both the CLI and hosted publishing. Worker modules in raw projects must already be JavaScript, using relative imports or Cloudflare built-ins. For npm dependencies or TypeScript, use a normal build project and omit no_bundle. Hosted builds can only see submitted source: replace dependencies pointing outside the project (such as file:../../tools/package.tgz) with a reachable package URL or registry version, and update the lockfile before publishing. ## Recover and update the same app In a fresh process, use this sequence: 1. Read your exact account phrase from private chat or supported private storage. POST https://deploy.deepspacesites.com/api/publish/auth/token with {} and Authorization: Bearer PHRASE_WITH_HYPHENS. Keep the returned management token private; use it for every request below. 2. GET https://deploy.deepspacesites.com/api/apps for {apps:[{appId,ownerUserId,name,url,role,...}],pendingTransfers:[...]}. Select your existing app from apps; ownerUserId is its owner identity, not userId. 3. GET https://deploy.deepspacesites.com/api/publish/apps/APP_ID/source?summary=1 for {revision,files:["path",...]} (files is an array of paths), then ?path=URL_ENCODED_PATH for {appId,name,revision,path,content}, where content is the file text. Read only the page, schema and files you need. Omit the query only when you need the whole project. Every response includes the current revision. 4. POST https://deploy.deepspacesites.com/api/publish with the SAME appId and name, expectedRevision equal to the revision you read, a NEW idempotencyKey, and only changed files. Omit starter. Poll the returned statusUrl until done, then check the live app and its saved data. Omitted files remain; null deletes a file. Use files: {} to rebuild the saved revision without an artificial edit. Recover an existing project's schema before editing; do not overwrite an existing app with a new starter. Source is stored as ordinary Git commits on the repository's default branch. You can clone a DeepSpace-source project, edit and deploy it with the CLI, then return to this API, including projects whose branch is named master. The response lists unchanged binary files and symlinks under preservedFiles; omit these from files to keep their exact Git bytes and modes. Existing binary assets are included in hosted builds; symlinks remain in Git but are not followed in the build container. Use Git to retrieve or change their bytes. Keep the same DEEPSPACE_APP_ID and Durable Object identities to retain the app and its data. Changing the application's data model can require a migration. GitHub-owned source remains on its existing GitHub workflow. ## McAPI integration catalog and calls Native tool discovery is available at https://deploy.deepspacesites.com/api/publish/agent/tools and https://deploy.deepspacesites.com/api/publish/agent/tools.md; MCP clients can use https://deploy.deepspacesites.com/api/publish/agent/mcp. Each tool takes the same Authorization as its HTTP endpoint: the account phrase for account_token, account_renew and app_token, and the management token for publishing and McAPI calls, so a client fixed to one bearer can do only that part. The publisher page registers the same tools through WebMCP when its browser supports it. No plugin is required for HTTP or browser publishing. Account creation, publication and McAPI tool calls delegate to the exact HTTP endpoints below; every operation keeps its own authentication and billing checks. Native publishing accepts the same source request size as HTTP. Use the URL handoff only for chats whose available tools cannot make these requests. To use an SDK app's selected tools after deployment, POST https://deploy.deepspacesites.com/api/publish/auth/app-token with your account phrase in the Authorization header and {"target":"https://YOUR_APP.spacestest.com"}. Use its short-lived token on that app's /_deepspace/agent/tools or /_deepspace/agent/mcp. The app's membership and permissions still apply. The publisher's app_token tool and the CLI's agent tools/invoke commands use this same exchange. Keep the phrase and tokens private; do not send the phrase to app origins. Raw starter tools retain the starter's explicit public-board policy. McAPI is the DeepSpace integration catalog. Stay on the publishing origin: discover names/prices at https://deploy.deepspacesites.com/api/publish/integrations?summary=1, then fetch only the chosen endpoint’s schema/example with ?endpoint=wikipedia%2Fget-page-summary. POST JSON to https://deploy.deepspacesites.com/api/publish/integrations/INTEGRATION/ENDPOINT with the same fresh management bearer to use it directly (up to 2 MiB per request). These routes call the existing McAPI service with the same authentication and billing; no new provider signup or API key is needed. The direct https://api.deepspacesites.com/api/integrations routes also remain available. Successful calls return {"success":true,"data":RESULT}; the catalog's outputSchema describes RESULT, not the outer response. Read result.data after checking HTTP status and success. GET https://deploy.deepspacesites.com/api/publish/usage with your fresh management bearer returns credits, usageByIntegration and recentUsage. credits is a credit balance (100 credits = 1 USD); usageByIntegration[].totalCost and recentUsage[].totalCost are USD. Counts exclude settlement adjustments; recentUsage.entryType distinguishes a charge from its settlement. This is the same balance as https://api.deepspacesites.com/api/usage/summary; /api/users/me is the account profile. A fresh token/status response describes current capabilities; old saved enrollment receipts may predate McAPI availability. In a raw app, call env.API_WORKER.fetch from worker.js with Authorization: Bearer plus env.APP_OWNER_JWT, as the starter’s /api/inspiration route demonstrates. Both bindings are supplied by the normal deployment. The browser calls your own app route; never embed the owner token or private credential in HTML. Each uncached integration request bills the app owner, including requests triggered by public visitors. The raw starter's /api/inspiration therefore reuses one successful result for 24 hours from the board's Durable Object storage (response header X-Inspiration-Cache: hit or miss); failures are not cached. Keep that pattern when you change the route. A short per-click cooldown is not a budget: a public random-topic route needs a server-side cache or daily cap, since browser limits are not an account-wide budget. Expose the specific operations and inputs your app needs, rather than a public arbitrary paid proxy. In SDK apps use the standard integration client/server tools and src/integrations.ts billing policy. Calls use the existing credit checks and billed identity. OAuth connections and connection-based tools require a human account; agents can still inspect their catalog. Account renewal restores runtime integration access without republishing. Hosting and saved data continue while verification expires. ## Recovery guidance - revision_conflict: read current source and apply your edit to that revision. - publish_busy: poll the existing job at the error's statusUrl. - publishing with release_reconciliation_pending or deploy_timeout: keep polling the same job. DeepSpace retains and retries the exact release request; do not submit another publication. If code is token_expired, exchange your phrase for a fresh management token and poll that same statusUrl to resume. If repeated failures end the job as failed, resubmit the same files with a new idempotency key. - idempotency_conflict: this key identifies different input. Use a new key for a different edit. - failed: inspect code and error. If revision is present, source was saved. Fix that source and submit a new key against its current revision and same appId. The previous live release remains when validation/build fails. - agent_verification_required: POST /api/publish/auth/renew with {} and your private credential, solve the challenge, then POST challengeId and answer to the same endpoint. Obtain a fresh management token and poll the same pending job to resume it. Hosting continues while verification is expired. - app_quota_exceeded (older receipts: quota_exceeded): the error's appsUrl lists existing apps; activeApps and limit describe the quota. A new-app refusal happens before a job or app ID is created. Update an existing app or report the limit. Do not delete apps or create extra accounts automatically. - storage_full: the app's Git history and deploy files are over its 256 MiB repo limit, the same on every plan, so an upgrade does not help. The refusal starts clearing history no branch uses; retry once after a minute. If it repeats, report it: large media belongs in app files, not in source. Direct source submissions support up to 512 changed paths and 6 MiB total project source, with no separate 2 MiB per-file ceiling. JSON requests allow 12 MiB for encoding overhead. Normal Git/CLI deployment uses its existing content-addressed uploads (25 MiB per asset and 100 MiB total by default). These limits are independent of URL drafts; never encode source into a link when your host can POST it. Secret paths, Git metadata, and node_modules are refused. Keep secrets in the app's secret store; publication uses its prd config. Keep the phrase in the private chat by default, or in private storage outside a disposable machine. If local files disappear, read that exact phrase from chat and exchange it for a fresh token; do not enroll again. If verification expired, solve the renewal challenge with the same phrase. Never guess a missing phrase; losing every copy loses account control. Payments, legal commitments and connecting external accounts remain human actions. Ordinary McAPI calls use the existing credit balance; a 402 means the balance cannot cover the call, not that you should purchase credits automatically.