> ## Documentation Index > Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt > Use this file to discover all available pages before exploring further. # Environments > The sandbox a workflow runs in: Browser, Linux or Windows, the custom environments that configure it, and live environments for building and testing. Every workflow runs inside an isolated sandbox. The **environment** decides what that sandbox is, how it is configured, and how the workflow acts on the target system. There are three ways to get one. | Way | What it is | Where you set it | | - | - | - | | **Environment type** | Browser, Linux or Windows. A fresh machine per execution. | **Runs on** in the builder's bottom bar | | **[Custom environment](#custom-environments)** | A saved environment with its own environment type, networking, stealth, cookies, extensions, allowed profiles and warm pool. | **Environments** page, or **Runs on** in the builder's bottom bar | | **[Live environment](#live-environments)** | A sandbox started outside a workflow run. Astro starts one to explore and test while it builds. You can start one to drive yourself. | Astro, while it builds. You: `environmentStart` (MCP) or `POST /environments` (API) | ## Environment types A workflow has one environment type, and it applies to every node. A bound custom environment replaces it with its own environment type. | Type | Best for | How the workflow acts | | - | - | - | | **Browser** | Web apps and websites | Page structure, scripts, and screenshots | | **Linux** | Linux desktop applications | Screenshots, mouse and keyboard | | **Windows** | Windows-only software | Screenshots, mouse and keyboard | The type also decides which capabilities an Agent node can use. See [What a node can do](/concepts/node-capabilities). | Type | `browser_use` | `computer_use` | | - | - | - | | Browser | On by default | Off by default | | Linux or Windows | Always off | Always on | ### Browser A headless Chromium sandbox. Choose it when the work happens on the web: forms, web apps, pulling content out of pages, and scripted browser steps. A node in this environment has three ways to act, and one workflow can mix all three: * **Page structure**: click, type and select by reading the DOM. This is the default. * **Scripts**: deterministic JavaScript for precise, repeatable steps. * **Computer use**: screenshot and coordinate actions, for pages the DOM cannot handle. Browser downloads land in `downloads/`. See [Workflow filesystem](/concepts/filesystem). ### Linux A full Linux desktop session. Choose it for native desktop applications, terminal work, local files through desktop tools, or a mix of browser and desktop steps. The workflow works through **computer use**: the model reads screenshots and issues mouse and keyboard actions. ### Windows A Windows desktop session. Choose it for enterprise desktop tools, Windows-only vendor clients and internal apps that need a Windows runtime. The workflow works through **computer use**, the same way it does on Linux. Windows workflows start after a demo with our team. Ask us at [support@asteroid.ai](mailto:support@asteroid.ai). Computer use is slower and costs more than browser use. Pick Browser when the task can be done on the web. ## Custom environments A **custom environment** is a saved environment definition. It fixes the environment type and its settings, lists the [profiles](/concepts/profiles) the workflow may run as, and can keep pre-booted copies ready so executions start in seconds. ### In the platform Open **Environments** in the sidebar. Click **New environment** and pick **Browser**, **Linux desktop** or **Windows desktop**. The form walks through the sections one at a time. Click an environment to open its drawer. Click **Edit** in the drawer header to turn every section into its form, then save once. The page also has a **Gateways** tab when your organization has a gateway preset to manage. ### Set it from the builder Open the environment control in the builder's bottom bar. * **Runs on** picks **Default environment** or **Saved environment**. The default is a fresh Browser, Linux or Windows machine per execution. Click **View** to open the default environment's drawer read-only. A saved environment replaces the workflow's environment type. Create or edit one in place with **New** or **Edit**. * **Runs as** picks the [profiles](/concepts/profiles) the workflow may sign in as. See [Profile rows](#profile-rows). With a saved environment, every execution of the workflow boots from it. ### Sections | Section | What it decides | | - | - | | **General** | Name, **Environment type** (Browser, Linux or Windows) and, for Linux and Windows, the **Snapshot** it boots from. | | **Networking** | How traffic leaves the sandbox. | | **Browser** | Stealth, page content, cookies and extensions. Browser only. | | **Profiles** | Which profiles and profile groups may run. | | **Auth** | How sign-in state carries over: None, Authed cache, [Warm cache](#warm-cache) or [Warm pool](#warm-pool). | | **Pool members** | The live warm-pool copies. Shown when a warm pool is set. | ### Settings | Setting | Browser | Linux, Windows | | - | - | - | | **Snapshot** | — | The default image, one of your organization's snapshots, or a shared one | | **Networking** | None, Managed proxy (pick a country), Custom proxy, or Gateway (pick a gateway preset) | None or Gateway | | **Stealth** | Extra stealth and captcha solving. Both need a managed proxy. | — | | **Page content** | Ad, popup and media blocking, popups as tabs, PDF viewer | — | | **Cookies** | Injected into every session | — | | **Extensions** | Organization extensions loaded into every session. See [Extensions](#extensions). | — | ### Extensions An extension is a Chrome extension your organization uploads once. Any Browser environment in the organization can then load it. Manage them in the **Extensions** group of the **Browser** section: * **Add existing** picks extensions the organization already has. * **New extension** uploads a ZIP and adds it to this environment. `manifest.json` must sit at the root of the ZIP. The version shown comes from the manifest. Names are unique within the organization. Each row has a menu: | Action | Effect | | - | - | | **Replace version** | Uploads a new ZIP. Every environment that uses the extension gets the new version. | | **Remove from environment** | Takes it off this environment only. Saved when you save the environment. | | **Delete extension** | Deletes it from the organization. Every environment that uses it loses it. | Adding or removing an extension takes effect when you save the environment. Uploading, replacing and deleting take effect at once. ### Profile rows The profile list is a whitelist. Each row is one profile or one profile group. The builder shows the list as **Runs as**. * **No rows**: any profile or profile group may run, or none. * **One row**: only that row may run. A trigger that names nothing runs on it. * **Several rows**: every trigger must name one of them. A profile group row is named by its ID (`agentProfilePoolId`). A profile inside a group row cannot be named on its own, unless it is also a row itself. The group hands out the rest. A trigger outside the whitelist is refused with a 400 before anything runs. Runs, scheduled executions, batches and recurring schedules are checked when they are created or saved. A recurring schedule is checked again each time it fires. On the platform, the run, batch and schedule forms list only the rows. They link to the environment to add a missing profile. The list belongs to the environment. Every workflow on it shares the list. In the builder, **Copy environment for this workflow** gives one workflow its own copy. ### Warm pool Keep-warm boots copies of the environment ahead of time. An execution claims a ready copy and skips the boot. When none is ready, it cold boots as usual. The **ready count** applies per profile row. An environment with two rows and a ready count of one keeps two copies, one on each profile. A profile group row without concurrent use keeps a distinct profile on each of its copies, so it needs at least as many profiles as the ready count. A group row with concurrent use spreads its copies evenly over its profiles, so any group size works. An environment with no rows keeps the ready count in total. A claimed copy always holds the profile the execution resolved. Cookies and proxy were set at boot, so a copy on another profile is never handed out. | Setting | Meaning | | - | - | | **Usage** | Single use retires a copy after one execution. Reusable copies serve several, up to a concurrency you set. | | **Schedule** | Windows of the week with their own ready count per row, for example more during office hours and none overnight. | | **Lifetime** | Copies retire and are replaced past this age. | | **Preparation** | An agent that runs on every fresh copy before it becomes claimable, for example to sign in. | | **Success outcomes** | The outcomes of the preparation agent that mean it worked. See [Success outcomes](#success-outcomes). | Removing a row retires the copies it held. Lowering the ready count retires the oldest idle copies first. An organization can keep a limited number of warm copies across all of its environments. ### Warm cache Some portals end a session that stays idle. A warm cache keeps the session alive without holding a copy open. On a timer, it boots a browser on each profile, runs your login agent, and stops the browser. The profile keeps the fresh cookies, so the next execution starts signed in and cold boots as usual. A warm cache needs a Browser environment with cache persistence on, at least one profile row, and no warm pool. Every profile in the rows logs in, including each member of a profile group row. | Setting | Meaning | | - | - | | **Login interval** | Minutes between logins of the same profile. Keep it shorter than the portal's idle timeout. | | **Login agent** | The agent that signs in, with fixed inputs. | | **Active hours** | Windows of the week during which logins run, for example office hours. Outside them nothing runs. | | **Success outcomes** | The outcomes of the login agent that mean it signed in. See [Success outcomes](#success-outcomes). | The environment's **Logins** tab shows each profile's last login, the execution that did it, and any login that is running or failed. A failed login retries after a short backoff and keeps the last successful login on record. A login that hangs is stopped after 30 minutes. At most three logins run at once per environment. ### Success outcomes An agent that cannot sign in can still complete, for example on a `login_failed` outcome. By default any completed run counts as a success. Pick **success outcomes** to count only the runs that end on one of them. A run that completes on any other outcome is treated as a failed run. A warm pool stops that copy and boots a replacement, so an execution never claims a copy that is not signed in. A warm cache records a failed login and retries after the backoff. The choices are the outcomes of the agent's published version. Saving rejects an outcome that version does not return. If you later publish a version without a chosen outcome, no run can succeed until you update the environment. ## Live environments A **live environment** is a sandbox started outside a workflow run, instead of one an execution starts for you. Nothing runs inside it unless someone drives it. A live environment does not apply a custom environment's settings yet. ### Started by Astro Astro starts one while it builds a workflow. It boots from the workflow's environment type and the profile Astro picks. Astro uses it to explore the site and try steps before writing them. You can watch it in the builder. ### Started by you Start one to test a page or an app by hand, or to drive a browser from your own code. Start it with `environmentStart` (MCP) or `POST /environments` (API). Pass your `organizationId`, and optionally an `agentId` to bind it to a workflow. The response carries a `connection.cdpUrl`, a websocket URL at `wss://cdp.asteroid.ai`. Point any Chrome DevTools Protocol (CDP) client at it, such as Playwright's `connectOverCDP`. Read it with `environmentGet`. Stop it with `environmentStop` when you are done. One you do not stop ends on its own at its session timeout. See the [API reference](/api-reference/overview) for the full request and response shape. ## What every environment shares The sandbox layout is identical in all of them. Each execution mounts `/home/agent` with the same four directories: `shared/`, `workspace/`, `downloads/` and `uploads/`. See [Workflow filesystem](/concepts/filesystem). The [profile](/concepts/profiles) supplies secrets, whatever the environment. Capabilities and the tools they unlock Timeout and global rules The identity an environment runs as How the workflow acts in each type This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.