Reference

Runtime Ctx

The server-side Userland runtime context available to app modules.

For agents: Server code receives only request and scoped ctx; use those helpers instead of platform internals.

Shape

ctx.app.app_id
ctx.app.origin
ctx.app.release_id
ctx.auth
ctx.data
ctx.files
ctx.secrets
ctx.jobs
ctx.webhooks
ctx.log

Server modules can export fetch, job, and webhook handlers.

Server module

export default {
  async fetch(request, ctx) {
    return Response.json({ app_id: ctx.app.app_id });
  },

  async job(event, ctx) {
    ctx.log.info("job received", { name: event.name });
  },

  async webhook(event, ctx) {
    return Response.json({ received: true });
  }
};

Request handling

fetch(request, ctx) handles dynamic HTTP requests when static routing does not match and runtime.fallback is server.

Use standard Web APIs: Request, Response, URL, Headers, and Response.json.

Data

const posts = ctx.data.collection("posts");
const post = await posts.create({ title: "Hello", slug: "hello" });
await posts.update(post.id, { title: "Hello world" });
const page = await posts.list({ where: { slug: "hello" }, limit: 10 });

Rows are scoped to the app and expose declared fields plus id, created_at, and updated_at.

Secrets

const apiKey = await ctx.secrets.require("OPENAI_API_KEY");
const optional = await ctx.secrets.get("OPTIONAL_TOKEN");

Secret values are available only to server runtime code.

Auth

const user = await ctx.auth.currentUser(request);
const admin = await ctx.auth.requireRole(request, "admin");

Auth helpers work when the app declares auth.mode: "app_users".