The vault is where your credentials are stored. You can add entries through our UI or API. When adding an entry to your vault through our API, you have to encrypt the user name, password, and any tfa_secret before sending them to us. You can find your encryption key in your workspace settings. Here’s a code snippet you can use:

Python
JavaScript

from Crypto.Cipher import AES
from Crypto.Random import get_random_bytes
import binascii, json

def encrypt_message(message: dict, key_hex: str) -> str:
    key = binascii.unhexlify(key_hex)  # 32‑byte AES‑256 key
    iv = get_random_bytes(12)          # 96‑bit IV for GCM
    serialized = json.dumps(message)   # ensure deterministic encoding
    cipher = AES.new(key, AES.MODE_GCM, iv)
    ciphertext, tag = cipher.encrypt_and_digest(serialized.encode())
    return iv.hex() + ciphertext.hex() + tag.hex()

const crypto = require('crypto');

function encryptMessage(message, keyHex) {
    // Convert hex key to bytes
    const key = Buffer.from(keyHex, 'hex');

    // Generate a random initialization vector (IV)
    const iv = crypto.randomBytes(12);

    // Serialize message
    const serializedMessage = JSON.stringify(message);

    // Create cipher object and encrypt the message
    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
    let encrypted = cipher.update(serializedMessage, 'utf8', 'hex');
    encrypted += cipher.final('hex');

    // Get authentication tag
    const tag = cipher.getAuthTag().toString('hex');

    // Return IV, encrypted message, and tag as hex strings
    return iv.toString('hex') + encrypted + tag;
}

Security Overview

Your credentials are protected with envelope encryption, the pattern recommended by NIST SP 800-57 and used by services like AWS Secrets Manager. Credentials are encrypted before being submitted to the vault and are stored encrypted at rest. The key that protects your workspace key is held in AWS KMS and never leaves it. This page explains how the pieces fit together.

Key hierarchy

Workspace encryption key (AES-256-GCM)
- One key per workspace, shared by everyone in that workspace. Find it in your workspace settings.
- You use it to encrypt usernames, passwords and TFA secrets before sending them to the vault.
- Stored persistently only in encrypted form, wrapped by AWS KMS.
- Can be rotated at any time from the dashboard.
Master key (AWS KMS)
- A 256-bit AWS KMS key protects workspace encryption keys and encrypts integration tokens, including Slack and Sentry tokens.
- The key material never leaves AWS KMS. Wrapping and unwrapping are calls to KMS, made by a single dedicated service identity that the key policy permits for that purpose only.
- AWS KMS API operations are logged in AWS CloudTrail.
- Permissions to unwrap workspace keys can be revoked through AWS KMS access controls, preventing future unwrapping operations without requiring immediate re-encryption.
- Production and development environments use separate keys.

Secret ingestion flow

You encrypt the credential with your workspace encryption key, in your own code or in the dashboard.
The ciphertext is sent to the vault. The vault checks that it decrypts with your workspace key, then stores the ciphertext.

The vault accepts credentials encrypted with the current workspace key or, during the rotation grace period, the previous key.

Runtime access

When a browser agent needs a credential:

The backend asks AWS KMS to unwrap your workspace encryption key and keeps the unwrapped key in process memory for at most 60 seconds. While a workflow-builder session is open, the key is also held in our internal cache for up to an hour so the builder agent can encrypt the credentials you enter.
The backend decrypts the credential in memory and hands it to the browser agent running your workflow.
The vault decrypts credentials in memory and does not persist plaintext credentials in its database.

Key rotation

You can rotate your workspace encryption key at any time from the dashboard. Rotation:

Generates a new workspace encryption key and wraps it with the master key.
Re-encrypts every value stored under the old key with the new key, in a single transaction. If any value can’t be re-encrypted, nothing changes and the rotation is refused.
Keeps the old key for two hours, so nothing written with it in the meantime is lost (for example from an open dashboard tab or a workflow already running).
After two hours, re-encrypts anything written with the old key during that time and deletes the old key.

You can’t rotate again during those two hours. Update any code that encrypts credentials or run inputs with the old key within that window; afterwards the vault only accepts the new key.

Threat model & mitigations

Threat	Mitigation
Database breach	Credentials are stored encrypted with workspace keys, and workspace keys are stored wrapped by a master key that never leaves AWS KMS. A database copy alone decrypts nothing.
Compromise of a single workspace key	The blast radius is that workspace only. Rotation replaces the workspace encryption key for future operations. Credentials that may have been exposed must also be rotated at their source.
Master key exposure	The key material cannot be exported from AWS KMS. Using it requires the one identity the key policy allows. Every use is logged in CloudTrail, and access can be revoked without re-encrypting data.
Ciphertext tampering	AES-256-GCM authentication tags detect unauthorized modifications to encrypted credentials, preventing altered ciphertext from being decrypted successfully.

For security questions or key-rotation assistance, email founders@cloudcruise.com.

Credential Configuration

Vault entries support comprehensive authentication and session management options to accommodate different website requirements and security needs.

