Automations

An automation is a TypeScript program exported from a *.automation.ts file. Its description identifies it during deployment and execution. Automate.ax provides durable triggers, integration authentication, deployment, and execution.

automations/archive-receipts.automation.ts

import { automation } from "automate.ax"
import { gmail } from "automate.ax/gmail"

export default automation("Archive incoming receipts", () => {
  const email = gmail.onNewEmail()

  gmail.archiveMessages({ messageIds: email.messageId })
})

The default export must be the value returned by automation(description, fn). The callback defines the automation’s triggers, actions, signals, and dependencies.

Use Bun APIs and packages

Deployed project code runs on a pinned Bun 1.4 runtime. Custom action handlers can use Bun’s built-in APIs, standard Web APIs, compatible Node.js APIs, and packages from the npm registry. See Bun runtime for dependency setup, image processing with Bun.Image, compatibility guidance, and serverless constraints.

Connect triggers, signals, and actions

Concept	Role
Automation	A named program deployed as part of a project.
Trigger	Declares the event that can start the automation and exposes its data as a signal.
Signal	A reference to a value that materializes during execution.
Action	Performs work after its signal dependencies are ready.
Integration account	Gives actions and triggers access to an external service without exposing credentials to code.
Deployment	Resolves authorization, configures event sources, and publishes the project runtime.

In the example, gmail.onNewEmail declares a Gmail subscription and returns the incoming email as a signal. Passing email.messageId to gmail.archiveMessages makes the action depend on that event data.

Source order describes the automation, but signal dependencies decide when actions are ready. Independent actions may execute concurrently.

Organize repeated work

Automate.ax doesn’t compile your program into a user-authored JSON graph. Use functions and modules for repeated logic:

import { gmail } from "automate.ax/gmail"
import type { Signal } from "automate.ax"

function flagMessage(messageId: Signal<string>) {
  gmail.markMessagesAsImportant({ messageIds: messageId })
  gmail.starMessages({ messageIds: messageId })
}

Calling the helper registers both actions. Because neither action consumes the other’s result, they can execute independently once messageId materializes.

Declare durable work synchronously

The automation callback runs synchronously to describe durable work. Actions don’t return promises. They return signals for eventual outputs.

const message = gmail.getMessage({ messageId })
gmail.archiveMessages({ messageIds: message.messageId })

Don’t await an action. Passing message.messageId into gmail.archiveMessages records the dependency and allows Automate.ax to execute it after gmail.getMessage succeeds.

Keep composition deterministic

Automate.ax replays automation code while planning and resuming durable work. The same inputs must produce the same action and trigger call structure.

Keep action and trigger calls in stable positions.
Use signals for decisions based on event data or action results.
Don’t choose which durable calls exist using ambient time, randomness, or process-local mutable state.
Put side effects in actions, not directly in the automation callback.

Use signal-aware control flow such as filter or branch when execution should depend on runtime data. See Signals.

Deploy project files together

bunx automate.ax init creates automate.config.ts, which identifies the project. bunx automate.ax deploy finds every *.automation.ts file beneath that configuration directory and deploys them together. When you omit --project or --org, commands use the config in the current directory, the nearest parent config, or one config found within five descendant levels. If descendant discovery finds multiple configs, the command asks you to choose a project or organization instead of asking you to choose a directory. An explicit option always takes precedence. The relative source path is the automation’s stable identity within the project. Renaming or moving the file removes the old identity and creates a new one on the next deployment.

Start

Concepts

Guides

Use Bun APIs and packages

Connect triggers, signals, and actions

Organize repeated work

Declare durable work synchronously

Keep composition deterministic

Deploy project files together

​Use Bun APIs and packages

​Connect triggers, signals, and actions

​Organize repeated work

​Declare durable work synchronously

​Keep composition deterministic

​Deploy project files together

Use Bun APIs and packages

Connect triggers, signals, and actions

Organize repeated work

Declare durable work synchronously

Keep composition deterministic

Deploy project files together