World sessions

A session is one isolated running world pinned to a project, environment, build, seed, and starting setup. Creating a session never starts your agent.

Choose the starting setup

Create a session with exactly one of these choices:

Selection	Result
Neither `scenarioId` nor `drillId`	Start from the build baseline
`scenarioId`	Start from that reusable situation without a target or verdict
`drillId`	Prepare the task, target, assertions, and budgets needed for a drill run

Every session requires a decimal unsigned 64-bit seed. You may also pin an exact build hash and explicitly select approved callback receivers.

Connect your agent

The code below is an integration skeleton: implement runExistingAgent using your actual agent and its configuration boundary. Replace project, environment, and actor IDs with values from your project. When the session is ready, request access for one actor declared by its build. The returned binding contains short-lived world URLs, one world credential, expiry, and the exact operations that actor may call. Pass only that binding to your agent’s test configuration. Never give the agent a Firedrill control credential. A world credential cannot manage projects, create other sessions, or access another actor’s capabilities.

import { connect, FiredrillClient } from "@firedrill-run/cloud";

const client = new FiredrillClient({
  token: process.env.FIREDRILL_CREDENTIAL,
});

const world = await connect({
  client,
  projectId: "prj_...",
  environmentId: "env_...",
  actorId: "operator",
  seed: "42",
});

try {
  await runExistingAgent({
    httpUrl: world.binding.worldHttpUrl,
    mcpUrl: world.binding.worldMcpUrl,
    credential: world.binding.credential,
  });
} finally {
  await world.destroy();
}

Session controls

Control	Meaning
Reset	Restore the original setup, selected Tool packages, or an immutable snapshot
Advance time	Move virtual time with an explicit event budget and durable receipt
Set a fault	Enable or disable a fault declared by the selected build
Snapshot	Capture state, evidence position, clock, and pending work atomically
Fork	Create an independent session from an immutable snapshot
Extend	Increase the session lifetime within the server allowance
Destroy	Release the exact session

Reset changes world state, pending work, clock, and evidence generation together. It does not change repository source or silently select another build. Existing connection endpoints stay scoped to the same session, but SDK helpers may rotate the short-lived binding after a mutation. Unsafe controls require a stable idempotency key. If a request times out, do not assume it was undone. Recover the accepted asynchronous operation or repeat the exact request with the same key.

Starting a session, opening a Tool app, or manually calling a Tool does not mean an agent passed. Use a drill run when you need a verdict.

Get started

Tools and worlds

Test and inspect

Automate and collaborate

Core concepts

Source and reference

Choose the starting setup

Connect your agent

Session controls

​Choose the starting setup

​Connect your agent

​Session controls

Choose the starting setup

Connect your agent

Session controls