Workflow runtime

Learn about the different task runtimes
A runtime determines how your task's code is executed. By default, Airplane executes tasks on the standard runtime in which code is executed on a server, similar to how you would execute a script locally. For long-running tasks, Airplane supports the workflow runtime which enables developers to write orchestration logic as code.

Comparison
The following table compares the two runtimes:
Configuring a runtime is an advanced feature. If you are new to Airplane, start with the standard runtime.
StandardDefaultWorkflowBeta
General use caseRun scripts on serversOrchestrate long-running processes
Execution timeUp to 12 hoursUp to 60 days
Programming modelArbitraryDeterministic and side-effect free
ResumableNo✅
RetriesNo✅
Child runs✅✅ Up to 1000 child runs
Prompts✅✅
Sleep✅✅
Self-hosting✅✅ - Requires the v2 agent. See Self-hosting.
Configurable timeout✅(Coming soon)
Network and file I/O✅No - See Common invalid operations.
Language supportJavaScript, Python, Shell, DockerJavaScript (Python coming soon)
Both runtimes support all task features (e.g. Logs, Output, Prompts, and Schedules). The exceptions are documented in the table above.

Configuring a runtime
Tasks have a runtime field that defaults to "standard". This can be overridden to "workflow" in your task's configuration:
typescript
Copied
1
import airplane from "airplane";
2


3
export default airplane.task(
4
  {
5
    slug: "my_task",
6
    // The line below configures this task to use the workflow runtime:
7
    runtime: "workflow",
8
  },
9
  async () => {
10
    // Add your workflow code here.
11


12
    return "Hello, world!";
13
  },
14
);

Workflow runtime overview
Unlike the standard runtime, the workflow runtime can arbitrarily pause and resume runs. This happens automatically whenever a run is waiting for external operations to complete. This offers a few important benefits over standard runs:
  1. Workflow runs can execute for much longer—up to 60 days!
  2. Workflow runs do not consume resources while waiting for operations to complete. Airplane does not charge for compute time on hosted agents, but customers who run self-hosted agents benefit from these resource savings.
  3. Workflows runs that encounter unexpected errors—such as the underlying server dying—are safely resumed elsewhere without losing any progress.
Pausing and resuming are performed automatically by Airplane. Pausing is not an explicit operation, but instead implicitly based on the operations that a workflow can perform (e.g. waiting for a child run to complete or for a prompt to be submitted).
The workflow runtime offers these features by running code in a restricted environment where the only external operations allowed are those exposed by the Airplane SDK (e.g. executing tasks and built-ins, creating prompts, etc.). The runtime maintains a history of the output returned by each of these operations and—if the workflow is paused—can resume the workflow by replaying those outputs instead of re-performing the operation.
This is a concept known as the durable programming and popularized by products like Azure Durable Functions and Temporal. Under the hood, the workflow runtime runs on Temporal, allowing you to write durable programs with all the benefits of Airplane Tasks.
In order to resume workflow runs, the runtime requires that runs are:
  • Deterministic: When run with the same execution history, a workflow must always perform the same operations in the same order.
  • Side-effect free: Workflows cannot perform side-effects (e.g. directly performing API requests), otherwise those side-effects would get executed every time the workflow is resumed. Instead, workflows should use the Airplane SDK perform side-effects, such as executing other tasks.
We discuss common sources of non-determinism and side-effects below.

Limitations
As mentioned earlier, there are a few restrictions on runs within the workflow runtime:
  1. Runs must be deterministic.
  2. Runs must be side-effect free.
  3. The only external operations allowed are those exposed by the Airplane SDK.
For the most part, the runtime mocks out common sources of non-determinism. For example, Math.random and the Date constructor are both mocked such that they return deterministic values. Other libraries that generate randomness—such as those that generate random UUIDs—cannot be used.
Common sources of side-effects include performing network I/O (e.g. HTTP requests via fetch) and file I/O (e.g. trying to read/write files to disk via the fs package).
Instead, execute a standard-runtime task that performs the desired operation. For example, instead of directly performing a fetch call in a workflow, move the fetch call to a JS task and call that (or use the REST built-in).
Since the vast majority of Node.js APIs produce side effects, all Node.js APIs are disabled within workflows. When Airplane builds a task for the workflow runtime, it will produce an error if it detects that your code is using a Node.js APIs.
There are a couple of notable exceptions:
  • All of the console methods, such as console.log, are allowed.
  • Environment variables can be accessed via process.env.
All of the methods exposed by the Airplane SDK—such as executing tasks or built-ins and creating prompts—are safe to call from within the workflow runtime. In other words, the operations exposed by the SDK are what allow you your workflow to perform side-effects.

Self-hosting
The workflow runtime requires a sufficiently recent version of the Airplane agents.
To check, open the team settings page and confirm your agent's version is prefixed by v2:
If you are not running v2 agents, you can upgrade by following the Self-hosted agents instructions.
The Docker agent does not support the v2 agent format. If you are running Docker agents and wish to self-host workflows, you will need to deploy one of the other agents.
PrivacyTermsSupport