Ship and share

Offloaded work

Send heavy commands such as tests and typechecks to a runner on one of your machines

On this page(5 sections)

Whether a runner can take a heavy command
Run a heavy command on a runner
Recent offloaded commands
Stop an offloaded command
Kinds of heavy work that can run elsewhere

Heavy commands are sorted into kinds (tests, typechecks, verify…), and the owner can send each kind to a runner on one of their machines instead of running it here. The sandbox's own `offload-run` command drives the run: it asks whether the runner can take the work, hands it a snapshot of the code and streams the output back, ending with the exit code and every file the command changed. The rest lists the kinds and the recent runs.

GET/offload/runners/{runner}Whether a runner can take a heavy command

Answers whether the runner a kind of heavy work is sent to is connected and able to run it, before anything is copied to it. When it is not, the command runs in this sandbox and says why.

What you send

Field	Type	Where
`runner`required	string	address

What comes back

Field	Type
`runner`	string
`name`	string
`ready`	boolean
`why`	string

Try itanswered in this tab

curl

curl "$SANDBOX/offload/runners/%E2%80%A6" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.offload.target({
  "runner": "…"
});

POST/offload/runsRun a heavy command on a runnerstream

Hands one command to a runner on one of your machines, together with a snapshot of the code as it stands, and streams its output back as it comes. It ends with the exit code, every file the command changed and any report it wrote.

What you send

Field	Type	Where
`runId`required	string	body
`repo`required	string	body
`ref`required	string	body
`cwd`required	string	body
`command`required	string	body
`env`	object	body
`exports`	string[]	body
`label`required	string	body
`timeoutMs`	integer	body
`runner`required	string	body

What comes back

Field	Type
`when event is "message"`	shape
`data`	object
`when kind is "status"`	shape
`text`	string
`when kind is "output"`	shape
`stream`	"stdout" \| "stderr"
`text`	string
`when kind is "exit"`	shape
`code`	integer
`signal`	string
`failure`	string
`ran`	boolean
`patchBase64`	string
`files`	object
`when kind is "refused"`	shape
`why`	string
`id`	string
`retry`	number
`when event is "done"`	shape
`data`	unknown
`id`	string
`retry`	number
`when event is "error"`	shape
`data`	unknown
`id`	string
`retry`	number

Try itanswered in this tab

curl

curl -N -X POST "$SANDBOX/offload/runs" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"runId":"run_8c2f41d9","repo":"root","ref":"refs/heads/main","cwd":"/work","command":"pnpm dev","env":{"src/app.ts":"…","README.md":"…"},"exports":["…","…"],"label":"Nightly changelog","timeoutMs":1,"runner":"…"}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.offload.run({
  "runId": "run_8c2f41d9",
  "repo": "root",
  "ref": "refs/heads/main",
  "cwd": "/work",
  "command": "pnpm dev",
  "env": {
    "src/app.ts": "…",
    "README.md": "…"
  },
  "exports": [
    "…",
    "…"
  ],
  "label": "Nightly changelog",
  "timeoutMs": 1,
  "runner": "…"
});

GET/offload/runsRecent offloaded commands

The heavy commands this sandbox sent to runners lately, newest first, with where they ran and how they ended.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`runs`	object[]
`runId`	string
`runner`	string
`name`	string
`label`	string
`command`	string
`startedAt`	number
`endedAt`	number
`code`	integer
`failure`	string

Try itanswered in this tab

curl

curl "$SANDBOX/offload/runs" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.offload.runs();

POST/offload/runs/{runId}/cancelStop an offloaded command

Stops a command running on a runner, with everything it started there.

What you send

Field	Type	Where
`runId`required	string	address

What comes back

Field	Type
`ok`Always true	true

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/offload/runs/run_8c2f41d9/cancel" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.offload.cancel({
  "runId": "run_8c2f41d9"
});

GET/offload/kindsKinds of heavy work that can run elsewhere

The kinds this sandbox sorts heavy commands into (tests, typechecks, verify…), each of which can be sent to a runner on one of your machines instead of running here.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`kinds`	object[]
`id`	string
`pattern`	string

Try itanswered in this tab

curl

curl "$SANDBOX/offload/kinds" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.offload.kinds();