> ## 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.
# Custom environments
> A reusable environment definition — base machine, browser settings, a whitelist of profiles, and an optional warm pool that keeps copies ready per profile.
A **custom environment** is a saved environment definition an agent binds to. It fixes the base machine and its settings, lists the profiles the agent may run as, and can keep pre-booted copies ready so executions start in seconds.
Bind an agent to one in [Workflow settings](/concepts/workflow-settings). Every execution of that agent then boots from the custom environment instead of the agent's own [environment](/concepts/environments).
## What it holds
| Part | What it decides |
| ------------- | ----------------------------------------------------------------------------------------------------- |
| **Base** | Browser, Linux or Windows, and the provider that boots it. Replaces the agent's own environment type. |
| **Settings** | Proxy, cookies, extensions and browser flags the environment boots with. |
| **Profiles** | An ordered list of [profiles](/concepts/profiles) and profile pools. The whitelist below. |
| **Warm pool** | How many copies to keep ready, per profile row, and for how long. |
## Settings
Browser settings live on the custom environment, not on the agent profile.
| Setting | Browser | Linux, Windows |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| **Proxy** | None, managed (country, captcha solver, persistent IP), custom, or gateway | None or gateway |
| **Cookies** | Injected into every session | — |
| **Extensions** | Organization extensions loaded into every session | — |
| **Browser flags** | Operating system, extra stealth, third-party cookies, cache persistence, ad, popup and media blocking, popups as tabs, PDF viewer | — |
Agent profiles used to hold these settings. Values already stored on a profile still apply when its agent runs without a custom environment. They can no longer be edited on the profile in the platform.
## Profile rows
The profile list is a whitelist. Each row is one agent profile or one profile pool.
* **No rows**: any profile or pool 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 counts as named when it is a row itself or a member of a pool row.
A trigger outside the whitelist is refused with a 400 before anything runs. Runs, scheduled executions, batches and recurring schedules are all 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.
## 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 pool row keeps a distinct profile on each of its copies, so a pool row needs at least as many profiles as the ready count. An environment with no rows keeps the ready count in total.
A claimed copy always holds the profile the execution resolved. Cookies, proxy and fingerprint were set at boot, so a copy on another profile is never handed out.
Other warm pool settings:
| 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. |
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. The cap counts the total across rows.
The identity an environment runs as
Browser, Linux and Windows sandboxes