Environments

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.

​

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. The type also decides which capabilities an Agent node can use. See What a node can do.

​

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.

​

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.

​

Custom environments

A custom environment is a saved environment definition. It fixes the environment type and its settings, lists the 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 the workflow may sign in as. See Profile rows.

With a saved environment, every execution of the workflow boots from it.

​

Sections

​

Settings

​

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: 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. 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. 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 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. The profile supplies secrets, whatever the environment.