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.
- 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, and the platform wakes it when a schedule is due or an event arrives. See Why a schedule goes through
run.
- 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
runCLI calls an integration’s tools from the shell, and@boxd/runcalls them from a*.run.tsscript, 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.
daily-digest.run.ts
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 inrun 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 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 authenticates git and gh on your private machines, the GitHub App does the same on shared machines and is available to scripts, and GitHub is the integration that automations call.
To go from connecting an integration to a running automation in a few minutes, see 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.Where this works, and as whom
- Connections and automations work on your private machines and on shared machines. Isolated machines have no
runcommand 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.
- The
boxdclient 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.