Runtime SDK - Tinycloud

A worker entrypoint must default-export tiny.app(handler) from @tinycloud/runtime-sdk. The handler receives standard Web Request and Response objects plus a verified Tinycloud context.

import { tiny } from '@tinycloud/runtime-sdk';

export default tiny.app(async (request, context) => {
  context.log('info', 'request received', { url: request.url });

  return Response.json({
    user: context.user?.email ?? null,
    requestId: context.requestId,
    environment: context.environment,
  });
});

Unhandled handler errors are converted to a JSON 500 APP_ERROR response and written to the deployment log.

The SDK is supplied by the runtime and the build image. An application does not declare it as a dependency.

Context

Property	Type / behavior
`user`	verified user or `null`; includes ID, email, app role, groups, and assurance
`requestId`	request correlation ID
`appId`, `appSlug`	current app identity
`environment`	environment name
`deploymentId`	current immutable deployment
`db`	declared database, or a descriptive error on use when absent
`storage(name?)`	declared object namespace; the name may be omitted when only one is declared
`capabilities.invoke(operation, input?)`	call a granted broker operation
`fetch(input, init?)`	outbound fetch checked against manifest egress rules
`log(level, message, fields?)`	structured deployment log event
`audit(action, detail?)`	structured `app.audit` event in deployment logs
`secret(name)`	resolved secret value or `undefined`

Identity is derived from a short-lived platform token verified by the runtime host.

Client-supplied Tiny-* headers are stripped at the gateway and are not exposed to app code. Never trust a header for identity — use context.user.

Database

context.db is not a connection. A microVM is replaceable, so the database lives outside it, and the app is given no host, path, or credential to leak. Statements travel over the VM’s private link to the control plane, carrying the deployment’s own workload token; the control plane resolves that token to exactly one environment’s database.

const rows = await context.db.query<{ id: number; title: string }>(
  'select id, title from notes order by id desc limit ?', 20,
);

const row = await context.db.get<{ count: number }>(
  'select count(*) as count from notes',
);

const { changes } = await context.db.execute(
  'update notes set title = ? where id = ?', 'Updated', 42,
);

await context.db.transaction(async () => {
  await context.db.execute('delete from notes where id = ?', 42);
});

Available methods are query, get, execute, and transaction. A failed transaction rolls back automatically. Parameters are always bound, never interpolated, whichever engine is behind the binding. Write the placeholder syntax your engine uses: ? for SQLite, $1 for Postgres.

Value types over the wire

Rows reach your app as JSON over the private link, so values arrive as the JSON type that can hold them without losing anything. That sometimes means a string where you might expect something richer:

Postgres type	Your app receives	Notes
`timestamptz`, `timestamp`	ISO 8601 string	`new Date(value)` is exact. A bare `timestamp` is read as UTC.
`date`	`'2026-08-22'`	A calendar day, deliberately not an instant: `new Date('2026-08-22')` is UTC midnight and renders as the day before anywhere west of Greenwich. Compare and store it as text.
`numeric`	string	Arbitrary precision; a float would silently round it.
`int8`	number, or a decimal string past 2⁵³	Beyond that a JSON number would lose digits.
`bool`	boolean
`json`, `jsonb`	parsed value
`bytea`	base64 string
`NULL`	`null`

Binary goes the other way as itself: pass a Buffer or Uint8Array as a parameter and it is bound as bytes, not as text.

Transactions are leased sessions

transaction opens a server-side session with a short lease rather than a lock the app holds. Two consequences are worth knowing:

Nesting is refused, not flattened. A flattened rollback would quietly commit work the caller believed was undone.
The lease expires. A transaction left open past the timeout is rolled back and its session reclaimed, so a crashed guest cannot hold a write lock or a pooled connection indefinitely. Keep transactions short, and never wait on a slow remote call inside one you need to commit.

Bounds

The platform bounds what one request may ask for: statement size, parameter count, result rows, and result bytes. A query that would return more than the row limit is refused rather than streamed — add a LIMIT and paginate. On SQLite, one write transaction is open per environment at a time; a second begin is refused with that explanation rather than blocking. Postgres serves several concurrently from its pool.

Object storage

Objects work the way SQL does: the guest holds no bucket, path, or credential, and every operation crosses to the control plane’s storage service over the private link under the deployment’s workload token. The token decides which namespaces the app may address, so a namespace another app declared is unreachable even by name.

const files = context.storage('files');
await files.put('exports/report.csv', csv);
const contents = await files.get('exports/report.csv');
const objects = await files.list('exports/');
await files.delete('exports/report.csv');

The name is the one from resources.storage[].name, and may be omitted when the manifest declares exactly one namespace. Asking for a namespace the manifest never declared throws before any request is made.

put accepts a string or Uint8Array and returns the stored object’s metadata.
get returns Uint8Array | null — null means that key is absent, while a missing namespace or a superseded deployment raises, so an unreachable namespace never reads as an empty one.
delete returns whether the key existed.
list returns objects sorted by key with key, size, lastModified, and etag, filtered by an optional prefix.

Keys must be relative and may not contain ..; anything that would escape the namespace is refused. Bytes cross the link raw rather than base64-encoded in JSON, so binary is stored exactly as given — the round trip is byte-for-byte, not UTF-8-normalized.

etag is a change validator derived from an object’s size and modification time, not a content digest. Two identical objects under different keys have different ETags. It is safe to compare an ETag with an earlier one for the same key to detect a change.

Bounds: an object is at most 32 MiB, a key at most 1024 bytes, and a listing returns at most 1000 keys per call. A namespace also has the maxSize its manifest declared, measured after the write, so replacing an object does not charge for the copy it replaces. Bytes moved are metered as storage_bytes.

Capabilities

const result = await context.capabilities.invoke<{ data: unknown[] }>(
  'stripe.payments.read',
  { status: 'failed', limit: 25 },
);

The SDK sends the workload token and, when present, the user token to the control-plane broker. The broker validates the grant, user-presence rule, input schema, constraints, rate limit, and response filter before returning.

Vendor credentials never enter the worker.

Outbound fetch

context.fetch is for declared direct egress. It checks host and effective port against network.egress. On Firecracker, allowlist mode is deployable only when the operator has set TINY_FIRECRACKER_ALLOW_EGRESS=true; the host then pins each declared hostname’s resolved addresses into that VM’s firewall. Otherwise planning rejects the manifest. Brokered capabilities remain the preferred path because application code never receives the vendor credential.

Logging and audit

context.log('info', 'export finished', { rows: 4210 });
context.audit('report.exported', { period: '2026-08' });

log writes a structured deployment log event at the manifest’s level. audit writes a structured app.audit event into the same log stream — use it for actions a person may later need to account for.

Secrets

const key = context.secret('REPORT_KEY');   // string | undefined

Only secrets the manifest declared are resolvable.

Runtime limits

The runtime host enforces the manifest request timeout and concurrency.

A timed-out process is retired after its response, because JavaScript promises cannot be forcibly cancelled. Do not rely on a timeout to stop work already in flight.

Limit	Value
Request body	5 MiB
Response body	10 MiB
Gateway upstream timeout	35 s

The gateway applies the same default size limits.

​Context

​Database

​Value types over the wire

​Transactions are leased sessions

​Bounds

​Object storage

​Capabilities

​Outbound fetch

​Logging and audit

​Secrets

​Runtime limits

Context

Database

Value types over the wire

Transactions are leased sessions

Bounds

Object storage

Capabilities

Outbound fetch

Logging and audit

Secrets

Runtime limits