Skip to main content
A synthetic Tool has its own state and modeled clock. Controls apply to that Tool, not your agent’s process, model randomness, filesystem, database, or external services. For a manual instance, read its current identity and epoch first:
Set FD_INSTANCE_ID and FD_EPOCH from that response. Use a distinct saved idempotency key for each deliberate action.

​
Take a snapshot

Keep the returned snapshot ID. It identifies synthetic state, virtual time, pending work, and modeled randomness together.

​
Reset or rewind

Set FD_SNAPSHOT_ID to that retained snapshot. Re-read the instance to obtain its current epoch before a new restore:
tools reset performs the same snapshot restore. The snapshot must belong to the compatible instance lineage. Restore advances the epoch and invalidates previous connection grants; use the returned state and fresh connections afterward. History is retained. Restore does not erase a prior result or undo actions taken in a real external system.

​
Fast-forward modeled time

Set FD_TARGET_TIME_US to an explicit later modeled time in microseconds:
The event-processing bound limits scheduled work performed by that action. Inspect the returned outcome and pending work; a bounded advance may require further deliberate processing. Time travel does not accelerate model inference, skip your application’s OS timers, or make a live third-party job finish instantly.

​
Controls inside a simulation

A scenario sequence can declare Tool operations, snapshots, virtual-time advances, waits, restores, and target calls. Later target calls receive the appropriate refreshed bindings. Use the sequence schema to express the intended control order. Do not manipulate a run-owned instance from a separate manual workflow while its runner owns it.

​
Recover without repeating work

If an action’s response is uncertain, preserve its exact instance, epoch, input, and key. Reconcile the same request. Do not substitute a newer epoch or key merely to get past an error. Inspect firedrill tools history INSTANCE_ID --json to see retained action outcomes, including modeled time changes and restores.