Web access lets an agent read pages, search the web and call public APIs during a run. The microVM itself has no internet: every request goes through Ephemeral, which checks it, sends it as EphemeralBot and records it.
Turning it on
Web access is off unless a run or workflow sets web. The playground in the dashboard turns it on for you.
"web": trueTo keep a run to certain sites, list them in allow. api.github.com matches only that host; *.github.com matches every subdomain and github.com itself. Redirects are checked against the same list. Set search to false to leave out web search.
"web": { "allow": ["api.github.com", "*.stripe.com"], "search": false }In a workflow file the same setting reads web: true, or web: with allow and search beneath it. A run request's web replaces the workflow's for that run.
What the agent can do
| Tool | Does |
|---|---|
web_ | Sends a request with any method, headers and body, and returns the status and the response as text. HTML pages are turned into readable text with their links. Long responses come in parts of 40,000 characters; reading the next part of a page the run already fetched is free. |
web_ | Searches the web and returns up to 10 results, each with a title, URL and short extract. The agent reads a result in full with web_fetch. |
Every run's agent is told how its machine works: that the shell has no network, so curl or pip install will fail, and that it should reach the web with these tools instead.
What Ephemeral checks
- The destination is a public address on port 80, 443, 8080 or 8443, over HTTP or HTTPS, and on the run's allowlist. Every redirect is checked again, up to five.
- A safety classifier reads each request with the run's task and refuses ones that look like an attack on a system, spam or fraud, or data being sent somewhere the task does not call for. If the classifier cannot answer, reads go ahead and requests that could change data are refused until it can.
- A run can make 50 web requests and searches. An organization can make 120 a minute, and all customers together send a single site at most 60 a minute. When a limit is reached, the agent is told and the request is not sent.
- Request bodies are up to 1 MiB, and up to 10 MiB of each response is read.
- Requests follow rules a site's robots.txt sets for EphemeralBot by name. The EphemeralBot page explains how site owners recognise and block it.
A refused request is recorded with its reason, and the agent receives the same reason so it can change course. The run carries on.
Cost
On the hosted service each request costs $0.001 and each search $0.01. Both come out of the run's budget like model calls; a request that would go over it is refused. Refused requests are not charged. See pricing.
Events
| Type | Recorded when |
|---|---|
web_ | A request was sent. Includes the method, final URL, status, size, duration, cost, the safety scores and the request ID it carried. |
web_ | A search ran. Includes the query, how many results it returned, and its cost. |
web_ | A request or search was refused before it was sent. Includes the reason. |
Credentials
web_fetch sends whatever headers the agent sets, so an API key the agent uses has to be in the prompt or input, where it is stored with the run. For an API you call with a secret, a connection is better: Ephemeral keeps the secret and the agent never sees it.
Self-hosted installations
The engine sends web requests from its own host. Set EPHEMERAL_WEB_SOURCE_IP to a separate address on that host to keep them apart from your other traffic. Web search uses the OpenRouter key in INFERENCE_API_KEY; with another provider, search is unavailable.
The safety classifier is off on self-hosted installations, because it runs on your inference account. To turn it on, set EPHEMERAL_WEB_CLASSIFIER_MODEL=typesafe/jev-1.13 with an OpenRouter key. Without it, your allowlists, the rate limits and the network rules still apply.