Work together
Automations
Run your own TypeScript when something happens in a workspace, such as moving a ticket when its pull request merges.
An automation is code that runs when an event happens: a ticket is created, a pull request opens, a deploy fails. There’s no rule builder. You write a handler in TypeScript against the Nexul SDK, push it, and Nexul runs it.
Each automation belongs to one workspace. It hears that workspace’s events, plus instance-wide ones such as runners and DNS, and you switch and configure it on that workspace’s Automations page. It never hears a direct message or a private channel.
Which ones need you
An automation is failing when it is on and its last run failed or crashed; its row shows that run’s error in place of its description. It needs attention when it is on and something waits on a person: a required setting is empty, its host is offline, its token was revoked, or a pushed version waits to be merged. The row names the most urgent of these. All, Failing, Needs attention and Off above the list count each kind and narrow the list to it, and the list keeps the most urgent first: failing, then needs attention, then on, then off. Each row also shows when the automation last ran and how many of its runs in the last seven days failed; hover its mark for the last run’s error in full.
An automation’s own page names the same problems under its title, each one a link to where it is fixed: a failed run to Runs, empty settings and a revoked token to Settings, a waiting version to Versions, an offline host to the Hosts tab. Runs lists the newest 50 runs by day, and Failures there lists the newest 50 failed or crashed ones; runs are kept 30 days. Settings holds its configuration, the host it runs on, its token and Delete automation; a shipped default can’t be deleted, because it comes back at the next start, so switch it off instead.
The defaults
Every workspace comes with its own copy of three. The first two are switched on:
- Ticket finished moves a ticket to its project’s Done status once all its pull requests have merged.
- PR opened moves each linked ticket to its project’s In review status when a pull request opens.
They need no setup. Each one picks the first status of that kind in the ticket’s own project, so projects with different boards all work. A project with no status of that kind is left alone, and the run’s log says so on its Runs tab.
The third, Crash intake, starts switched off. It turns crash reports a bot posts into bug tickets, described below.
Crash intake
Your app reports a crash by posting it through a bot’s URL in the crash-report/1 format: the line Crash fingerprint: <hash> as the message, and one embed whose fields are Contract (crash-report/1), Fingerprint, Kind, Process type, App version, Build commit, OS, Arch, First seen, Signature, Stack, Truncated, and optionally Suppressed duplicates. Any other post is ignored.
Open its Settings tab and pick the channel the bot posts in and the project its tickets go to, then switch it on. The bug type (bug) and the high-priority label (high-priority) can be changed there too. For each report, it looks for a ticket in that project whose body has the report’s fingerprint line:
- None: it files a bug in the first column, with the fingerprint line, the kind, the first version, the OS, the signature and the stack. Its origin is marked unknown.
- An open ticket: it keeps one Seen again note on it, updated in place with the number of reports, the versions and when it was last seen. It never files a second ticket.
- A done ticket with no merged pull request, such as one closed as won’t fix: the same Seen again note, and nothing else.
- A done ticket with merged pull requests: it asks GitHub whether the report’s build commit contains every one of them. If it does, the crash came back, so it files a new bug found in the done ticket, labels it
high-priority, and puts it at the top of the column. If the build lacks a fix, it updates an Old build note instead. If GitHub can’t tell (the repository isn’t connected, it doesn’t know the commit, or it didn’t answer), it updates a Can’t tell note that says why, and files nothing.
The notes are posted on behalf of the workspace’s Owner. Each report’s Runs entry logs what it did.
The Decisions check isn’t here: it’s a play with an auto play, switched on from the play.
Write your own
-
On the Automations page, press New automation. Name it and pick its Scopes: what its token may read and change, from the same permissions integrations use. The dialog then shows the commands for the next steps, with your instance URL and the automation’s id filled in.
-
In an empty folder, run
bun add @otal-labs/nexul-sdk; its commands need Bun. Then runbunx nexul init --url <your instance URL> --id <automation-id>. It asks for a personal access token from Settings → Security, keeps both innexul.config.json(added to.gitignore, since it holds the token), and writessrc/index.ts, named after the automation, and atsconfig.jsonso your editor knows the SDK’s types. The name and description in your code are the ones Nexul shows once it runs. -
Write your handlers:
import { defineAutomation } from "@otal-labs/nexul-sdk/automation"; const automation = defineAutomation({ name: "my-automation", description: "Describe what this automation does.", config: {}, }); automation.on("ticket.created", async (payload, ctx) => { ctx.log("ticket created", { id: payload.ticket.id }); return true; }); export default automation;Return
truefor success. A thrown error, a timeout (30 seconds by default), or any other value counts as a failed run.payloadis typed from the event catalog, and a list in it is always an array,[]when empty.ctxgives youctx.api, a typed client acting with the automation’s token, plusctx.config,ctx.secrets,ctx.log, andctx.runPlay(Start a play). -
Run
bunx nexul dev, pick a topic, and it fires a sample event at your handler. You see the outcome, the logs, and every API call it would have made. Nothing reaches your instance. -
Run
bunx nexul push <automation-id> "message"to upload the code as a pending version. -
On the automation’s Versions tab, read the new code against the active one and press Merge. The automation restarts on the new code.
-
A new automation starts switched off. Switch it on at the top of its page, and its next event runs your code; each run shows on the Runs tab with its logs.
Nexul keeps your src/index.ts beside the bundle it runs, so the Versions diff compares what you wrote, and bunx nexul pull <automation-id> writes the active version’s src/index.ts back; bunx nexul pull <automation-id> <version-id> writes that version instead. While a version is pending and kept its source, the Versions tab names it, so your next push builds on it rather than replacing it with an edit of the active code. Other files you import go into the bundle only, and a version pushed before an SDK that keeps sources (0.1.2) has nothing to pull; its diff shows the bundled code. Run these commands with bunx from the project folder: a bare nexul is the command that installs and runs your instance, not the SDK’s.
For unit tests, createMockContext from @otal-labs/nexul-sdk/testing gives you the same recording context nexul dev uses. It records ctx.runPlay as the POST /api/plays/queue call it makes and answers with a queued run, unless your test scripts another answer under that key.
Two events mark a moment rather than one change. ticket.unblocked fires when a ticket’s last open blocker gets its pull request merged, reaches a done column, has its blocked-by link removed, or is deleted, with cause saying which (blocker_finished, blocker_done, link_deleted, blocker_deleted). doc.settled fires once a person’s edits to a doc have stopped for ten minutes, with first true for a doc created inside that window; edits an agent makes through MCP, or an automation makes, never start the wait.
History
History at the top of an automation’s page lists every version pushed to it, newest first, for anyone who can read the automation. Each version is shown as a diff against the one before it: removed lines in red with a -, added lines in green with a +, both versions’ line numbers beside them, and the changed words of an edited line highlighted. Unchanged code folds down to three lines around each change; press a fold to show the lines it hides. The push message is the version’s name. The active version reads Current and a waiting push reads Pending. Select the pending version and press Merge to make it the active code, or select an older one and press Roll back to #N (it asks first); the automation restarts on that code. Versions are never deleted, so a rollback only moves the active mark. The Versions tab shows the pending version’s diff against the active code, the active code in full, and for your own automations the commands that change it.
When a service goes down
service.container_stopped fires when a service of a stack goes down: its container died with a non-zero exit code or was killed for running out of memory. service.container_recovered fires once that container has stayed running for a minute. A container that keeps restarting is one outage, so the stopped event fires once, at the first crash. Both carry the stack, service, container, machine, an outage_id that pairs the two, the exit code, oom and restart_count; they carry no output lines, so to see why it crashed, read that service’s logs while Docker still holds the container. Events for a stack with a deploy running, and for containers that exit with code 0, are never sent.
When the error rate trips
stack.error_rate_crossed fires when a stack’s error-rate rule trips: the share of 5xx answers went above its limit with enough requests. stack.error_rate_recovered fires once every minute of a window has stayed under the limit. Both carry the stack, an episode_id that pairs the two, the worst share the episode reached (peak_percent) with its requests and errors, and the rule’s limit_percent, window_minutes and min_requests as they were when it tripped. They carry no request lines, since Nexul keeps none. Switching the rule off ends an episode without sending the recovery.
Start a play
ctx.runPlay queues one of the workspace’s ticket plays on a ticket, named by the play’s label:
automation.on("ticket.test_failed", async (payload, ctx) => {
const run = await ctx.runPlay("Fix with AI", payload.ticket.id, { priority: "high" });
ctx.log("fix queued", { state: run.state, reason: run.reason });
return true;
});- The run waits in a person’s queue exactly like an auto play’s: on the ticket’s developer, or its tester with
runOn: "tester", atpriority"high","normal"(the default) or"low". It counts toward the ticket’s daily cap of automatic runs, and the play’s show-when stage doesn’t apply. - It answers with
{ id, state, reason }.stateis"queued", withreason"paused"when the ticket has reached its daily cap, or"didnt_run"with why, such as the ticket having no developer. Either way the ticket shows it. - The automation’s token needs the
plays:runscope, and whoever created the automation must be able to run that play on that ticket. The default automations have no creator, so they can’t start plays.
Play names are checked as you type. Run bunx nexul types <automation-id> and it writes src/plays.generated.d.ts with the workspace’s play names, so a typo, a doc play, or a play renamed since then is a type error in your editor. nexul push refreshes the file every time. A project made by nexul init already points src/index.ts at it; in an older project, add /// <reference path="./plays.generated.d.ts" /> as the first line of src/index.ts. Labels are unique in a workspace, so a name is always one play.
Code you already pushed keeps the name it was written with. Renaming a play warns first: the play dialog lists the automations whose active or pending code still has the old label in quotes and asks before it saves, and play_update over MCP renames it and names them in its warnings. If someone renames or deletes that play anyway, ctx.runPlay throws, nothing is queued, and the run fails with the server’s reason on the Runs tab, such as no play named "Fix with AI" in this workspace. Rename the play back, or update the name, push, and merge.
Versions
Every push is kept as a version with its author, time, and message, and lands pending: a push never changes running code by itself. Roll back to #N on an older version makes it active again.
Secrets
Set secrets on the Secrets tab of the Automations page. Every automation in the workspace reads them as ctx.secrets.NAME; no other workspace sees them. Once saved, a value can be replaced (Replace on its row) or deleted but never read back. A value can be a 1Password reference instead of a secret: see External secrets.
Where automations run
Automations run on an automations host. nexul install puts one on your instance’s server, named instance, and new automations go there.
To run automations on another machine, for example to reach services on its network:
- On the Hosts tab, press Add automations host.
- Give it a Host name (lower-case letters, digits, and dashes) and the Machine it runs on. Add automations host appears when you hold Manage on a machine, and the Machine field offers only the machines you manage. The instance Owner can also type a machine Nexul doesn’t know yet, or leave it empty, since a host doesn’t add machines.
- Run the install line shown, for Linux or macOS, or for Windows, on that machine. It needs no Docker. The line carries a one-time code that expires after an hour.
A host belongs to its machine, like a runner. You see it when you can see its machine, and its Remove button appears where you hold Manage on the machine; a host on a machine you can’t see is not found. Placing an automation on a host takes Deploy to on the host’s machine as well as automations:write in the automation’s workspace, and the instance host is open to every automation. Taking someone off a machine leaves the automations already placed there running; their next move is checked. Agents add and remove hosts with host_create and host_delete and kind: "automations", and place an automation with automation_update and host_id.
Move an automation by picking another host in Runs on on its page. The list holds the instance host and the hosts on machines you hold Deploy to on. It stops on the old host as it starts on the new one, so two hosts never run the same automation. To retire a host, move its automations off, then Remove it; it uninstalls itself. Removing a host moves its automations to the instance host and stops its credential. Adding a host again makes a new one: its automations stay on the instance host until you move them back.
Switching off
Switch an automation off and it receives nothing until you switch it on again. Events in between are skipped, not replayed. A host that loses its connection is different: it picks up where it left off when it reconnects.
Its token stops working too: every API call with it is refused with automation is switched off, and its host stops running it. Switch it back on and the same token works again; there’s nothing to mint.