Integrations & automations

Tell the coding agent on any machine what you want:

> every morning at 9, post my open Linear issues to myself in Slack

The agent checks what your team has connected, connects what is missing, writes the script and starts it, all on that same machine. There is nothing to deploy anywhere else. From then on boxd delivers the events, wakes the machine when the schedule is due, retries crashes, and documents the result in the console with a write-up and a flow diagram. One prompt to a living automation.

The real session, compressed: the prompt, the agent connecting Linear and Slack and testing the script, its done report, the automation's page in the console, and the digest in Slack.

Two more reasons this is the way to run automations:

It is all code. An automation is a TypeScript file, so it can do anything you can write: full types, any npm library, every CLI installed on the machine. Workflow builders ask you to learn their UI and fit your logic into their blocks. Here it is ordinary code, and you can just as well write it yourself instead of asking the agent.
It costs close to nothing between runs. Automations run inside boxd machines, so they follow the machine’s lifecycle. An idle machine hibernates, and the platform wakes it when a schedule is due or an event arrives. See why a schedule goes through run.

Four pieces, each building on the last:

An integration is a service in the catalog: Linear, Slack, GitHub, Notion, and a hundred more.
A connection is an account for an integration that you or your organization authorized. You connect it once, in the console or from a machine, and every machine you own can act as it. Personal by default, or shared with the whole organization under a name.
Inside a machine, the run CLI calls an integration’s tools from the shell, and @boxd/run calls them from a *.run.ts script, fully typed. The credential never enters the machine.
An automation is a script that registered a schedule or an event trigger. boxd keeps it running as a background job, delivers the events, wakes the machine when a schedule is due, retries crashes, and shows it in the console with a generated write-up and flow diagram.

A script that only calls tools runs once and exits, like any other command. A script with a schedule or a trigger is an automation. Here is the one the agent writes for that prompt:

// daily-digest.run.ts
import { linear, slack, every } from "@boxd/run";

every("0 9 * * *", async () => {   // 09:00 UTC, every day
  const { user: me } = await linear.getCurrentUser();
  const issues = await linear.listIssues({ assignee_id: me.id });
  const { user } = await slack.findUserByEmailAddress({ email: me.email });
  const dm = await slack.openDm({ users: user!.id });
  await slack.sendMessage({ channel: dm.channel!.id, markdown_text: `${issues.length} issues on your plate today.` });
});

$ run daily-digest.run.ts

a3f01: running in the background - `run logs a3f01` to follow

That is the whole deployment. The connections already exist on the platform, the machine already has run, and the file holds only the logic.

Automation scripts are written in TypeScript today. Python support is coming soon.

Connect an integration

Over a hundred integrations are available: Linear, Slack, Notion, GitHub, the Google suite, Stripe, Salesforce, OpenAI, Vercel, Jira, HubSpot, Zendesk and many more. The live list is on the console’s Integrations page and in run list inside any machine. A connection is personal by default. Any member can also connect an account for the organization under a name, so a whole team can act as one shared Linear or GitHub org. Every integration is connected and used the same way. Connections covers the whole model: personal and shared connections, connecting from the console or a machine, which machines can use which connection, and permissions. It also covers GitHub, which additionally authenticates git and gh on every machine and offers an organization-wide App. Ready to try it? The Quickstart goes from connecting an integration to a running automation in a few minutes.

Why a schedule goes through `run`

Machines on boxd auto-suspend when idle, and a suspended machine’s clock is frozen, so a crontab entry or a systemd timer silently misses its slot. Schedules registered with every(...) are known to the platform, which wakes the machine when one is due. Jobs also survive reboots, retry with backoff, tell you when they are waiting on a connection, and redeploy by re-running the file. The coding agents pre-installed on every machine are told the same thing: anything recurring or event-driven goes through run. A long-lived server, a web app or a database, still belongs in systemd.

What you see in the console

Integrations lists what is connected, for you and for the organization, and everything you can add. Automations lists every long-running job across your machines: a generated name and one-line summary, plain-English triggers (Every morning at 9am, Linear issue created), the integrations it uses, its state and last run. Open one for a write-up, a flow diagram and a rename box. An automation waiting on an integration says which one, and starts by itself the moment you connect it. Details in Jobs.

Where this works, and as whom

Connections and automations work on your personal and private machines and on shared org machines. Isolated machines have no run command and no integrations.
On your own machines, calls use your personal connections plus the org’s shared ones. On a shared machine they use the org’s shared connections only, never a member’s personal one, because everyone in the org can reach a shared machine. See where connections are available.
The boxd client inside a script is scoped like the machine. On a private machine it can manage your machines, on a shared org machine the org’s shared fleet only.
A forked machine, or one restored from a snapshot, inherits the automations of its source and starts them immediately. Forking is how you scale an automation out.

Getting started

Guides