Two-Factor Authentication (TFA)

CloudCruise supports multiple TFA methods for automated login flows:

Authenticator App (TOTP)

Method: AUTHENTICATOR
Setup: Provide the TOTP secret key from your authenticator app
Usage: CloudCruise generates time-based one-time passwords automatically during login

Email TFA

Method: EMAIL
Setup Options:
1. Register the CloudCruise email directly with the target account
2. Forward TFA emails from your account to the CloudCruise email
Usage: CloudCruise automatically processes TFA codes received via email

Email Magic Links

Method: MAGIC_LINK
Setup Options:
1. Register the CloudCruise email directly with the target account
2. Forward magic-link emails from your account to the CloudCruise email
Usage: CloudCruise extracts the login link from the email and navigates to it during the TFA node

SMS TFA

Method: SMS
Setup Options:
1. Register the CloudCruise phone number directly with the target account
2. Forward TFA SMS messages to the CloudCruise phone number
Usage: CloudCruise automatically processes TFA codes received via SMS

Session Persistence

Control how browser state is maintained across workflow executions:

Storage Options

Cookies: Maintains authentication cookies between runs
Local Storage: Preserves local storage data across sessions
Session Storage: Maintains session storage (typically cleared between browser sessions)

Concurrent Sessions

Allow Multiple Sessions: Enable parallel workflow executions using the same credentials
Max Concurrent Sessions: Limit the number of simultaneous sessions (leave empty for no limit)
Prevent Concurrency During Login: Block other sessions while login is in progress

Session Expiration

Configure automatic session cleanup:

Expiry from Last Use: Sessions expire after period of inactivity
Expiry from Creation: Sessions expire after absolute time from creation

Credential Pooling

Distribute runs across multiple accounts by passing an array of permissioned_user_id values instead of a single string when starting a run:

JSON
TypeScript
Python

{
  "run_input_variables": {
    "USER": [
      "user-id-1",
      "user-id-2",
      "user-id-3"
    ]
  }
}

const run = await client.runs.start({
  workflow_id: "your-workflow-id",
  run_input_variables: {
    USER: ["user-id-1", "user-id-2", "user-id-3"],
  },
});

run = client.runs.start(
    StartRunRequest(
        workflow_id="your-workflow-id",
        run_input_variables={
            "USER": ["user-id-1", "user-id-2", "user-id-3"],
        },
    )
)

CloudCruise uses round-robin selection to distribute runs across the provided credentials. Each credential’s concurrency limits and session settings are respected individually. This helps prevent rate limiting on target websites and provides fault tolerance if one credential becomes unavailable.

Pooling All Credentials for a Domain

To pool every vault entry in your workspace for the alias’s domain without listing ids, pass an empty array (or an empty string) for the alias:

{
  "run_input_variables": {
    "USER": []
  }
}

CloudCruise looks up all vault entries matching the domain bound to USER in the workflow’s vault schema and round-robins across them, as with an explicit array. Entries added to the domain later are picked up by subsequent runs automatically. The alias key must still be present in run_input_variables. If no entries exist for the domain, the run is rejected with a 400 error. The pool is fixed when the run is submitted: entries added to the domain afterwards are not picked up by that run, including its retries.

Several Aliases on One Domain

When a workflow has two or more aliases on the same domain, each alias picks from its own pool independently, so two aliases could land on the same vault entry and block each other at a concurrency limit of 1. To prevent this, the run is rejected with a 400 error when:

two aliases’ credential pools share a vault entry, or
an alias uses the domain-wide pool (empty array or empty string) while another alias in the workflow is on the same domain, because its pool would always overlap the other alias’s.

Give each alias on a shared domain explicit permissioned_user_id values that do not overlap. An alias with the domain-wide pool is fine when it is the only alias on its domain.

Proxy Configuration

Override workflow proxy settings at the credential level:

Proxy Modes

Set a credential’s proxy via proxy_setting (it overrides the workflow-level proxy for any run that uses this credential). The meaning of proxy_value depends on the mode:

`proxy_setting`	`proxy_value`	Behavior
`random`	—	A random proxy from CloudCruise’s managed pool
`static`	target IP address	The managed proxy closest to that IP — ideal for geo-restricted content or region-specific testing
`country`	country code (e.g. `US`)	A managed proxy in that country
`custom`	proxy URL	Your own proxy infrastructure (Enterprise) — see Custom URL below

Proxy priority: credential-level proxy settings take precedence over workflow-level configuration, allowing fine-grained control over network routing for specific accounts.

Custom URL (bring-your-own proxy)

Enterprise customers can point CloudCruise at their own proxy infrastructure instead of the managed pool. Select Custom URL in the credential’s proxy dropdown and provide a URL. Supported transports and authentication:

