RumataBackends and bindings
Contracts for hosting APIs, containers and workers on Rumata: configuration, access, runtime policy, builds and frontend bindings.
Step-by-step guidance.
Before you start
- A factory with permission to create and configure backend services.
- For the Studio walkthrough of service sources, see Build and connect backend services.
Choose a backend or a workflow
| Need | Use |
|---|---|
| App API, CRUD, authorization, a third-party container, a hosted agent | A managed backend service. |
| ETL, cron, heavy pipelines, delegated asynchronous jobs, standalone AI endpoints | A workflow. |
| A mix, such as generate then save, then edit later | A workflow for generation and saving, a backend for later reads, edits and deletes. |
Host on Rumata unless the user explicitly requests external hosting. A vendor’s VPS installation guide describes application requirements; translate them into a backend configuration instead of asking for an external server or hosting credentials.
Configure, develop, build, deploy
- Inspect `rumata.getFactoryBuilderContext` and `rumata.listBackendServices`. An empty list means “create a service”, not “hosting is missing”.
- For a new API, scaffold the verified `node-api` starter and use its repository-owned Dockerfile configuration, then read its README. Preserve existing services and explicit native-runtime choices. Existing third-party applications keep their own runtime.
- Register the service with `rumata.configureBackendService`. Creation passes `{config: {...}}` and omits `serviceId` and `expectedRevision`; an update needs the existing ID and the current revision. A local manifest alone does not register a service.
- Start the development process with `rumata.runBackendServiceAction` action `ensureDevelopment`. A `starting` result is provisional: wait for readiness and prove a real API response. Development uses working-tree code and real integrations.
- Build repository source and read the completion before deploying. Deploy prebuilt images directly. A saved configuration, a successful build or a running development process is not a release.
- Inspect `rumata.getBackendService` until the deployment is ready or failed, then verify a representative request with `rumata.debugBackendRequest`.
Access and publication
- The default is `accessMode:rumata_permissions`. A new backend receives Public execute permission after deployment unless a project rule says otherwise; existing services and explicit restrictions keep their permissions on update or redeploy.
- The `direct` mode bypasses Rumata invocation permissions for the public. It is not needed for isolation; keep the default.
- Rumata permissions admit a caller to the service. Authorizing end users and their data stays in your backend code.
- Managed preview requires Studio authorization even for a public app, supplied by the browser bridge or `rumata.debugBackendRequest`. A raw anonymous preview 403 is not an application authentication failure, and publishing is not a workaround.
Runtime policy and persistence
| Policy | Use it when |
|---|---|
| `sleep_when_idle` (default) | On-demand services. They wake on a real request. |
| `always_on` | The user requests continuous execution. |
| `stop_after_duration` | A fixed runtime is requested. It expires even while busy and needs redeployment. |
A worker with HTTP disabled cannot wake from an HTTP request, so choose its policy for the worker’s lifecycle. Do not assume the container filesystem survives replacement. Use the factory database for relational data and managed storage for files. A persistent disk is for software that needs a filesystem: it requires a single replica, counts against storage while stopped, has no automatic backup, and is never mounted in development.
Connect the frontend
Copy `getBackendService.frontendBinding` into `rumata.backends.json` under a `VITE_*` key and call it from the frontend. Keeping typed clients under `src/api/` is a maintainability convention, not a routing requirement. A binding is a base path without a trailing slash. It can be relative in preview and absolute in production, so join paths as shown in Technical details. The binding is configuration, not a secret or an access grant.