Actor API

Run your actor on any host with a public HTTPS endpoint that accepts WebSocket upgrades. Register its URL with a project API key, then select the disk and instance in the invocation URL. wabe Cloud starts instances on demand and routes HTTP, SSE and client WebSockets through one upstream connection per live instance.

Create a project key

Create a project and an API key in the Dashboard. Replace YOUR_PROJECT_API_KEY with that key. The ncp_ key selects the project for registration and disk selection.

Register and invoke

Deploy the handler to your hosting provider. Replace the example endpoint with your public HTTPS URL. Generate a unique random base64url secret and set it on your handler and in the request. The actor room guide verifies this secret before reading the activation context.

Register an actor endpoint

curl --fail-with-body "https://api.wabe.sh/v1/actor" \
  -H "Authorization: Bearer YOUR_PROJECT_API_KEY" \
  --json '{
    "name": "chat",
    "endpoint": "https://chat.example.com/wabe",
    "endpointSecret": "YOUR_ENDPOINT_SECRET"
  }'

Registration returns 201 with metadata of this form.

{
  "id": "779742ad-cd09-4e1c-9170-f20968b344d4",
  "name": "chat",
  "endpoint": "https://chat.example.com/wabe",
  "fetchUrlTemplate": "https://api.wabe.sh/v1/actor/chat/disks/{disk}/instances/{instance}/fetch"
}

Method	Route	Effect
POST	/v1/actor	Register the URL. Return 201.
GET	/v1/actor	List registrations as an array in the authenticated project.
GET	/v1/actor/{name}	Return one registration.
PATCH	/v1/actor/{name}	Change endpoint, endpointSecret, or both. Return updated metadata.
DELETE	/v1/actor/{name}	Revoke its sessions and remove ingress. Return 204.

Actor and instance names contain 1–128 ASCII letters, digits, underscores or hyphens. Endpoint URLs use HTTPS with a DNS hostname and optional path, without user info, query or fragment. Secrets use 32–256 base64url characters and are write-only. Management returns 400 for an invalid endpoint URL, 401 for an invalid project key, 404 for a missing actor, and 409 for a duplicate name. Distinct projects can use the same actor name.

Invoke an instance

Call an instance on a named disk

curl --fail-with-body \
  'https://api.wabe.sh/v1/actor/chat/disks/customer-42/instances/room-7/fetch/messages?limit=20' \
  -H 'Authorization: Bearer YOUR_PROJECT_API_KEY'

The gateway resolves the actor and disk within the key’s project and creates the disk if needed, subject to the organization’s disk quota. The same actor, disk and instance share one live handler and connection set. Changing the disk or instance selects another handler. Instances using the same disk share its persisted data.

This route supports HTTP, SSE and WebSocket. The handler sees the suffix and query, such as /messages?limit=20. The gateway consumes the project key in Authorization. It forwards application cookies and other application headers. Use the project key from your server and authorize your application users there before selecting their disks.

For public ingress with one fixed disk, supply an existing project disk as disk when registering. The response includes that disk and the UUID-based /v1/actor/{actor_id}/instances/{instance}/fetch template. This route forwards the application’s Authorization header and uses the fixed disk for every instance. Existing registrations keep their public URLs.

Endpoint or secret changes fence every current generation and revoke its refresh family. Reconnect to the same URL to activate against the updated settings. The owning broker closes stale clients on its next authority check, with an idle check every ten seconds. After deletion the old ID returns 404. Reusing the name creates a new actor ID. New disk operations from a fenced generation fail, while admitted operations may finish. Refresh continues at POST /v1/runtime/sessions/{session}/refresh. See the transport protocol and credential lifetimes and limits.

Endpoint validation

Registration and updates validate the URL format. On each activation the broker resolves the hostname and rejects the entire answer if any address is non-public, including loopback, private, link-local and metadata addresses. The broker dials a validated address directly, verifies the TLS certificate for the registered hostname, and rejects redirects. Failed activations return 503.

Credentials and limits

WabeDisk.fromProps(ctx.props.wabedisk) validates context without a network request. It preserves an immutable disk binding and sends access only to that disk API. Access lifetime is 300 seconds; refresh occurs on demand when fewer than 30 seconds remain. It works after long idle intervals and does not use periodic timers or client WebSocket messages. Each live generation shares one credential manager and refresh family. The seven-day absolute family lifetime is not extended by refresh.

Refresh rotates a random secret through HTTPS. Same-input/same-key retries recover the encrypted result for ten minutes while its issued generation remains current. A consumed secret reused for a different attempt revokes its family. Refresh responses are no-store. Access tokens have fixed ES256/type/audience/issuer validation; actor tokens also require current generation and a live owner lease on every new disk operation. Admitted writes may finish after a stop. There are no distributed transactions across actors or external effects.

Private fleet/control routes and disk creation/catalog access require their own credential classes. Public reserved storage lifecycle routes are absent. Cross-disk data access is rejected before disk placement. Endpoint updates, deletion and broker takeover fence new operations from old actor generations.

Initial operator limits are intentionally explicit and have not been capacity-qualified:

Limit	Default
Broker owner lease / renewal	30 seconds / 10 seconds, using database time
Worker startup / client admission	30 seconds / 10 seconds
Instance HTTP response-header wait	60 seconds after dispatch
Application frame / HTTP chunk	65,536 bytes before base64
Queue frame count	32
Client / instance / broker queued bytes	262,144 / 8,388,608 / 33,554,432 bytes
Connections per instance / broker	128 / 1024
Live instances per broker	256
Concurrent instance HTTP responses per broker	256
Concurrent runtime ingress/control handlers	256
Named instances per actor	1024, including stopped names
Refresh	120 per minute per session
Actor HTTP/connection ingress	600 per minute per actor; relay does not charge twice

Queue limits cover retained application queue data/reservations, not total process RSS, TLS/TCP buffering or user JS memory. Stream bodies use bounded chunks and credits. A full client queue closes that client with 1013; aggregate limits can reject work. The platform operator configures these limits. Startup/routing/authorization add coordination cost; latency, capacity and cost improvements have not been measured.

Consumed refresh hashes survive until family expiry; encrypted retry responses expire after ten minutes. Cleanup processes bounded batches, retaining session audit metadata for an additional seven days after expiry and while referenced by a named instance. Named instance identities are retained.