How workflows, environments and profiles connect
Think of a job, a machine and an account.- The workflow version picks the machine. A trigger cannot pick it.
- The machine lists the accounts it accepts, and refuses any other.
- The trigger picks the account from that list.
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.
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.Windows workflows start after a demo with our team. Ask us at [email protected].
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 Gateways tab holds your gateways: a fixed IP, or a route into your own network. See Networking.Set it from the builder
Open the environment control in the builder’s bottom bar. It lists the Built-in base environments and your Custom environments. New environment creates one. The choice is saved on the workflow version, not on the workflow. A run uses the published version unless the trigger asks for another, so publish the version for its environment to take effect. A version under test can point at a different environment from the published one. A custom environment replaces the workflow’s environment type. Every execution of that version boots from it.Sections
Settings
Addresses
Addresses sets which IP address each run leaves from. It is in the Networking section, under the network.
One per login needs a managed proxy. On a gateway, a tunnel, a custom proxy or no proxy, the network
sets the address, and saving one per login is refused. A browser on Anchor needs the US.
It also needs a plan with sticky IP.
A login gets its address on its first run on the environment. That run signs in again, because a
login keeps a separate saved sign-in for one-per-login environments. Later runs stay signed in.
Changing the setting deletes no saved sign-in.
With one per login on, the drawer’s Networking section lists each login the profile rows name,
and each login that ran in the last 30 days: its address, since when, and its last run. A login with no address yet
gets one on its next run.
MCP and the CLI read the same list with
custom_environment_addresses_list.
A login profile with the deprecated Sticky IP switch on also keeps
its own address on the managed proxy. The switch will be removed, so set Addresses here instead.
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.jsonmust sit at the root of the ZIP. The version shown comes from the manifest. Names are unique within the organization.
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.- 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 trigger that names nothing is refused.
profileGroupId). 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. To give one workflow its own list, create a separate environment for it.
Warm pool
Keep-warm boots copies of the environment ahead of time. An execution claims a ready copy and skips the boot. A warm pool is a capacity limit, not only a speed-up. When no copy is ready for the run’s profile, the trigger is refused with a 429. It does not fall back to a cold boot. The error names the profiles that do have a ready copy. Retry the call, and size the ready count for peak load, not average load. 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 alogin_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.
How a run is routed
Every execute call, schedule, scheduled execution and batch item takes these steps in order.
The environment then supplies the machine type, snapshot, networking, addresses, stealth, extensions and cookies. The profile supplies secrets, the email inbox and saved browser state.
Best practices
- Create one environment per portal and network path, not one per workflow.
- Share an environment only between workflows that sign in with the same profiles. They share its profile list.
- Keep one profile row when you can. Triggers then need not name a profile. To rotate accounts, put them in one profile group row, not in several rows.
- Put a profile in one place: its own row, or a group row. Not both.
- Add a warm pool only when boot or sign-in time matters. Callers must retry on 429.
- Do not delete an environment or a profile group while a workflow version, schedule or batch uses it. A deleted environment makes every run of the versions that point at it fail with a 400.
- Remember that the environment is picked per version. A test of an unpublished version can run on a different environment from the published one.
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 bound to a workflow boots from the workflow’s custom environment, if it has one. It takes the environment type, snapshot and settings. Under a warm cache with Executions save browser state (e.g. cookies) off, it loads the profile but does not save it. A live environment with no workflow uses no custom environment.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 withenvironment_start (MCP) or POST /environments (API). Pass your organizationId, and optionally a workflowId 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 environment_get. Stop it with environment_stop 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.
What a node can do
Capabilities and the tools they unlock
Workflow settings
Timeout and global rules
Profiles
The identity an environment runs as
Browser vs computer use
How the workflow acts in each type

