How Automations Work

This page explains what Type does from a trigger to the end of a run.

The parts of a run

Trigger: a schedule, a Slack message, a GitHub event, a webhook, an email, or a feed item
  └─ Type saves the event
  └─ Filters run on the server
  └─ The run starts
       ├─ Instruction automation: the managed agent runs the instructions in a new thread
       └─ Code automation: your method runs in a new VM
             ├─ calls connected apps and the sandbox through ctx
             └─ can hand a step to the managed agent
  └─ Run history records the output, the steps, and any errors

	Instruction automation	Code automation
What runs	The managed agent, in a new thread	Your TypeScript method, in a new QuickJS VM
Skills	The managed agent loads named skills and finds others	Through a handoff to the managed agent
Sandbox	The managed agent’s sandbox	One sandbox for the automation, through `ctx.tools`
Acts as	The automation creator, for scheduled runs	The automation creator
Run time	One managed agent turn	180 seconds for the code. A handoff runs after the code.
After a failure	A schedule pauses after three failed runs in a row	The automation pauses after the first failed run, and a repair starts

The rest of this page describes code automations in detail.

Deploy a code automation

type-cli automations deploy
  └─ validation    typecheck, read the deployment export, check the class
  └─ fixtures      run adapter fixtures and fixtures.json
  └─ subscription  check connections and events, register each subscription
  └─ activation    save the revision and enable the automation

Type reads the deployment export in an isolated VM with no credentials. No code runs on your computer.
Each deploy makes an immutable revision. A failed deploy does not change the active revision.
The automation belongs to a Space and to the person who created it.

Run a code automation

Event or schedule
  └─ Type saves the event
  └─ Resource filters and the matcher run on the server
  └─ Debounce groups events, if set
  └─ The run waits in the automation's queue
  └─ A new QuickJS VM runs your method with (ctx, event)
  └─ Type saves the output, the checkpoint, and the handoffs
  └─ Handoffs start, if any

The VM

Each run starts in a new QuickJS VM. The VM:

runs the saved code of the active revision,
has no fetch, no file system, no shell, and no Node or Bun APIs,
can import only the SDK, zod, neverthrow, and your project files,
discards console output,
stops after 180 seconds.

Your code reaches the outside only through ctx. Type checks each call. For shell work, ctx.tools can call a separate sandbox.

One run at a time

An automation runs one method at a time, for all its subscriptions. Other runs wait. Different automations run independently.

Access and identity

A run uses the access of the person who created the automation, and the connections of its Space.
Type gives each run a short-lived token. The VM never gets a provider credential.
Type checks the connection’s access for each event and each call.
An AI agent in a thread can have more access than the automation. A call that works in a thread can fail in the automation.

State

State	Where	Lasts
Checkpoint	`ctx.checkpoint`, `ctx.saveCheckpoint()`	Until the next successful save. One for each subscription.
Output	`ctx.setOutput()`	In run history. Code cannot read it.
Saved data	`ctx.read.data`	Read only from code.
Sandbox files	The sandbox	Until Type replaces the sandbox. A cache only.
Variables and class fields	The VM	One run.

Type saves the checkpoint, the output, and the handoffs together, after the method succeeds. Writes to other apps happen when you call them. They are not part of this save. See Write Safely.

Guarantees

Type does	Type does not
Save each verified event before it starts work.	Promise the order of runs.
Run a provider retry with the same event ID only one time for each subscription.	Make external writes exactly once. An effect key does not prevent a second write.
Save the checkpoint only when the method succeeds.	Save the checkpoint of a failed run.
Pause the automation after the first failed run, and start a repair.	Retry a failed or interrupted run automatically.
After a repair, run the original event one time to verify the fix. This run has real access and can repeat writes.	Undo the writes of a failed run.
Keep events that it saved before a pause, and run them after resume.	Save events that come during a pause.
Continue a schedule at its next planned time.	Run missed schedule ticks.

Failures

A failed run pauses the automation. Type starts a repair agent, tests its fix with fixtures, then runs the original event one time with real access to verify the fix. If verification succeeds, Type resumes the automation. Reconcile the failed run’s writes before verification. See Troubleshoot and Fix Failed Runs.

Report a bug