Stacker

Search Documentation

Search for pages and topics in the documentation

6 min read

Automations

Automations run your own JavaScript or Python in a secure sandbox whenever something happens in your app — a record changes, a button is clicked, or an agent calls them. Each automation has full access to your app's data through the built-in stacker SDK.

Finding Automations

Open your app and look in the left sidebar for the Automations item (above your agents). There you can create automations, edit their code, run them manually, and review every execution's logs. The neighbouring Data item lets you browse the records your automations read and write.

You can also ask the AI builder (or a worker agent with the Modify workflows permission) to “create an automation that…” and it will write the code, wire up the trigger, and diagnose failures from the logs for you.

Triggers

Choose how each automation runs:

  • Record change — runs when records in a chosen table are created or updated. Use it to validate input, derive fields, or fan out notifications.
  • Button — runs when a user clicks a button in your portal. Call stacker.triggerWorkflow(slug, params) from a portal page.
  • Agent — a worker agent runs the automation as a tool (the agent needs the Run automations permission).
  • Callable — a function-style automation with no automatic trigger. Agents, app pages, skills, and other automations all call it with stacker.runWorkflow(slug, input) and it reads the passed inputs with stacker.getInput(). You can declare its inputs (name, type, required) in the automation's detail view — calls that omit a required input or pass the wrong type are then rejected. Great for shared logic you want to reuse.
  • Manual — runs only when you test it from the Automations UI. Pass a JSON Test input to simulate the inputs a caller would send. Great while you're building.

The Stacker SDK

Your code runs with a pre-injected stacker object scoped to this app only. The most-used helpers:

  • stacker.getTrigger() — the event that started this run (the changed record, button params, or agent input).
  • stacker.records — read, create, and update records in your app's tables.
  • stacker.log(...) — write a line to the execution log, visible in the Automations UI.
  • stacker.getInput() — the input object passed to this run (button params, agent params, or the input from another automation that called it). Same as stacker.getTrigger().input.
  • stacker.runWorkflow(slug, input) — call another automation in this app like a function, passing an input object. The call is queued and runs independently; loop protection applies (see below).
  • stacker.sendAgentMessage(agentId, message, { threadKey }) — send a message to one of your worker agents. Pass a stable threadKey to keep messages in the same conversation.
JavaScript example
// Runs on new orders, greets the customer via an agent
const { record } = await stacker.getTrigger();

stacker.log("New order received", { orderId: record.id });

await stacker.sendAgentMessage(
  "support-agent",
  `A new order ${record.id} was placed for ${record.total}.`,
  { threadKey: `order-${record.id}` },
);

Languages & packages

Automations can be written in JavaScript or Python. You can declare a list of npm or pip packages for an automation; Stacker installs them ahead of time so runs start quickly. If a package can't be pre-installed, the automation still falls back to installing it at run time.

Logs, errors & loop protection

Every run is recorded with its status, duration, return value, and the lines you wrote with stacker.log(). Open any execution in the Automations UI to diagnose failures.

Stacker automatically prevents runaway loops: whether an automation re-triggers itself through record writes or calls another automation directly with stacker.runWorkflow(), the platform tracks the cause-chain and stops it when it gets too deep or the same automation appears too many times in one chain. Automations also respect your workspace's usage limits — runs are metered, and an automation is blocked before it starts if the workspace is out of credit.

Automations run server-side in an isolated sandbox and can only touch the data in their own app. They never receive credentials or data from other apps or workspaces.

Workflows & ZapierAPI Access