project_deploy
Deploy / ship / host / push / release your app — upload raw source (HTML, CSS, JS, server functions) to a project and put it in production at https://{subdomain}.somewhere.site. The platform compiles your code; you deploy source, not a build.
If you can run a shell, LEAD WITH the CLI: somewhere deploy reads files straight from disk (no inline JSON payload) and is the faster path. The CLI installs with npm i -g @somewhere-cloud/cli && somewhere auth login (shares MCP auth). This MCP tool is the inline fallback — for agents without shell access, small projects, or when the CLI isn't available.
For UPDATES to an existing project, project_patch with find/replace ships surgical edits in ~200 bytes instead of resending every file. project_deploy is for the FIRST deploy of a new project, or for replacing the whole tree.
Large or binary files are referenced, not pasted. Instead of being inlined into files, a big asset (or base64 bytes) goes to project file storage first with fs_write and is referenced by storage path via file_refs (text files) or binary_file_refs (images, fonts, other binaries). The platform resolves the referenced content server-side at deploy time, so a big tree ships without a giant inline payload. Inline files/functions keep working and can be mixed with refs in the same deploy.
Deploys your app. The result lands at https://{subdomain}.somewhere.site and on any verified custom domain — every deploy reaches production.
⚠️ Omitted items are NOT all treated the same. Static files are full-replacement: anything you omit from files is deleted (scope:"functions" leaves static untouched). functions are merge-preserved by default: a function already in production but omitted from this call is KEPT, not deleted — so you can ship a backend-only change without resending the frontend, and project_patch-only functions survive a later full deploy. replace_functions:true makes a deploy delete functions it no longer ships. (Env vars, database, and uploaded fs files are never affected.) Use dry_run:true to inspect exactly what will be added / removed / modified before anything is written. project_patch with a files map changes several files of an existing project without resending the rest: files not listed are kept.
Server-side functions are the core — handler code goes in the functions map (keyed by path, e.g. "api/hello.ts") and becomes routable at /api/... on your production URL. The files map is for STATIC assets only (HTML, CSS, client-side JS, images). Handler code (api/*, _lib/*, root [id].ts routes) belongs in functions, not files — a static asset never routes, so /api/* would just serve the app's HTML. (A handler-shaped path found in files is moved into functions with a warning.)
For a JSON route in api/, use export default sw.endpoint({ auth, handler }) and set auth explicitly. TypeScript infers the handler inputs and sw context. Use auth: 'none' only for a deliberately public route.
export default sw.endpoint({ auth: 'none', handler: async () => ({ ok: true }) });Declare application tables in db/schema.ts. Read them with sw.db.from for caller-scoped access or sw.db.server.from after authorizing the caller for server access. Write them with the corresponding structured methods, such as sw.db.server.insert. Raw query and batch use the separate raw SQL database on current projects.
Functions run directly on the platform with access to sw.db (database), sw.fs (file storage), sw.email (send email), sw.ai (AI models), sw.env (environment variables), sw.jobs (background jobs), sw.queue, and sw.logs. sw.db uses the function's authenticated project binding, so application code does not send a developer API key or construct a platform HTTP request. First-use activation, placement, transport, scheduling, and engine work can still contribute to latency. sw.db.batch([{sql, params}, ...]) runs multiple statements as one atomic transaction; any failure rolls every statement back. (ctx is an alias — same object, both names work.)
Source base (required on every live deploy). Pass base_release_id: the active_release_id from the project_export read your source came from, or null when the project has no source yet. The base is the one that came with the edited source; a newer id read just before deploying is not a valid base. A missing base returns 400 BASE_REQUIRED and nothing changes; a base that is no longer live returns 409 STALE_RELEASE_BASE with data.changed_files. Recovery is a re-export, the change re-applied to the new source, and a deploy with the new base. force:true deliberately replaces the live source; it still fails if another deploy lands while yours builds.
Projects without releases use base_version from your last deploy/export response instead. If the project changed elsewhere, deploy returns 409 STALE_BASE with data.changed_files, data.last_change_source, and data.last_change_at; review project_diff_versions before choosing force:true.
Version counter check (optional, separate from the source base). expected_version compares the project's deploy counter: a number returns 409 VERSION_CONFLICT with data.current_version when it differs; omitting it (or "latest") skips only this extra check. Omitting it never replaces base_release_id.
The success response always includes the new version. When available, it may also include _runtime_key_summary, a plain-language note on whether the runtime key for this deploy was narrowed to least-privilege scopes or fell back to blanket access.
Example:
{
"project_id": "my-saas",
"files": {
"index.html": "<!DOCTYPE html><html><body><h1>Hello</h1></body></html>"
},
"functions": {
"api/hello.ts": "export default sw.endpoint({ auth: 'none', handler: async () => ({ ok: true }) });"
}
}Handler code goes in functions; static assets (here, index.html) go in files.
The default workflow has one environment: read production source, check, deploy once, then verify the public production URL. somewhere preview is an optional advanced capability; preview inputs apply when a preview is explicitly requested and the account has hosted preview access (every plan includes it for signed-in accounts).
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"project_id": "<project_id>"
},
"name": "project_deploy"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| draft | No | Alias for preview; preview is the canonical name. | |
| files | No | Map of STATIC file paths to content, e.g. {"index.html": "<html>..."}. A native object or an array of {path, content} is accepted. Static assets include HTML, CSS, and client-side JS. Handler code (api/*, _lib/*, root [id].ts routes) belongs in `functions` for routing; a handler-shaped path here is auto-routed with a warning. Full deploys require this field; scope:'functions' may omit it when only functions are supplied. | |
| force | No | Bypasses a STALE_BASE refusal and overwrites the remote changes it reported; project_diff_versions lists those changes. | |
| scope | No | Optional partial-deploy guard. "all" (default) deploys static files and functions. "functions" leaves static files untouched; "static" leaves functions untouched. Omitted functions remain merge-preserved by default. | |
| dry_run | No | Optional non-writing diff of added, modified, and removed files, function changes, and version conflict. It exposes every deletion before a real deploy and returns { dry_run, static_files, functions, warnings, version_conflict }. | |
| message | No | Optional user-supplied note for this version (max 200 characters). | |
| preview | No | Advanced `somewhere preview` flag requiring hosted preview access for signed-in accounts on every plan; otherwise CLOUD_DEV_NOT_ENABLED is returned before resource creation. False (default) deploys directly to production. | |
| draft_id | No | Alias for preview_session_id. | |
| file_refs | No | Optional map of deploy path → project file-storage path for TEXT files otherwise supplied inline, e.g. {"index.html": "/staged/index.html"}. The platform reads referenced content from file storage at deploy time, so a large tree avoids a giant inline payload. Referenced source must already exist through `fs_write`. Inline `files` may be mixed in. | |
| functions | No | Map of function paths to ES-module source. Prefer an object; an array of {path, content} or a JSON-stringified object also works. Files under api/ become routes. For a JSON route in api/, use export default sw.endpoint({ auth, handler }) and set auth explicitly. TypeScript infers the handler inputs and sw context. Use auth: 'none' only for a deliberately public route. A direct request handler is also supported for streaming and webhooks. Read config from sw.env inside the handler (docs topic sw.env). | |
| project_id | Yes | Project ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them). | |
| base_version | No | Optional stale-base guard containing the version from the preceding deploy or export response. A 409 STALE_BASE indicates a remote project change and requires reviewing project_diff_versions before a forced retry. | |
| binary_files | No | Optional map of binary asset paths to base64 content. Exact preview snapshots require the complete map. | |
| base_release_id | No | Release id the deployed source was prepared from: the active_release_id returned with that project_export, or null when the project had no source. Required on every live deploy and on the first preview snapshot. A missing base returns 400 BASE_REQUIRED; a base that is no longer live returns 409 STALE_RELEASE_BASE with data.changed_files, and nothing changes. | |
| binary_file_refs | No | Optional binary counterpart to `file_refs` for images, fonts, and other non-text assets, e.g. {"public/logo.png": "/uploads/logo.png"}. Binary data is referenced from file storage rather than base64-encoded in `files`. | |
| expected_version | No | Optional extra check on the deploy counter, separate from the required base_release_id. A number returns 409 VERSION_CONFLICT when the counter differs; "latest" or omission skips only this extra check. | |
| replace_functions | No | Optional authoritative-function flag. When true, functions absent from the payload are deleted; false (default) merge-preserves omitted functions. The true value is for intentional removal of functions no longer shipped. | |
| draft_operation_id | No | Alias for preview_operation_id. | |
| preview_session_id | No | Stable editing-session id for this preview lineage. Required with preview:true. | |
| expected_preview_id | No | Exact current preview id, or null for the first preview. | |
| preview_operation_id | No | Stable idempotency id for this exact preview build/retry. | |
| expected_candidate_release_id | No | Alias for expected_preview_id. |