> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations and automations

> Connect Linear, GitHub, Slack and over a hundred other integrations, then let scripts run on schedules and events while the machine sleeps between runs.

Tell the coding agent on any machine what you want:

```text theme={"theme":"github-dark"}
> every morning at 9, post my open Linear issues to myself in Slack
```

The agent checks what your organization 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.

<Frame caption="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.">
  <video autoPlay muted loop playsInline src="https://mintcdn.com/azin/WVNnZEt_-NWGDarQ/videos/one-prompt-automation.mp4?fit=max&auto=format&n=WVNnZEt_-NWGDarQ&q=85&s=39749c21d4c72f993592d398515e7e95" data-path="videos/one-prompt-automation.mp4" />
</Frame>

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. You can 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](/guides/suspend-resume), and the platform wakes it when a schedule is due or an event arrives. See [Why a schedule goes through `run`](#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 over 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. It is personal by default, or shared with the whole organization under a name. Your private machines get your personal connections plus the org's shared ones, and shared machines get the org's shared ones only.
* Inside a machine, the [`run` CLI](/cli/run) 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:

```typescript daily-digest.run.ts theme={"theme":"github-dark"}
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.` });
});
```

```bash theme={"theme":"github-dark"}
run daily-digest.run.ts
```

```text theme={"theme":"github-dark"}
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.

<Note>
  Automation scripts are written in TypeScript today. Python support is coming soon.
</Note>

## 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](https://app.boxd.sh/integrations) 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 the whole organization can act as one shared Linear or GitHub account.

Every integration is connected and used the same way. [Connections](/guides/integrations/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 the three GitHub entries: [Git](/guides/integrations/connections#git) authenticates `git` and `gh` on your private machines, the [GitHub App](/guides/integrations/connections#github-app) does the same on shared machines and is available to scripts, and [GitHub](/guides/integrations/connections#github) is the integration that automations call.

To go from connecting an integration to a running automation in a few minutes, see [Integrations quickstart](/guides/integrations/quickstart).

## Why a schedule goes through `run`

Machines on boxd hibernate when idle, and nothing runs on a sleeping machine, 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 follow the same rule: 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 background 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. See [Jobs](/guides/automations/jobs#the-console).

## Where this works, and as whom

* Connections and automations work on **your private machines** and on **shared machines**. **Isolated** machines have no `run` command and no integrations.
* On your private 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 [Connections](/guides/integrations/connections#where-connections-are-available).
* The `boxd` client inside a script is scoped like the machine. On a private machine it can manage your machines in that org, and on a shared machine the org's shared machines only.
* A **forked** machine, or one created from a snapshot, inherits the automations of its source machine and starts them immediately. Forking is how you scale an automation out.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.