Automations

Islo automations are repeatable workloads that run in managed sandboxes. Use them when work should survive disconnects, run on a schedule, react to an external event, or be started by another system.

For AI agents, start with islo-labs/skills. The skills repo is the maintained, agent-readable reference for Islo automations, sandbox lifecycle, gateway integrations, SDK usage, and templates. It is the best way to teach Cursor, Claude Code, Codex, and other agents how to use Islo correctly.

Automation building blocks

Building block	Use when
Durable jobs	You need a named, repeatable unit of work with parameters, versions, runs, status, and logs.
Scheduled jobs	The work should run on a recurring cron schedule.
Manual job runs	A human, script, or integration should start a known job on demand.
Webhook-triggered jobs	An external HTTP event should start a deployed job run, with optional params mapped from the payload.
Webhook sandbox actions	An external HTTP event should ensure, resume, pause, delete, or deliver traffic to a sandbox.

Durable jobs

A job defines what to run and which sandbox it needs. A deployment creates a versioned job definition, and a run executes that version with parameters.

The standard manifest path is:

jobs/<name>/job.toml

Discover the full schema

Do not hand-write job.toml from memory. Use:

$ islo schema job              # Full job.toml schema (JSON) + job CLI surface
$ islo job init <name>         # Scaffold with the platform default image
$ islo job deploy <name> --dry-run

islo schema job returns the machine-readable manifest schema under job_toml. The control-plane OpenAPI JobManifest type is the API source of truth for deploy/validate bodies.

Manifest sections

Section	Required	Purpose
`[job]`	yes	Name, version, description
`[job.params.*]`	no	Typed run parameters (`{name}` substitution)
`[run]`	yes	Fanout, concurrency, region, teardown / resume policy
`[run.sandbox]`	no	Default sandbox (image, resources, snapshot, gateway)
`[run.sandbox.lifecycle]`	no	Auto-pause / auto-delete policy
`[[run.tasks]]`	yes (≥1)	Fan-out unit; optional per-task sandbox override
`[[run.tasks.steps]]`	yes	Ordered compute ops (`exec`, `snapshot`, `pause`, …)
`[schedule]`	no	Cron schedule created/updated on deploy
`[verification]`	no	Optional evaluation layer

`[run]` fields

Field	Default	Meaning
`fail_fast`	`true`	Stop remaining tasks on first step failure
`fanout`	`false`	One shared sandbox vs one sandbox per task
`concurrency`	`1`	Max parallel tasks when `fanout = true`
`workdir`	`"."`	Default workdir for steps
`timeout`	none	Max wall-clock run duration
`region`	none	Compute region; falls back to `ISLO_REGION`
`teardown_on_complete`	`true` for `provision`; `false` for `ensure`/`reuse`	Delete sandbox after run
`resume_on_start`	`true` for `ensure`; `false` otherwise	Resume paused sandbox before steps

`[run.sandbox]` fields

Field	Default	Meaning
`mode`	`provision`	`provision` (fresh), `ensure` (create-if-missing), or `reuse` (attach existing)
`name`	none	Required for `ensure` / `reuse`. Supports `{param}` substitution.
`image`	none	Required for `provision` / `ensure`. Use `ghcr.io/islo-labs/islo-runner:latest` (do not use `islo/default`).
`vcpus`	`2`	Virtual CPUs
`memory_mb`	`2048`	Memory in MB
`disk_gb`	`10`	Disk in GB
`snapshot_name`	none	Restore from a named snapshot on create
`gateway_profile`	none	Gateway profile for credential injection
`init`	none	Tagged object: `{ type = "full" }`, `{ type = "minimal" }`, or `{ type = "custom", capabilities = [...] }`
`internet_enabled`	`true`	Allow outbound internet
`workdir`	none	Sandbox working directory
`cache_key`	none	Optional cache key
`env`	none	Environment variables table

1 [run.sandbox]
2 mode = "provision"
3 image = "ghcr.io/islo-labs/islo-runner:latest"
4 vcpus = 4
5 memory_mb = 8192
6 disk_gb = 40
7 snapshot_name = "baseline-v1"
8 gateway_profile = "default"
9 init = { type = "full" }
10 
11 [run.sandbox.lifecycle]
12 pause_after_idle = 3600

Step actions

Each step must define exactly one action:

Step field	Behavior
`exec = ["cmd", "arg"]`	Run a command in the sandbox
`snapshot = { name = "…" }`	Create a snapshot
`pause = true`	Pause the sandbox
`resume = true`	Resume the sandbox
`delete = true`	Delete the sandbox

upload / download are not available yet.

Use a gateway profile when an automation needs provider access. This keeps GitHub, Slack, model provider, and other secrets out of the sandbox environment by default.

Scheduled jobs

Use [schedule] in job.toml for recurring runs:

1 [schedule]
2 cron = "0 * * * *"
3 timezone = "UTC"
4 enabled = true

Deploying the job creates or updates its schedule:

$ islo job deploy <name>

Every param a scheduled run needs must have a default. Keep scheduled job tasks idempotent — retries and repeated runs are part of the automation model.

Webhooks

Webhooks connect external HTTP events to Islo automations. They are not only for sandbox lifecycle work — a common pattern is to trigger a deployed job when GitHub, Linear, Stripe, Slack, or your own service sends an event.

Webhook-triggered jobs

Add a trigger_job action to a webhook rule to start a job run:

$ islo webhook create linear-to-slack \
>   --target-sandbox-name linear-to-slack-events \
>   --action trigger-job \
>   --job-name linear-to-slack \
>   --job-param ticket_id=json_path:$.data.identifier

Webhooks still require a target (fixed name or event-derived) for ingress routing, even when the only action is trigger_job. The job provisions its own sandbox at run time.

The action runs against the latest deployed version unless you pin version_id or override region. Map job params from the webhook request with params entries (json_path, header, query, header_param, raw_body, method, or path).

Typical flow:

Deploy the job with islo job deploy <name>.
Create a webhook whose rule includes trigger_job for that job name.
Paste the webhook receiver_url into the external provider.

Use this for event-driven automations such as Linear issue updates, GitHub PR events, or custom app callbacks that should run your job.toml workload instead of managing a long-lived sandbox directly.

Webhook sandbox actions

Webhooks can also drive sandbox lifecycle without starting a job:

ensure a sandbox exists
resume a paused sandbox
pause or delete a sandbox
deliver the request to a port inside a sandbox

For auth, targets, rules, idempotency, and full action reference, see Incoming Webhooks.

Agent guidance

When you want an agent to build or maintain Islo automations, point it at islo-labs/skills. The repository includes an Islo skill and plugin metadata that explain the current automation model, recommended CLI discovery commands, gateway credential patterns, and runnable-template pointers.

Recipes and examples are useful for humans looking at a specific pattern, but the skills repo should be the first link for agent setup and agent-authored automation work. Always have agents run islo schema job before editing [run.sandbox], and islo schema webhook before editing ensure-sandbox templates.