Skip to main content
An agent profile holds everything a workflow needs to sign in and act as one identity. A profile carries:
  • credentials in a vault
  • two-factor secrets
  • cookies
  • browser cache and session state
  • proxy and captcha settings
  • an email inbox
A profile is reusable. Many workflows can share one profile, and one workflow can run with a different profile on every execution.

​
Attaching a profile to an execution

An execution uses at most one profile. You pick it when you start the execution.
Pass agentProfilePoolId instead to let Asteroid choose a profile from a pool.
agentProfileId and agentProfilePoolId are mutually exclusive. Pass one or the other, never both.
On the platform, choose the profile or the pool in the dropdown next to Run. See Call a workflow from your code for the full execute call.

​
Profile configuration

  • Proxy country code — the country the proxy routes through. One of us, uk, fr, it, jp, au, de, fi, ca.
  • Proxy type — the managed proxy connection to use. basic.
  • Persistent IP — keep the same IP address across requests.
Persistent IP locks the profile to a basic proxy in the us. The country and type selectors are fixed while it is on. It works with a platform-managed proxy only. Custom and gateway proxy modes reject it.
Turn automatic captcha solving on or off for the profile.
Cache persistence controls whether browser cache and cookies survive between runs.
  • On — the profile keeps session state, cookies and cached data across runs.
  • Off (the default) — every execution starts with a fresh browser state.
Clear the stored cache at any time with Clear Cache on the profile.
Every profile gets an inbox at {prefix}@agentmail.asteroid.ai. The default prefix is the profile’s UUID. Set a prefix to get a readable address. See Workflow emails.
Create and manage profiles on the platform, through the API, or through the SDKs. See the API reference.
Deleting a profile affects every workflow that references it. Check that no live automation depends on it first.

​
Credentials

Store credentials in the profile’s Vault. Each entry has a name and a value. The platform mirrors each vault name into a placeholder token of the form ##CREDENTIAL_NAME##. The name is uppercased, with underscores, to match how substitution normalises it. Use the placeholder in:
  • Agent node instructions
  • Browser automation scripts — the runtime injects the decrypted value into browser inputs only, not into shell or file tools
This injection path is separate from the args a scripted Agent node receives. Those come from the node’s declared inputs. See Nodes.
Never paste a real secret into instructions or scripts as plain text. Use a vault placeholder.
Read Security for how Asteroid stores and encrypts these values.

​
Two-factor codes

A profile can hold a TOTP secret, so the workflow generates its own authenticator codes. Asteroid supports every standard TOTP provider, including Google Authenticator, Microsoft Authenticator, Authy and 1Password.
1

Get the TOTP secret key

Ask the target service for the manual setup key rather than the QR code. Most sites offer it behind a Can’t scan it?, manual entry or setup key link.The key is a Base32 string of 16–32 characters.
2

Store it in the vault

Create a credential on the profile and paste the key as the value.The credential name must start with TOTP_ or 2FA_. The rest of the name is yours to choose.
3

Run the workflow

Nothing needs enabling on the node. Agent nodes can always generate TOTP codes. The tool works as soon as the profile holds a TOTP credential.
Codes expire after 30 seconds, so tell the workflow to generate one immediately before it submits. For codes that arrive by email instead, see Workflow emails.

​
Cookies

A profile can store site cookies, so an authenticated session survives between runs. Add cookies when you create the profile, or manage them later through the API. A cookie has these fields:

​
Profile pools

A profile pool groups profiles together. You point a run at the pool, and Asteroid picks a profile from it. Pools solve four problems:
  • Credential conflicts — stop two executions using one account at the same time.
  • Rate limits — spread requests across several accounts.
  • Availability — fall back to another profile when one is busy.
  • Manual selection — remove the choice from every execute call.

​
Selection strategies

A pool uses one of two strategies. Least recently used rotates fairly. With profiles A, B and C, an execution after B picks whichever of A or C idled longest. Most recently used concentrates work on fewer profiles. It keeps browser state and authenticated sessions warm.

​
Concurrent use

allowConcurrentUse decides whether a busy profile can be picked again.
With allowConcurrentUse: false, a request fails immediately when every profile in the pool is busy. The error says no profile is available. Add more profiles, or allow concurrent use.

​
Pool constraints

An execute call takes agentProfileId or agentProfilePoolId, never both.
  • Every profile in a pool belongs to the same organization.
  • A pool name is unique within an organization.
  • A profile from another organization cannot join the pool.
  • A pool needs at least one profile before an execution can use it.
  • Remove the last profile and no new execution can use the pool.
Match the pool size to your parallelism. Five simultaneous runs need at least five profiles. Add one or two spare profiles for peak load.
A pool works with every profile feature — credentials, cookies, TOTP secrets, inbox and cache persistence. The selected profile’s configuration applies exactly as if you had named it yourself.

Call a workflow

Pass a profile or a pool on the execute call

Workflow emails

The inbox each profile owns

Workflow settings

What the workflow owns instead of the profile

Security

How Asteroid protects stored credentials