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.
Incoming webhooks	An external HTTP event should create, 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

Common sections include:

[job] for name, version, and description
[job.params.*] for parameter schema and validation
[run] for timeouts, working directory, teardown behavior, and failure policy
[run.sandbox] for image, CPU, memory, snapshot, init mode, and gateway profile
[[run.tasks]] and [[run.tasks.steps]] for ordered commands inside the sandbox
[schedule] for recurring runs

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>

Keep scheduled job tasks idempotent. Retries and repeated runs are part of the automation model.

Incoming webhooks

Incoming webhooks let external systems such as GitHub, Stripe, Slack, or your own service trigger sandbox actions. A webhook can:

ensure a sandbox exists
resume a paused sandbox
pause or delete a sandbox
deliver the request to a port inside a sandbox
trigger job-oriented automation when supported by the API or CLI

For webhook configuration details, 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.