# Publish an app directly from your native tools

Publish ordinary DeepSpace SDK projects or raw HTML/JS through HTTP, a browser, or a chat-authored launcher file. Cloudflare builds and hosts your app.

You can deliver a working full-stack app without setting up a development
environment. Start with an agent name, solve your challenge, submit your files,
and receive a live URL.

**Staging prototype:** use the [live agent guide](https://deploy.deepspacesites.com/agents.md)
for the exact HTTP contract or the [publishing form](https://deploy.deepspacesites.com/publish)
for browser tools. Production enrollment is not enabled.

**Returning agent?** Use your account phrase from the private chat or private storage to get a management token, then
`GET /api/apps` to find your existing app. The free staging tier has one active
app slot, including an app registered but not deployed yet. Continue with that
app's source and current revision; no new signup or local installation is needed.

## One line to get started

“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.”

Keep the requested app behavior in that instruction. No extra tool, plugin,
connector, or bot customization is needed. A provider may still impose its own
permission prompts or have unavailable tools; the page does not override those.

Fresh signup sends only a name and a challenge answer. Use its returned management
token to publish immediately; no existing password or separate browser sign-in is
needed. If your host does not permit sharing authentication phrases in chat, keep
the same phrase in supported private storage and continue. Respect the host's
credential-handling rules. A user can retrieve their own browser receipt through
**Download credential backup**; a file on a disposable agent computer alone will
not survive replacement of that computer.

Bound individual HTTP requests; 15 seconds is a useful starting point. If a
native tool stalls before returning an HTTP response, cancel the pending call
when supported and use another available native tool. Preserve your enrollment
IDs, account and publication job. A stalled tool is not a failed deployment.

## What happens

1. Send your agent name and solve the returned challenge. DeepSpace issues a
   portable 12-word account phrase. Give the exact phrase, account ID and staging auth URL to the user in the private chat immediately. Private storage is optional for the same phrase. Anyone with it can manage the account; keep it out of app source, public messages, URLs and logs.
2. For a small app, fetch `/api/publish/starter?kind=raw&path=public%2Findex.html`
   and customize the returned `{path,content}` page. Submit only changed files;
   DeepSpace supplies unchanged starter files. The starter has a real Worker
   backend, persistent SQLite, WebSockets and a server-side McAPI example.
   Use the React/TypeScript SDK starter when its records, auth or permissions help.
3. Submit the app name, files, and a fresh request ID. The initial HTTP 202
   response returns the publication job `id` and `statusUrl`; `appId` appears
   after registration. Poll `statusUrl` for the result.
4. Open the app, exercise its real behavior, reload it, and verify that data
   survives. Check live updates from a second session when your app uses them.
5. Recover the saved source through the API, change a file, and submit another
   publication against the revision you read. The URL, app ID, and database stay.

Source is saved as real Git commits. The same request ID and identical input
return the same job; conflicting edits are refused. Closing your browser or
losing the agent's local environment does not cancel the server-side job.

Follow `done` and `pollAfterMs` in the receipt. `building` and `publishing` are
still in progress. The receipt reports `createdAt`, `startedAt`, and `finishedAt`
as Unix milliseconds when available, plus `elapsedMs` and `queueMs`. SDK builds
have recently taken about a minute; HTML/JS publications took about 5–16 seconds.
`published` confirms release acceptance. Edge rollout may take a few more seconds;
reload the same live URL before changing code or submitting another publication. If your token expires, refresh it and resume
the same job URL. A quota refusal includes `appsUrl`, `activeApps`, and `limit`
before allocating a new job or app ID; it does not require a CLI or another account.

## One tool definition, native transports

The staging publisher exposes the same operations through
[JSON discovery](https://deploy.deepspacesites.com/api/publish/agent/tools),
[Markdown tool instructions](https://deploy.deepspacesites.com/api/publish/agent/tools.md),
and a stateless MCP endpoint at `https://deploy.deepspacesites.com/api/publish/agent/mcp`.
These call the existing signup, source, deployment and McAPI endpoints. Use the
same Authorization bearer; a native host must already support supplying it.
HTTP and browser publishing require no installed connector.

In a browser that supports WebMCP, the publishing form registers those operations
as native site tools. Signup saves the issued account phrase in the browser's
existing receipt, so the next tool can publish. New SDK scaffolds expose their
selected `buildTools` definitions through HTTP, MCP and Markdown; their app layout
registers the same actions with WebMCP under the signed-in user's permissions.
The raw starter exposes its public board operations through the same adapter.
When replacing its HTML or Worker, retain both `deepspace-agent.js` runtime
files, `registerAgentToolTransports`, and the page’s `connectAgentTools` module
registration. Keep the shared adapters so native browser tools and server
endpoints stay available. Verify `GET /_deepspace/agent/tools` returns JSON and
invoke its read-only list tool after deployment with `{"input":{}}`; do not
substitute a separate tool implementation. Keep the page adapter’s `basePath`
set to `/_deepspace/agent`, matching the Worker registration. Native WebMCP invocation still requires a supporting host.

To call a protected SDK app's tools, use the publisher's `app_token` operation
with your account phrase and the exact app origin. Send its returned token to
the app's `/_deepspace/agent/tools` or `/_deepspace/agent/mcp` endpoint. It lasts
at most five minutes, retains your identity and cannot grant access beyond the
app's membership and permissions. The CLI performs this exchange automatically
when an independent agent credential is selected. Keep the phrase on the account
service; never send it to an app or put it in source.

WebMCP support varies by browser and host. The adapter detects the available API
and makes no extra requests on unsupported browsers. The ordinary UI and HTTP
routes continue to work. An MCP endpoint does not automatically install an app
or connector into ChatGPT, Claude or another host.

## Source size depends on the transport

Send source directly whenever your existing tools can make HTTP requests.
Direct HTTP and MCP publishing accept a **12 MiB JSON request** and a **6 MiB
source project**, including unchanged files. There is **no separate 2 MiB
per-file ceiling**, for raw apps or SDK container builds. Native agents can use
ordinary Git and CLI deployment for larger projects, with the existing asset
upload limits of 25 MiB per asset and 100 MiB total by default.

Only the restricted-chat URL draft uses the smaller limits: 100,000 encoded
characters and 256 KiB of inflated JSON. It is a fallback, not the transport
for every agent. App-action results remain bounded for model context; retrieve
large source files through the direct source endpoint instead of a tool result.

## What you can write

The optional SDK project is the same one produced by `create-deepspace`: Worker,
schemas, React pages, `package.json`, and `wrangler.toml`. Change an individual
file in the browser, or submit `starter: "public-board"` and only your changed
files through HTTP. DeepSpace builds the project in a fresh Cloudflare container
using the same builder as `deepspace deploy`. You do not need npm or a compiler
in your agent's container.

For page-only edits, retain the starter's `ideas` collection and `text: string`
and `done: boolean` fields. Read record values under `record.data`. Preserve its
loading, reconnect, and saving feedback. A new collection or field needs matching
schema changes; verify a real write after publishing, even when compilation passed.

Prefer plain HTML/JS with `starter: "raw"` when it meets the request. Its standard Wrangler
config uses `no_bundle = true`, so ready-to-run JavaScript publishes without a
build. The raw example uses its own small public-board Durable Object; use the
SDK starter for DeepSpace's records, auth, permissions, and SDK features.
Both can call McAPI from their backend.

Both paths use the existing Cloudflare deployment system, real Git history,
app identity, URLs, and release records. You can clone the source and use the
CLI, then return to hosted editing. Preserve the app ID and data-room identities.
Hosted recovery and updates follow the repository's default branch, including
CLI projects whose branch is named `master`. Recover the existing schema before
editing an app; a fresh starter is not a data migration.
Existing direct-publish apps gain standard Wrangler configuration on their next
update while retaining their existing data. GitHub-managed source keeps its
GitHub workflow. Hosted edits accept UTF-8 text. The API lists existing binary
files and symlinks under `preservedFiles`; omitted entries keep their exact Git
bytes and modes. Binary assets are included in builds. Symlinks stay in Git but
are not followed in the build container. Use Git to retrieve or change those bytes.

## Integrations without another signup

McAPI is DeepSpace's integration catalog. Read
[the compact catalog](https://deploy.deepspacesites.com/api/publish/integrations?summary=1),
then request one endpoint's input/output schema with
`?endpoint=wikipedia%2Fget-page-summary`. POST to
`https://deploy.deepspacesites.com/api/publish/integrations/INTEGRATION/ENDPOINT`
with your management
bearer; ordinary services use your existing credit balance and need no provider
API key. A credit-limit refusal does not authorize buying more credits.

Successful calls return `{ "success": true, "data": RESULT }`. The catalog's
`outputSchema` describes `RESULT`; read it under `data`. Check your credit balance
with `GET https://deploy.deepspacesites.com/api/publish/usage` and the fresh management
bearer. It returns `credits`, `usageByIntegration`, and `recentUsage`. One hundred
credits equals USD 1; `totalCost` fields are already in USD. Request counts
exclude settlement adjustments; `recentUsage.entryType` distinguishes `charge`
from `settlement` ledger entries. Current
token/status responses supersede capability lists in older enrollment receipts.

These same-origin routes forward to the existing McAPI service, keeping its
authentication, credit checks and errors. Integration requests accept up to
2 MiB. The direct `https://api.deepspacesites.com/api/integrations` and
`/api/usage/summary` endpoints remain available too. Using the publishing origin
avoids another domain in agents' HTTP and browser flows.

Deployed HTML/JS apps use `env.API_WORKER` and `env.APP_OWNER_JWT` in their Worker.
Those bindings come from the same deployment used by SDK apps. The raw starter's
`GET /api/inspiration` shows a fixed Wikipedia call; customize that server route
for the feature your app needs. Keep the private token out of browser code and
expose only the operations and inputs your app requires. Public raw app calls
bill the app owner: enforce budgets and cache suitable results in the backend,
not only in the browser. Keep test budgets out of end-user copy. SDK apps use their
normal integration client and billing configuration.

External account connections, payments and legal actions still require a human.
Runtime McAPI calls check current agent verification. Renewing the challenge
restores access without redeploying; hosting and saved data remain available.

For updates, start with `/api/publish/apps/APP_ID/source?summary=1`, then read
individual files with `?path=...`. The summary has a `files` array; a file read
returns `{appId,name,revision,path,content}`. Fetch the whole project only when
needed. `GET /api/apps` returns `{apps:[{appId,ownerUserId,name,url,role,...}],pendingTransfers:[...]}`.

For account-auth requests, join the phrase words with hyphens in the Bearer header.
Use the returned management token for app requests. If a container disappears,
read the phrase from the private chat, sign in, list your apps and update the same
app ID. Never guess a missing phrase or enroll again to recover an existing app.

## Build a useful app against the real backend

The raw starter stores `{id,text,done,created}` records. `GET /api/items` and
WebSocket `/api/live` send the full list, including an immediate socket snapshot.
`POST /api/items` with `{text}` creates a record; `POST /api/update` with
`{id,text}` edits that record in place, and `{id,done:0|1}` sets completion.
Both fields can be sent together. Writes return the updated list. Text is
1–240 characters, `done` is numeric 0/1, and `created` is Unix milliseconds.
Keep record IDs stable; there is no need to encode edit history into task text.

`GET /api/inspiration` returns `{success:true,data:{title,description,extract,url,...}}`.
The starter always reads the Wikipedia article **Kindness**. Do not promise random
or new articles unless you change the server route. Read `data.extract`, link
`data.url`, and make failures retryable. Do not label
an offline fallback as a successful live integration result.

Give each app its own responsive layout, labeled controls, visible keyboard
focus, useful empty states, and errors that preserve typed input. Keep the
public-data notice. Check real create/edit/complete actions, a second-session
live update and a reload. When extending server operations, update their
app-owned agent tool definitions and input schemas too.

For raw apps, load the initial list with HTTP alongside the WebSocket. Enable
HTTP writes after either gives a valid snapshot; a reconnecting socket need not
disable a usable HTTP backend. Keep loading, saving and connection states
separate. Recompute button state on input, initial load and save completion,
including failures. Preserve typed edits during live broadcasts. When a save
finishes, clear an input only if its current value still matches the submitted
value, so text entered for the next task survives. Give controls
explicit nonzero dimensions and prevent flex shrinking. Check real rendered
controls; API-only checks cannot prove they are visible and clickable. Ensure
flex/grid styles do not override hidden error panels; for example, use
`[hidden]{display:none!important}`. Show retry controls only after a failure.
On phones, put the main task input and list before secondary charts or
inspiration panels. Let row actions wrap below task titles instead of squeezing
text between fixed-width controls. Verify the actual phone viewport; a successful
desktop screenshot does not establish mobile behavior. Publish and check the
real app promptly; building a local test harness is not required for this flow.

## When your chat can only read the web

Regular chats sometimes have a web reader but cannot make network requests or
operate a browser. For a ready-to-use one-line instruction, open the [launcher](https://deploy.deepspacesites.com/launch) and choose **Copy a prompt for your agent**. Paste it into your chat with your app idea. It includes a fresh guide URL directly in the initial request, avoiding a second documentation fetch that some readers reject. Copying the prompt creates no account or app.

Agents can also use the [browser-handoff guide](https://deploy.deepspacesites.com/chat-start.md).
It asks the chat to generate a fresh URL so web-reader caches cannot reuse an old question, then reads a Markdown response containing a real signup
challenge held for that guide for 20 minutes, the complete draft/encoding contract and an HTML/JS example page. The hold creates no account or credentials; it prevents another simultaneous signup from consuming the question while the app is being written. Re-reading the same fresh guide retains the hold. Expired holds return to the available pool. No
separate JSON endpoint calls or dependency build are needed. Preserve the raw
backend’s `/api/items`, `/api/update`, `/api/toggle` and `/api/live` contracts; you can customize
the example or write original markup. A summarizing web reader only needs to
extract the public question and those small contracts, not reproduce the entire
example. The [SDK variant](https://deploy.deepspacesites.com/chat.md?kind=sdk)
remains available when SDK features are needed. The agent solves the challenge, authors your app, and encodes a
source-carrying link using local code. For a regular chat, one line is enough:

“Build my shared app using https://deploy.deepspacesites.com/chat-start.md and deliver
a native HTML launcher containing the complete publish link plus its .deepspace.json file.”

Open the delivered HTML file, follow its publish link, and press
**Create account and publish**. Prefer native file delivery to streaming a long
URL into chat; return a direct clickable link when native files are unavailable.
Your browser completes
signup and deployment. You do not copy code, install tools, or create a hosting
account yourself. The browser shows a copyable account phrase receipt. Keep it in the private
chat by default when the host permits it, or store the same phrase privately; a backup download is also available. Reading or previewing the link never publishes anything. If the chat
corrupts a long link, choose its draft JSON file on the launch page; the browser
handles the encoding. If the one-time signup question has already been used, the launcher provides a fresh question link. Send it to the same chat and ask it to replace only `questionId` and `answer` in the draft. Your app source is retained; the rejected attempt creates no account or app.

For an update, give the agent the app ID and source revision from the receipt.
It returns another launcher containing changed files; **Publish update** reuses the
browser’s saved credential and preserves the app and its records. Keep the account phrase in the private chat, never in a draft or launch URL.
A fresh browser can accept the saved phrase directly on the update launch page. If a build service fails, **Retry build** keeps the same account,
app, and saved source. Compiler errors keep the previous release live and expose
the source revision needed to correct them.

This fallback needs a browser handoff. It is not evidence that a regular chat
can deploy autonomously. Agents with working HTTP or browser tools continue to
use the direct flow above.

The [live guide](https://deploy.deepspacesites.com/agents.md) describes request
fields, source limits, retries, updates, and errors. The
[account API](/agents/account-api) documents credential renewal and recovery.
Payments, legal commitments and paid platform changes still require a human.
