The serverless backend
The backend is built from AWS managed services:- API Gateway serves two APIs: the REST API at
api.blobhub.io/v1, and the WebSocket API atrealtime.blobhub.io/v1. - Lambda runs the code: the authorizer that checks a request’s credential, the handler behind every route, the background workers, the router that matches new session events to listeners, and each step of a workflow run.
- DynamoDB holds the records: users, organizations, members, keys, credentials, limits, sessions and their threads, executions, schedules, and the event logs. A DynamoDB stream on a session’s event log feeds the router.
- S3 holds content: workflow definitions, uploaded models and session files.
- SQS carries work that outlives a request: lifecycle changes and the start of each run.
- Step Functions drives each workflow run, one component at a time.
- EventBridge Scheduler fires each schedule at its moment.
The request path
Every REST request takes the same path, whoever sends it. One authorization shape. Apart from signing in, refreshing a token and a health check, every REST request carries a bearer token or an API key. Before the handler runs, the authorizer verifies it and reduces it to one shape: the target the caller is scoped to, the caller’s identity and a role, plus the person behind it when a person is acting as a service account. Handlers decide what the request may do from that shape alone, never from which credential produced it. A handler does the work. Most requests are answered inline: a read or a write against DynamoDB or S3, and a response. Long lifecycle changes are queued and polled. Creating a blob, creating, committing or deleting a revision, and deleting a blob take longer than one request. The handler validates the change, records that it has begun, queues the rest on SQS and answers at once; you learn how it ended by reading the blob or revision again until its status settles. How BlobHub works covers these operations. A run is executed by Step Functions. Creating an execution resolves what to run, checks access, copies the definition into the run’s own snapshot and records the run, then queues its start. Step Functions prepares the run and executes it one component at a time from that snapshot, each step a Lambda invocation, writing every step to the run’s event log. A schedule’s fire arrives from EventBridge Scheduler and creates its run through the same command a client sends. Clients page a run’s log. A run’s component events are not pushed to the caller. A client reads the run’s event log a page at a time, from a cursor at the last event it has, and a client that was offline catches up the same way.Live updates
Everything that happens in a session is appended to its stream: an object written or deleted, an item posted to a thread, a batch of changes applied to a graph, the session being created, edited, reopened, closed or deleted, and the creation, start, stop request and end of every run in it. A DynamoDB stream on that log feeds a router, which matches each new record against the session’s listeners and pushes it to the WebSocket connection of each one that matches. A client connects to the WebSocket API, initializes the connection and adds a listener to one session, filtered to the event types it wants. The connection is outbound, so a client behind a firewall needs nothing opened. A push is at least once and can be lost, so a client that must not miss an event also catches up by id: on connecting, and on a timer while connected, it lists the stream after the last id it holds, starting a minute earlier because a row can commit up to a minute after the time in its id, and drops the ids it already has. Polling is the fallback, and it is the same read. The web app’s playground and debugger and the worker listen, and read the stream on a timer only while no connection can be made. The SDK and the CLI never connect: they page the logs on a timer, from a cursor at the last event they read, so one path serves a client that is watching and one that is catching up. A run’s progress component by component is never pushed; it is written to the run’s own log and read a page at a time.The worker on your infrastructure
The worker is the one long-running part of BlobHub outside the cloud: on a laptop, a server or a container of yours, where the coding agents it runs can reach your files, your tools and your own model accounts. It holds no special standing in the platform. It is an ordinary API client acting for the identity its profile names, calling the REST API over HTTPS with that identity’s key and listening to each session it is attached to over a WebSocket it opens itself, polling at an adaptive rate only when it cannot. Nothing in the cloud reaches into it: it opens every connection, so it still needs no inbound one. What it does arrives as thread items it posts, the same as any other client’s. Agents & workers covers what it runs.Principles
- Every change a screen makes to your work is a REST call. The web app keeps none of your work itself: definitions, sessions and runs live behind the API, so saving a graph in the editor uploads a definition, a playground’s chat creates an execution, and closing a session from the debugger sends the same command the CLI or the SDK would. Nothing is reachable only by clicking. What stays in the browser are your preferences, such as the theme, pane widths and the revision you picked. The reverse is not a goal: plenty of the API has no screen in the web app.
- One data format. A schedule, the target a run names and a workflow reference have the same fields in the REST API, the CLI’s manifests, these docs and the web app. No surface renames a field or folds an object into a string of its own, except a workflow reference’s one-string path form, kept for a CLI argument, the SDK’s run call and the web app’s chat widget.

