# Ephemeral

> Ephemeral runs AI agents in disposable, sealed machines. Each run starts a fresh microVM with only the tools, files, connections and budget you allow, streams every step, records the result and exact cost, and is destroyed when the work is done. Use it through an HTTP API, a command-line tool or the dashboard.

## When to use Ephemeral

Reach for Ephemeral when a product or an operation needs an AI agent to do a bounded job in the background, safely, with a known maximum cost. Best-fit jobs:

- Support investigations: look up a failed payment, an order or an account through a read-only connection and answer in a few lines for a human.
- Monitoring and alerts: check a status page, a metric or a website on a schedule and report only what changed.
- Scheduled reports: gather data on a cron schedule in a chosen time zone and deliver a summary by callback.
- Data processing in a sandbox: transform, analyse or reconcile uploaded files with a shell that is discarded afterwards.
- Running untrusted or generated code: execute it in an isolated machine with no credentials and no network beyond what you allow.
- Any task that must touch sensitive data without leaving a trace: zero data retention returns the output once and stores nothing of the run's content.

Every run is bounded by a hard budget (`max_cost_micros`), a timeout of at most one hour, and an explicit allowlist of connections (with allowed HTTP methods, so read-only is enforceable), websites and files. Connection credentials are added by a broker outside the machine and never enter it. Runs can be started on demand, on a schedule, or from a saved workflow, and finish with a signed callback if you ask for one.

Not a fit: long-lived servers, interactive chat sessions, or workloads that must keep state between runs. Each run starts clean by design.

## How an agent calls Ephemeral

