Runs

A run is one agent working on one task in its own microVM. You send a prompt, JSON input, and the files and connections it may use. Ephemeral queues it, starts a fresh machine, records every step, and destroys the machine when the run ends.

What a run is made of

Every run has a prompt and optional input. The rest of the definition decides which model it uses, what it can read, what it can call, how long it may take and how much it may spend. You can send the whole definition inline, or name a saved workflow and send only the input.

{
  "prompt": "Find out why this payment failed. Follow the playbook.",
  "input": { "payment_id": "pay_123" },
  "model": "anthropic/claude-haiku-5.5",
  "files": [{ "file": "playbook.md" }],
  "connections": { "payments": { "ref": "payments-api", "allowed_methods": ["GET"] } },
  "timeout_seconds": 120,
  "shell": false,
  "max_cost_micros": 500000
}

Inside the microVM the agent can always read the files you mounted. With shell on, which is the default, it can also run shell commands and write files in its working directory. Each connection you grant adds tools it can call, and with web access on it can read pages, search and call public APIs. The machine itself has no internet. The working directory is discarded with the machine, so nothing carries over to the next run.

Lifecycle

A run moves through these statuses. The last five are final; once a run reaches one of them it does not change again.

Runs leave the queue in the order they were created. A self-hosted installation runs two at a time by default; the rest wait in queued. The timeout counts from the moment a run leaves the queue, so time spent waiting does not use it up.

Limits

Following a run

There are three ways to learn what a run is doing and when it ends.

• Poll GET /v1/runs/{id} until the status is final.
• Stream GET /v1/runs/{id}/events. This is a server-sent event stream that replays everything recorded so far, then continues live until the run ends.
• Set a callback on the run. Ephemeral sends a signed request to your server when the run reaches a final status.

Closing the event stream does not affect the run. You can reconnect with the last event ID you received and continue from there.

Event types

Ephemeral removes known credential values, such as connection tokens, from events and output before storing them. The API reference shows the exact stream format.

Cancelling a run

POST /v1/runs/{id}/cancel stops a run that is reserving, queued, starting or running. The worker is stopped and the microVM is terminated. Cancelling a run that has already finished changes nothing.

Zero data retention

Set zero_data_retention to true on a run, or in a saved workflow, when the task is sensitive. Ephemeral then records nothing of the run's content: you only get the output.

• Events still stream while the run works, through GET /v1/runs/{id}/events on any engine. They are held in a transient store and deleted a few minutes after the run ends.
• The output is returned once. The first GET /v1/runs/{id} after the run ends includes it and deletes it. With a callback, the callback delivers it and reads leave it in place until then. Either way it is deleted after at most an hour. output_available and output_expires_at say whether it is still held.
• Model calls go only to providers that neither retain your data nor train on it. A model with no such provider is refused with 400 before anything is reserved.
• On the hosted service the run costs 10% more: the surcharge applies to compute, model calls and web requests, counts toward the budget and appears in the cost breakdown. Self-hosted installations charge nothing extra.
• Transient data lives in tables that every backup leaves out, so a restored database never contains it.

After a run

The run keeps its output, error message, timestamps, events and cost. Treat the cost as final once the status is final and billing_pending is false; see budgets and billing.

Finished runs are deleted 30 days after they end, together with their events. A run is kept longer while its billing, callback delivery or microVM cleanup is still pending. Self-hosted installations can change the retention period.

To run the same task again, fetch GET /v1/runs/{id}/definition. It returns the definition the run actually used, with credentials removed, so you can review it, set a new budget and submit it.