run_code
Run a short script once, server-side, against a project's own bindings — get the result + console logs back in one call. It replaces a throwaway debug endpoint or dozens of tool calls when inspecting data, trying a query variant, or running a one-off transformation.
code is an ES module whose default async function receives sw (the same database / files / search / ai bindings a deployed function gets) and returns a JSON-serializable value:
{
"project_id": "my-saas",
"code": "export default async function (sw) { const { data } = await sw.db.server.from('notes', { limit: 1 }); return data; }"
}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. The script entry point above is for run_code. 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.
Runs with the project's OWN authority, not your developer key: no env secrets unless you pass include_env: true, no admin, no cross-project access, and outbound fetch is limited to public hosts. Returns { result, logs, duration_ms, error? }. result is capped at 256KB (truncated with a notice past that). logs keeps at most 100 entries. Each log message is cut at 64KB with a [truncated: …] marker at its end. All logs together stop at 4MB, followed by one final [logs truncated: …] entry. logs_truncated: true is set when entries were dropped by either limit (not when a single message is cut). error.message and error.stack are each cut at 64KB. A returned session over 64KB is not stored and the call answers SESSION_TOO_LARGE. timeout_ms defaults to 10000, max 30000.
Threading state across calls (opt-in): pass a stable session_id to carry explicit JSON state between runs. The saved JSON is exposed to your script as a read-only sw.session; a returned { session: {...} } object saves state for the next call (it is stored under that session_id, separately from result). Absent session_id = stateless, byte-identical to a normal run. This is explicit data you thread by id — NOT live-variable/closure persistence.
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>",
"code": "<code>"
},
"name": "run_code"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Per-run string inputs (at most 16KiB UTF-8 JSON), passed as the frozen second argument to export default async (sw, args). Separate from env and saved sessions; omitted means an empty object. Secrets belong in project env. | |
| code | Yes | ES module source: export default async function (sw, args) { ...; return value }. args is a read-only object of per-run strings (empty when omitted); existing (sw) scripts also work. The JSON-serializable return value comes back as result. | |
| project_id | Yes | Project ID (UUID), subdomain, slug, or 'default'. Resolved server-side. | |
| session_id | No | Opt-in session key (<=128 chars, [A-Za-z0-9_-]). Loads saved JSON as a read-only sw.session before the run; a returned { session } persists for the next call (stored state capped at 64KB). Absent = stateless. | |
| timeout_ms | No | Abort the script after N ms. Default 10000. Clamped to [1, 30000]. | |
| include_env | No | Expose the project env vars as sw.env. Default false — off unless the script needs a secret. |