Build with Substrio.
Everything you need to build, connect, and deploy apps with Substrio. Use HTTP, the CLI, or MCP.
Your first app
Get a key, create an app, push a function, try it on a sandbox and take it live.
Start BuildingStart with HTTP, CLI, or MCP
Walk one path three ways, from an app key to a deployed and invoked function.
Open the QuickstartConnect your AI agent
Your agent builds and deploys your app over MCP or plain HTTP, with the same results.
Connect Your AgentBring an existing project
Move an existing backend over in order: data, sign-in, routes, jobs, mail, files, secrets and tests.
Bring Your ProjectMake your first API call.
Get an app key, connect to your app, and make your first request. Your key is at /keys: set SUBSTRIO_URL and SUBSTRIO_KEY, and ask who you are. Every operation is reachable the same way over HTTP, as an MCP tool and from the CLI.
curl -s "$SUBSTRIO_URL/v1/_whoami" \
-H "Authorization: Bearer $SUBSTRIO_KEY"Getting started walks from nothing to a deployed function. MCP connects an agent.
Getting started
- Getting startedGet a key, create an app, push a function, try it on a sandbox, then make it live and call it.
- QuickstartWalk one path three ways, over HTTP, the CLI and MCP, from an app key to a deployed and invoked function.
- InstallInstall the CLI, SDK and client packages from npm.
- Project filesDeclare functions, collections, roles and auth providers as files, so the sandbox and production build from the same source.
- Bring your projectMove an existing backend to substrio in order: data, sign-in, routes, jobs, mail, files, secrets, tests, deploy.
Concepts
- Accounts and appsCreate an account for your team, then create an app under it for each project you deploy.
- VersioningAn app has one history: push a commit, move a branch or a tag, merge, diff and garbage collect it with git-like verbs.
- Test hosts and root domainsBind a sandbox to its own host, try a version there, then promote straight from that host to live.
- Plans and limitsRead what bounds one function call, one app and one key, and how an account's plan sets those bounds.
- GlossaryLook up a term used across these docs: what it names, and where to read more.
Best practices
- Data modelingPick collections and ids, declare schemas and unique fields, index for the queries you run, and choose KV, SQL, the ledger or files when a collection is the wrong shape.
- KeysPick the right kind of key for the caller, rotate it without downtime, and never let one reach function source.
- Versions and test hostsShip a change through a pushed version, try it on a sandbox or its own host, promote it, and roll back when it goes wrong.
- Plan limitsRead your limits and usage before you hit them, and know what each refusal means.
- Errors and retriesBranch on the typed error code, retry only what the envelope says is safe, and keep a retried write from running twice.
- Security and permissionsGate collections with security rules, gate function routes by sign-in, require a verified email or 2FA where it matters, and keep secrets and outbound calls scoped.
MCP and agents
- MCPConnect Claude Code, Claude Desktop, Cursor or any MCP client to an app's tools with no server code of your own.
- Agents over plain HTTPSEvery tool an agent reaches over MCP is also one plain HTTPS call, by the same name, with the same credential and the same answers. An agent that can make a request needs no MCP client, no SDK and no OpenAPI file. An agent that can only open links: [Agents that can only open links](#agents-that-can-only-open-links).
- Let your users' agents use your appYour users connect their own AI agents to your app's MCP endpoint with their own credentials, and each agent calls your tools as that person.
- Agent sessionsAn agent session lets an AI agent act for a person in one account. The person chooses what it may do: which apps, which capabilities, and whether it may write. Every call the agent makes is logged for the account. Calls that cannot be undone wait for a person to approve them. Any member of the account can end a session at once.
- Building on substrioBuild and ship an app on substrio as an AI agent, over MCP or plain HTTP with the same results.
- Agent workflowRun one loop as an AI agent holding an app key: discover, write a function, deploy to dev, fix, promote, roll back.
- Agent shellThere is no process and no host file system. The command is a POSIX shell subset interpreted inside the server, and every command is a builtin that works on your app's own stores. Nothing outside your app is reachable from it: there is no `..` past a mount, no symlink, no device, no network.
- Agent function toolingRead, search, check and edit a deployed function's source and environment through typed HTTP endpoints built for small, bounded calls.
Capabilities
- Schemas, namespaces and viewsDeclare a collection, set its schema, inspect its namespaces, and build materialized or live views over its data.
- Query languageFilter, sort, page and aggregate a collection's documents with a JSON where clause.
- Chain queries over the APIRun the same filter, sort, join and aggregate plan your JS chain builds, as one typed JSON request.
- SQL over the APIRun parameterized SQL over HTTP or MCP against an app's data, with batched transactions and schema introspection.
- Key-value storesStore and read bytes by key from a function, with typed numeric counters, prefix scans and a byte cursor.
- FilesStore, list, download and delete an app's files by path, over HTTP or from a function.
- RealtimeOpen a WebSocket to a collection or one of its fields and receive an event the instant a write commits.
- Queues and background jobsSend a message from a function to a named queue and have another function consume it in the background.
- SchedulesRun a deployed function on a cron schedule, with retries, catch-up and a run history.
- SecretsWrite, list and delete the named values your app's functions read as environment variables.
- App archivesDownload your whole app as one `.substrio.zip`: a backup you can restore and an export you can read.
- Users and authSign users up, sign them in with a token, and gate routes and records by role, permission, or ownership.
- PermissionsThree layers check every request, in order, each a single bitmask AND or flag check.
- EmailSend mail from a function over SMTP, and name the function that sends your app's sign-in, verification and invite mail.
- LedgerPost signed entries in minor units against a kind, a party and a currency, and read balances kept current without summing entries.
- Multi-document transactionsRun insert, update and delete operations across collections in one call, all committed or all rolled back.
- Vectors, geo and RAG searchIndex a collection's vector, geo or sparse fields, then query them with k-nearest, bounding-box and RAG search operators.
- App dashboardsAn app declares an admin dashboard for its owners in one file, `dashboard.json`. The owners are the members of the account that holds the app, and for a featured app (a jet), each customer account that enabled it. The Substrio console draws the dashboard with its own components when an owner opens the app: its pages, numbers, charts, tables with filters and paging, records, forms, and buttons that act on a row. No console release and no hand-written console page are needed, for Substrio's own jets and for every app an agent builds. What the app's own users see is the app's own site; the dashboard is the owners' side.
- Graph storage and analyticsStore directed edges between integer node ids under a label, then read neighbors, degree and run graph analytics over them.
- Calls and reads between appsCall a function or read a query that another app offers, with no HTTP and no shared code.
- Custom domainsAttach, list and detach your own domains, so your app answers on them as well as on its default subdomain.
- Static sitesDeploy a directory as a release and serve it with clean URLs, a real 404 page, and cache headers.
JavaScript runtime
- Function runtimeWrite JavaScript functions with db, substrio, env and fetch in scope, under call limits that carry between calls.
- JavaScript, Lua and cloud functionsDeploy JavaScript functions that run next to your app's data, and run Lua scripts over its Redis-compatible keys.
- Cloud functionsDeploy server-side JavaScript functions that run next to your data, with direct access to collections, SQL and key-value stores.
- Runtime API referenceEvery global, type and module a function can call, with its signature, read from the declarations the server serves.
- ServicesCall the function's own app as its API, call another function directly, and reach its files, kv, graph and auth from one object.
- Collections and chainsRead, filter, sort, join and write JSON documents from a synchronous chain of calls on a collection.
- Chain referenceLook up every chain method's signature, arguments, answer, errors and a runnable example on one page.
- Records and query resultsRead a row from a collection as a live record, assign its fields, and write them back with one call.
- SQLRun synchronous SQL, with typed parameters, prepared statements and transactions, over MariaDB 12.3 syntax.
- Durable objectsExport a class as an object with one live instance per id, calls to it serialised one at a time, and state in the app's database.
- Concurrency and async callsRun async work inside a function call, and know which state concurrent calls of your app share.
- Errors and logsRead what a thrown error leaves behind, read a function's console output back, and set up drains and alerts on its log.
- Function errorsRead the typed record a function's throw leaves behind, with its parsed stack frames, by request, function or revision.
HTTP API
- HTTP APICall any operation over plain HTTP: pick an app by host or header, send a bearer key, and get typed JSON back.
- API contractsCall one operation over HTTP, MCP or the CLI with the same arguments, and get the same result and the same errors back.
- Functions operationsWrite, check, run and inspect the JavaScript functions of the app: source, history, environment variables, invoke and eval.
- Deploy operationsShip the app: push a version, check it, try it in a sandbox, make it live, roll back.
- Data operationsCollections of objects, records, key-value pairs, graph edges, views, import and export.
- Query operationsRead data: SQL, typed chain queries, counts and aggregates.
- Schema operationsCollection schemas, SQL indexes and their state, namespaces, security rules.
- Schedule operationsCron schedules and their run history, collection triggers, webhooks, background jobs.
- Files operationsStatic site releases, uploaded files and installed tools.
- Config operationsSecrets, tenant settings, function environment variables, the MCP tool manifest.
- Access operationsEnd users, roles, authentication providers, rate limits, agent tokens.
- Realtime operationsPublish live events, stream them to clients and read their counters.
- Observability operationsFunction logs, thrown errors, usage and limits.
- Backup operationsBackups, restore, cloning into another app and whole-app export.
- AI operationsSearch, retrieval, threads and the AI configuration of the app.
- Account operationsThe account that owns apps: members, keys and apps.
- Platform operationsHealth, documentation, the app overview, its keys, limits and domains.
- ErrorsA failed call answers one JSON envelope with a stable code, an HTTP status and a hint for what to do next.