Form	Auth	Use case
`socks5://user:pass@host:port`	SOCKS5 username/password	Most residential and self-hosted SOCKS proxies
`socks5://host:port`	None (IP allowlist)	SOCKS proxies that whitelist worker egress IPs
`http://user:pass@host:port`	HTTP CONNECT + Basic auth	Squid, Tinyproxy, most corporate egress gateways
`http://host:port`	None (IP allowlist)	Corporate gateways that whitelist worker egress IPs
`https://user:pass@host:port`	HTTP CONNECT inside TLS + Basic auth	Proxies that require TLS encryption to the proxy itself
`https://host:port`	None (IP allowlist)	TLS-to-proxy with IP allowlist

Not supported (today): NTLM / Negotiate / Kerberos auth, HTTP Digest auth, and bearer-token / custom-header authentication. If your proxy requires one of these, contact us — we can scope a follow-up. UDP behavior: Preferred: a SOCKS5 proxy that supports UDP (UDP ASSOCIATE). This preserves full UDP egress — QUIC, WebRTC, and UDP DNS. If your proxy is HTTP CONNECT or a TCP-only SOCKS deployment, custom proxying still works, but the worker automatically falls back to DNS-over-TCP: HTTP/3 (QUIC) degrades to HTTP/2 over TCP (pages still load) and WebRTC-over-UDP is unavailable.

HTTP CONNECT proxies cannot carry UDP by spec. CloudCruise routes DNS over TCP through the proxy so resolution still works; Chrome’s QUIC attempts fail fast and fall back to TCP/HTTP2 automatically; WebRTC over UDP is unavailable.
SOCKS proxies vary — the spec supports UDP via UDP ASSOCIATE but many real-world deployments are TCP-only. On the first activation of a custom SOCKS proxy CloudCruise probes UDP support via a short DNS query through the proxy. If UDP works, full UDP egress (QUIC, WebRTC, UDP DNS) is preserved. If UDP doesn’t work, the worker reactivates with TCP DNS — same fallback as HTTP CONNECT. The probe result is cached for 24 h.

What CloudCruise does with the URL:

The URL is encrypted at rest with the workspace’s AES-256-GCM key (same protection as vault passwords).
On every dispatch, the URL is re-validated against SSRF rules: private/loopback/link-local IPs (incl. cloud metadata services at 169.254.169.254), .local/.internal/etc. suffixes, and hosts that resolve to CloudCruise infrastructure are all rejected.
For http/socks5 schemes, the hostname is DNS-pinned at dispatch to eliminate rebinding windows. For https, the hostname is preserved for TLS SNI validation.

Trust model:

Target-site traffic flows through your proxy. The proxy operator can see and log everything the worker sends to and receives from the target site for plain HTTP. For HTTPS, traffic is end-to-end encrypted to the target — your proxy sees the SNI and connect-traffic envelope but not the request/response body unless it performs TLS interception with a CA that the worker trusts (which is not possible on CloudCruise-managed workers).
CloudCruise infrastructure traffic (auth tokens, websocket, telemetry, screenshot uploads) is bypassed — it never traverses your proxy. The bypass covers *.cloudcruise.com, *.cloudcruise.app, and your configured Supabase host.
If sing-box (the OS-level proxy router) dies mid-session, the worker fails the run rather than reverting to direct internet egress. This protects compliance use cases where all automation traffic must stay inside the customer’s network.

Compliance note: when a custom proxy is active, traffic to the target site is egressing through customer-controlled infrastructure. The customer is the data controller for that egress, including any credentials submitted to the target site through their proxy.

Getting Started

Concepts

API Reference

SDK

Integrations

Vault

Security Overview

Key hierarchy

Secret ingestion flow

Runtime access

Key rotation

Threat model & mitigations

Credential Configuration

Two-Factor Authentication (TFA)

Authenticator App (TOTP)

Email TFA

Email Magic Links

SMS TFA

Session Persistence

Storage Options

Concurrent Sessions

Session Expiration

Credential Pooling

Pooling All Credentials for a Domain

Several Aliases on One Domain

Proxy Configuration

Proxy Modes

Custom URL (bring-your-own proxy)

​Security Overview

​Key hierarchy

​Secret ingestion flow

​Runtime access

​Key rotation

​Threat model & mitigations

​Credential Configuration

​Two-Factor Authentication (TFA)

​Authenticator App (TOTP)

​Email TFA

​Email Magic Links

​SMS TFA

​Session Persistence

​Storage Options

​Concurrent Sessions

​Session Expiration

​Credential Pooling

​Pooling All Credentials for a Domain

​Several Aliases on One Domain

​Proxy Configuration

​Proxy Modes

​Custom URL (bring-your-own proxy)

Security Overview

Key hierarchy

Secret ingestion flow

Runtime access

Key rotation

Threat model & mitigations

Credential Configuration

Two-Factor Authentication (TFA)

Authenticator App (TOTP)

Email TFA

Email Magic Links

SMS TFA

Session Persistence

Storage Options

Concurrent Sessions

Session Expiration

Credential Pooling

Pooling All Credentials for a Domain

Several Aliases on One Domain

Proxy Configuration

Proxy Modes

Custom URL (bring-your-own proxy)