- API base URL: https://app.ephemer.al
- Authentication: `Authorization: Bearer <API key>`. A person creates a key in the dashboard under API keys; keys are shown once.
- OAuth 2.1 sign-in for applications that act for a person (MCP clients, integrations): authorization code flow with PKCE (S256), dynamic client registration, scopes `member` and `admin`; the access token is sent as the same bearer. Authorization server metadata (RFC 8414): https://ephemer.al/.well-known/oauth-authorization-server. Protected resource metadata (RFC 9728): https://app.ephemer.al/.well-known/oauth-protected-resource. Hosted service only.
- Start a run: `POST /v1/runs` with JSON `{ "prompt": "...", "input": {...}, "max_cost_micros": 500000 }`. It returns `202 Accepted` with the run `id`. Send an `Idempotency-Key` header so retries are safe.
- Get the result, any of three ways: poll `GET /v1/runs/{id}` until the status is `succeeded`, `failed`, `cancelled`, `timed_out` or `interrupted` and `billing_pending` is `false`; stream `GET /v1/runs/{id}/events` (server-sent events); or pass a `callback` `{ "url", "secret" }` and receive a signed request when the run ends.
- Other capabilities of a run request: `files` (mounted read-only), `connections` (HTTP or MCP APIs with allowed methods), `web` (allowed domains, optional search), `shell`, `model`, `timeout_seconds`, `zero_data_retention`.
- Saved workflows: `PUT /v1/workflows/{name}`; schedules: `POST /v1/schedules` (cron and time zone). A workflow, and an inline run, can carry a `description`, an `input_schema` (a JSON Schema the run's `input` must match, or the request fails with 400 naming the path and reason) and an `output_schema` (a JSON Schema the run's output must match; the output is then JSON, and a run whose output does not match fails). `GET /v1/workflows?detail=true` and the `list_workflows` MCP tool return them, so a workflow can be called without reading its prompt.
- CLI: install with `curl -fsSL https://ephemer.al/install.sh | sh`, then `ephemeral login` and `ephemeral run --prompt "..." --wait`.
- Machine-readable API description: https://ephemer.al/openapi.json
- MCP server (Streamable HTTP): https://app.ephemer.al/mcp, with the same bearer API key, or sign in with OAuth: a client that supports it needs only this URL. Tools: create_run, get_run, wait_for_run, list_runs, cancel_run, list_workflows, get_workflow, save_workflow, delete_workflow, list_schedules, get_schedule, create_schedule, update_schedule, delete_schedule, preview_schedule, run_schedule, list_files, list_models (compact; filter with query, limit, zero_data_retention, or pass model for one model), list_connections. A run's cost is final only when cost_final is true (billing_pending false); until then cost_micros is provisional and usually higher. Changing schedules needs an admin key. Server card: https://ephemer.al/.well-known/mcp/server-card.json
- API catalog (RFC 9727): https://ephemer.al/.well-known/api-catalog
- [Ephemeral API versioning and deprecation policy](https://ephemer.al/docs#versioning-and-deprecation): the API is versioned in its path; a breaking change ships as a new version and the old one keeps working for at least six months, announced with Deprecation and Sunset headers.
- Rate limits: 600 requests per minute per API key, 120 per minute per client address without a key. Every response carries `RateLimit-Policy`, `RateLimit`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`; past the limit the API answers `429` (`code` `rate_limited`) with `Retry-After` in seconds, so wait that long before retrying.
- Pages are also available as Markdown: request any page on this site with `Accept: text/markdown`.

## Start here

- [Quickstart](https://ephemer.al/docs/quickstart): from a new account to a finished run and an API call, about five minutes
- [Documentation index](https://ephemer.al/docs)
- [API overview](https://ephemer.al/docs/api): authentication, errors, idempotency, limits
- [Pricing](https://ephemer.al/pricing): prepaid credits, no subscription; a run is charged for worker seconds, model calls and web requests and never more than its budget
- [About Ephemeral](https://ephemer.al/about)

## Docs: Get started

- [Security and data](https://ephemer.al/docs/security): How runs are isolated, what is stored and for how long, and how to report a problem.

## Docs: Recipes

- [Investigate a failed payment](https://ephemer.al/docs/recipes/investigate-payment): A read-only support tool: a payment ID in, the cause of the failure out.
- [Watch a page and get alerted](https://ephemer.al/docs/recipes/monitor-a-page): Check a page every 15 minutes and alert Slack only when its state changes.
- [Send a weekly report](https://ephemer.al/docs/recipes/weekly-report): A Monday-morning report from your analytics API, on a schedule.

## Docs: Concepts

- [Runs](https://ephemer.al/docs/concepts/runs): One agent in one disposable microVM, from queue to settlement.
- [Workflows](https://ephemer.al/docs/concepts/workflows): Saved run definitions you start by name with new input.
- [Schedules](https://ephemer.al/docs/concepts/schedules): Start a workflow on a timetable, in any time zone.
- [Files](https://ephemer.al/docs/concepts/files): Read-only files mounted into a run.
- [Connections](https://ephemer.al/docs/concepts/connections): HTTP APIs and MCP servers, called through a broker.
- [Web access](https://ephemer.al/docs/concepts/web): Pages, search and public APIs, reached through EphemeralBot.
- [Budgets and billing](https://ephemer.al/docs/concepts/billing): How credits are reserved, charged and released.
- [Roles and keys](https://ephemer.al/docs/concepts/permissions): Who can do what, for people and API keys.

## Docs: API reference

- [Runs](https://ephemer.al/docs/api/runs): Start, list, inspect, stream and cancel runs.
- [Workflows](https://ephemer.al/docs/api/workflows): Save, list, read and delete workflows.
- [Schedules](https://ephemer.al/docs/api/schedules): Create, preview, pause and run schedules.
- [Files](https://ephemer.al/docs/api/files): Upload, list, download, rename and delete files.
- [Connections](https://ephemer.al/docs/api/connections): Configure connections and sign them in to your accounts.
- [Models](https://ephemer.al/docs/api/models): The model catalog and pricing.
- [Callbacks](https://ephemer.al/docs/api/callbacks): Signed completion callbacks.
- [Organizations](https://ephemer.al/docs/api/organizations): Members, keys, billing and licenses on the hosted service.

## Docs: Tools and operations

- [CLI](https://ephemer.al/docs/cli): The ephemeral command-line tool.
- [MCP server](https://ephemer.al/docs/mcp): Connect Claude and other AI agents to Ephemeral.
- [Self-hosting](https://ephemer.al/docs/self-hosting): Run Ephemeral on your own infrastructure, under a license.
- [Deployment licenses](https://ephemer.al/docs/licenses): Licenses for self-hosted installations.

## Samples

- [All samples](https://ephemer.al/samples): real recorded runs, each with its permissions, request and code
- [AI payment failure investigator: why did this payment fail?](https://ephemer.al/samples/investigate-failed-payment): An agent reads a payment, its attempts and the processor status page, then explains the cause and the next step for your support team.
- [AI support ticket triage: classify, prioritize and route](https://ephemer.al/samples/support-ticket-triage): An agent reads a ticket and your routing rules, then returns the category, priority, owning team and a suggested first reply.
- [Summarize a support thread with an LLM, with zero data retention](https://ephemer.al/samples/summarize-support-thread): An agent turns a long support conversation into the issue, what was tried, the customer's mood and the open question, and keeps nothing afterwards.
- [Draft replies to refund requests with AI, never send them](https://ephemer.al/samples/draft-refund-reply): An agent checks a refund request against your policy and drafts a reply for a human to approve. It cannot issue the refund.
- [Prompt injection example: what happens when a ticket tries to hijack the agent](https://ephemer.al/samples/prompt-injection-resistance): A hostile ticket tells the agent to send its API key to an attacker and issue a refund. See why it cannot, and what the timeline shows.
- [AI status page monitor: alert only when something changes](https://ephemer.al/samples/monitor-status-page): On a schedule, an agent reads a status page and returns one JSON verdict your own script can act on.
- [AI log analysis: group errors and find the likely root cause](https://ephemer.al/samples/error-log-triage): An agent runs grep and sort over 200 lines of application logs inside a sandbox with no network, then names the likely cause and the first thing to check.
- [Generate an incident postmortem draft with AI](https://ephemer.al/samples/incident-postmortem): An agent combines a status page incident with an affected payment record and fills a blameless postmortem template.
- [AI low-stock alert with reorder suggestions](https://ephemer.al/samples/low-stock-alert): An agent reads inventory and eight weeks of sales, flags the SKUs that will run out soon and suggests what to reorder.
- [Check that your scheduled jobs actually ran, with AI](https://ephemer.al/samples/cron-job-health-check): An agent reads a list of cron jobs with their last run times and flags the overdue and failing ones in plain English.
- [Competitor pricing page change detector with AI](https://ephemer.al/samples/competitor-pricing-change): An agent fetches a pricing page, compares it with the snapshot you pass in, and explains what changed and why it matters.
- [Automate a weekly KPI report with AI](https://ephemer.al/samples/weekly-kpi-report): Every Monday a scheduled agent reads last week's signups, active users, revenue and churn and writes a short report with week-over-week change.
- [Extract invoice data to JSON with an LLM, with zero data retention](https://ephemer.al/samples/invoice-to-json): An agent turns invoice text into structured JSON and checks that the totals add up. The run keeps nothing afterwards.
- [Check expense reports against company policy with AI](https://ephemer.al/samples/expense-policy-check): An agent reads a policy and a list of expenses and flags each violation with the clause it breaks.
- [Explain why revenue changed this week with AI](https://ephemer.al/samples/explain-revenue-change): An agent pulls two weeks of metrics, calculates the changes with real commands and explains the likely drivers, with caveats.
- [Clean and profile a messy CSV with an AI agent](https://ephemer.al/samples/csv-quality-report): An agent profiles a CSV with real commands in a sandbox and reports duplicates, missing values, bad formats and outliers.
- [Group customer feedback into themes with quotes, using AI](https://ephemer.al/samples/customer-feedback-themes): An agent reads survey responses and returns the main themes with counts and word-for-word quotes.
- [Generate release notes from git commits with AI](https://ephemer.al/samples/release-notes-from-commits): An agent turns a list of commits into customer-facing release notes, grouped and with breaking changes called out first.
- [Run untrusted code safely: an AI agent in a disposable sandbox](https://ephemer.al/samples/untrusted-code-sandbox): The agent writes and runs a script, tries to reach the internet, and reports that the call fails inside a microVM that vanishes afterwards.
- [AI lead qualification and scoring from your CRM](https://ephemer.al/samples/lead-qualification): An agent reads a lead and its company from a read-only CRM, scores it against your ideal customer profile and proposes the next action.
- [Review an audit log for suspicious activity with AI, with zero data retention](https://ephemer.al/samples/audit-log-review): An agent reads a day of administrative events and flags the suspicious sequence with event IDs and a recommended response.

## Trust and operations

- [Security](https://ephemer.al/docs/security): isolation, data retention, encryption, reporting a vulnerability
- [Self-hosting](https://ephemer.al/docs/self-hosting): the same product on your own infrastructure, under a license
- [System status](https://status.ephemer.al)
- [EphemeralBot](https://ephemer.al/bot): how to recognise the web requests that runs make, and how to report abuse
- [Support](https://ephemer.al/support)
- [Terms of service](https://ephemer.al/legal/terms)
- [Privacy policy](https://ephemer.al/legal/privacy)
- [Specified commercial transactions act notice](https://ephemer.al/legal/commercial-transactions)
- [Sitemap](https://ephemer.al/sitemap.xml)
- [Command-line tool releases](https://github.com/erni-works/ephemeral-cli/releases)