Ephemeral documentation

Ephemeral runs AI agents in secure, disposable machines. Describe a task once, then run it from your code, the CLI, the dashboard or on a schedule. Each run gets a fresh microVM, the files and connections you allow, and a spending limit. It streams every step while it works, then the machine is destroyed. The output, the events and the cost stay.

A complete run

curl $EPHEMERAL_URL/v1/runs \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Summarize the input in one sentence","input":{"text":"…"},"max_cost_micros":500000}'

Who it is for

Ephemeral is for developers who add background AI tasks to their applications: investigating a support ticket or a failed payment, watching a system and explaining what changed, writing a scheduled report, or carrying out an operational chore. Your code starts a run with an API call, and the result comes back to your code.

What Ephemeral handles for you

Around a model API you would otherwise build:

A fresh, isolated machine for every task, destroyed when it ends.
A credentials broker: the agent calls your APIs without seeing a secret, and only with the methods or tools you allow.
Hard per-run budgets, reserved before the run and settled to the exact cost afterwards.
A recorded timeline and the exact cost of every run.
Schedules and signed callbacks, so work starts on time and your server hears when it ends.
A fixed retention period, and zero data retention for sensitive runs. See security and data.

How it fits together

A run is one agent working on one task. You describe it with a prompt and JSON input, and choose which files it can read and which connections it can call. A workflow is a run definition saved under a name, so your code only sends the name and new input. A schedule starts a workflow on a timetable, in any time zone.

The worker runs in its own microVM. It never receives your provider keys or connection credentials: model calls and connection requests go through Ephemeral with a short-lived run token, and only to the methods or tools you allowed.

Hosted or self-hosted

On the hosted service, runs are paid for with prepaid credits and your organization is managed at ephemer.al. Self-hosted installations run the same engine and dashboard in your own AWS account with your own model provider.

Where to go next

QuickstartAdd credits, create a key and start your first run in a few minutes.RunsStatuses, events, timeouts, cancellation and what is kept afterwards.ConnectionsLet workers call your APIs and MCP servers without seeing credentials.API referenceEvery endpoint, with request and response fields.SamplesRunnable examples with a recording of a real run, the exact request and the permissions each one had.

Versioning and deprecation

The API is versioned in its path: every endpoint is under /v1. Within a version, changes are additive only: new endpoints, new optional request fields, new response fields and new event types. Existing fields keep their names and meaning, so clients should ignore fields they do not know.

A change that would break existing clients ships as a new version under a new path. The previous version keeps working for at least six months after the new one is published. While it is deprecated, its responses carry a Deprecation header and a Sunset header with the date it stops working, and organization owners are told by email.