---
title: "Offloaded work · intentic sandbox API"
description: "Send heavy commands such as tests and typechecks to a runner on one of your machines. Every route in the offloaded work group of the intentic sandbox API."
url: "https://intentic.dev/api/offload/"
---

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](#offload-target)
- [Run a heavy command on a runner](#offload-run)
- [Recent offloaded commands](#offload-runs)
- [Stop an offloaded command](#offload-cancel)
- [Kinds of heavy work that can run elsewhere](#offload-kinds)

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 it answered in this tab

curl

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

TypeScript

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

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

**POST`/offload/runs` Run a heavy command on a runner stream**

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 it answered in this tab

curl

```bash
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

```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/runs` Recent 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 it answered in this tab

curl

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

TypeScript

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

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

**POST`/offload/runs/{runId}/cancel` Stop 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 it answered in this tab

curl

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

TypeScript

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

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

**GET`/offload/kinds` Kinds 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 it answered in this tab

curl

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

TypeScript

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

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

More in Ship and share

[Previous ← Pipelines](https://intentic.dev/api/ci/)[Next Outbox →](https://intentic.dev/api/public/)