Revyl Documentation

Runtime / Mobile

Session profiles

Look up session profile keys, where profiles run, the script's environment and output files, precedence, and errors.

A session profile is a script in your project that runs once as a session starts, before your app launches, and sets up the state the session starts in. The script can sign in, seed data on your servers, and write files that give the session its app launch environment, iOS launch arguments, browser storage state, first deep link, and variables for the session's steps. You name profiles in .revyl/config.yaml, choose a default, and pick another for one start with --session-profile. To add one, see Set up a session profile.

Profiles work for iOS, Android, and web sessions.

Session profiles and session.before_script with session.auth_bypass are two supported ways to prepare a session. A config uses one or the other: a config that sets session.profiles doesn't set session.before_script or session.auth_bypass.

Auth and session prep describes session.before_script and session.auth_bypass, and Compared with the before script and auth bypass settings maps each of them to a profile.

Where profiles apply

StartProfile it usesWhere the script runs
revyl dev and revyl device start--session-profile, otherwise the defaultThe machine that runs the CLI
start_dev_loop and start_device_session in the local MCP server (revyl mcp serve)session_profile, otherwise the defaultThe machine that runs the MCP server
CI jobs that run those commandsSame as the commandThe CI runner
Proof of changes runsThe default, unless the agent passes --session-profileThe proof agent's checkout of the pull request
The Open preview link in a pull request commentThe defaultRevyl's hosted runner

Profiles don't apply to test runs, workflows, live sessions started in the Revyl app, Verify, the hosted MCP server, explore, or schedules, and a test can't name a profile. A web test run can still start with cookies, as Cookies without a script describes. No session profile runs inside a computer: the default doesn't run there, and --session-profile <name> fails with session profile "<name>" can't run inside a computer; pass --session-profile none or --computer none. Native macOS apps have no profiles.

Cookies without a script

--cookies-file gives a web session browser storage state without a profile script, on revyl device start --platform web and on revyl test run for a web test. The file holds the storage state a profile's REVYL_BROWSER_STORAGE_STATE_FILE holds, such as Playwright's storageState() output, or a JSON array of its Playwright cookie objects; other cookie export formats fail. In this example, <session-cookie> stands for the session cookie your app's sign-in returns:

[
  {
    "name": "session",
    "value": "<session-cookie>",
    "domain": "app.example.com",
    "httpOnly": true,
    "secure": true
  }
]
revyl device start --platform web --app <app-id> --cookies-file cookies.json
revyl test run <web-test> --cookies-file cookies.json

Every cookie names its domain. The CLI checks the file with the rules and limits of a profile's storage state file and sends it as an applied profile named cookies-file. When the start also runs a profile, the file's cookies and localStorage come after the profile's, so the file wins where both set the same cookie or item. The browser holds them before its first navigation, so the session's Web sign-in, when it has one, runs after them and can replace them. They stay out of logs and reports like the profile's output files. A file with no cookies or origins fails, and a start inside a computer and a mobile test run refuse the file.

Through the API, a web session start or a test run takes the same instruction as session_profile, under a profile name you choose; a test run takes only applied:

{
  "instruction": "applied",
  "name": "cookies-file",
  "outputs": { "browser_storage_state": { "cookies": [], "origins": [] } }
}

Config

Profiles live under session in .revyl/config.yaml, beside idle_timeout_seconds:

session:
  idle_timeout_seconds: 600
  default_profile: signed-in
  profiles:
    signed-in:
      script: scripts/revyl/signed-in.sh
    seeded-cart:
      script: seed-cart
      requires_repository_checkout: true
KeyTypeRequiredDefaultDescription
session.profilesmapNoProfiles by name. When present, it holds at least one profile.
session.profiles.<name>.scriptstringYesThe script the profile runs: a repository path or a script name, as Script references describes.
session.profiles.<name>.requires_repository_checkoutboolNofalseWhether the hosted runner clones the repository before it runs the script. See The hosted runner's environment.
session.default_profilestringNoThe profile a start uses when it doesn't pick one. none means no default.

A profile name uses lowercase letters, digits, and dashes, from 1 to 64 characters. none is reserved: it means no profile wherever you pick one. A profile has only the keys script and requires_repository_checkout.

session.default_profile needs session.profiles and names one of its profiles, or is none. A config with session.profiles can't also set session.before_script or session.auth_bypass. Errors lists what validation reports.

Revyl stores each script value exactly as you write it, with no path rewriting.

Script references

A script that contains a / is a path from the project root, the directory that holds .revyl/. Write a file in the project root as ./setup.sh. The path can't leave the repository. The file runs as a program, so it needs a #! line and its executable bit.

A script without a / is a script name. Revyl looks for .revyl/scripts/<name>.sh, .py, .js, or .ts in the repository first, and then for the Library Script with exactly that name. Two files in .revyl/scripts/ with the same name and different extensions fail the start, and so do two Library Scripts with the same name, as Errors lists. A named script runs with its runtime, where <file> is the script file Revyl found:

RuntimeFileCommand
Bash.shbash <file>
Python.pypython3 <file>
JavaScript.jsnode <file>
TypeScript.tsnode --disable-warning=ExperimentalWarning <file>

TypeScript runs on Node.js's built-in type stripping, which needs Node.js 22.18 or later and allows only erasable TypeScript syntax. When the machine that runs the CLI lacks the interpreter, the start fails and names it. A Library Script in any other runtime fails the start too.

Where Revyl reads profiles

CLI starts read .revyl/config.yaml in your checkout. The Open preview link and proof runs read the configuration the pull request uses, as Pull-request configuration lifecycle describes. A project without Git-managed configuration publishes its config with revyl config push (Configuration publication and retrieval). A Revyl CLI or Revyl app tab from before session profiles can't save a project that has them, because saving would remove them.

In the Revyl app, an app's Session settings show a Session profiles card with each profile's script, marked Default and Needs repository checkout where they apply. The card is read-only.

Picking a profile

Each start picks at most one profile:

  1. An explicit pick wins: --session-profile <name> on revyl dev and revyl device start, or session_profile on the local MCP server's start_dev_loop and start_device_session.
  2. Otherwise the start uses session.default_profile.
  3. With no default, or a default of none, the start runs no profile.

Pick none to start without the default, for example to test the sign-in screen itself:

revyl device start --platform ios --session-profile none

A name the project doesn't define fails before anything starts, and the error lists the profiles it does define. A project without session.profiles accepts only none. The Open preview link always uses the default profile.

The script's environment

Revyl sets these variables for the script:

VariableValue
REVYL_PLATFORMThe session's platform: ios, android, or web
REVYL_SESSION_PROFILE_NAMEThe profile's name
REVYL_SESSION_WEB_ORIGINWeb sessions only: the app's origin, such as https://app.example.com for a deployed URL, or http://revyl-app.localhost:3000 for a bundle Revyl serves, with the bundle's run port in place of 3000
REVYL_BACKEND_URLThe Revyl API the session uses
REVYL_API_KEYHosted runs only: a key for this run
The seven output pathsOne file path per output, as Output and failure lists

On the machine that runs the CLI

The script runs from the project root with your whole environment and your Revyl login, so revyl commands in it act as you. Revyl doesn't set REVYL_API_KEY; one already in your environment stays as it is. The script uses the interpreters on your PATH.

The start waits for the script. With revyl dev --detach and start_dev_loop, the wait for the session to be ready begins after the script finishes. The CLI prints Running session profile <name>... while the script runs and Applied session profile <name> once its outputs pass. The JSON output of revyl device start and revyl dev status, and the results of the local MCP server's start tools, name the profile a session started with as session_profile.

The hosted runner's environment

The Open preview link runs the profile on Revyl's hosted runner, in a new sandbox for each session:

AspectOn the hosted runner
CommitThe pull request's head commit, or the default branch's head when the pull request comes from a fork.
FilesWithout requires_repository_checkout, the script runs in an empty directory that holds only the script. With requires_repository_checkout: true, Revyl clones the commit and runs the script from the project root. Nothing installs dependencies; a script installs what it needs.
Toolsbash, curl, git, jq, Python 3.12, Node.js 22, and the revyl CLI on the PATH.
EnvironmentOnly HOME, LANG, PATH, and the variables Revyl sets for the script.
REVYL_API_KEYA key for this run alone. It can only read your organization's variables and launch configurations, reveals secrets as Who can read secrets describes, and stops working when the run ends, 15 minutes after the run starts at the latest.
NetworkOutbound requests come from the same address as the Revyl proof agent's, listed in Network allowlisting.

The session's device or browser starts while the script runs, and the app launches once the script's outputs are ready.

Output and failure

Every output is optional. Revyl points each path variable at a file that doesn't exist yet, in a new directory only the script's user can read. A file the script doesn't write, or leaves empty, means nothing. Revyl deletes the directory after reading it.

Output files

The script hands values back by writing to the file each variable names, the way a GitHub Actions step writes to $GITHUB_OUTPUT and $GITHUB_ENV, so nothing the script prints can become a value.

VariableiOSAndroidWeb
REVYL_LAUNCH_ENV_FILE-KEY value launch argument pairsString Intent extrasEnvironment of an app Revyl runs with a start command
REVYL_SECRET_LAUNCH_ENV_FILEThe same, kept secretThe same, kept secretThe same, kept secret
REVYL_IOS_LAUNCH_ARGUMENTS_FILELaunch argument tokens, in orderFails the startFails the start
REVYL_BROWSER_STORAGE_STATE_FILEFails the startFails the startCookies and localStorage the browser starts with
REVYL_DEEP_LINK_FILEOpened after the app launchesOpened after the app launchesThe first page opened
REVYL_VARIABLES_FILEVariables for the session's stepsSame as iOSSame as iOS
REVYL_SECRET_VARIABLES_FILESecret variables for the session's stepsSame as iOSSame as iOS

Launch environment values reach the app the way environment launch configurations do. Secret values, and the arguments, storage state, and deep link files, stay out of logs, reports, and the session's launch snapshot.

A mobile deep link is a URL with a scheme, and any host it names must be valid. In a revyl dev loop it opens after the dev client's link, and again after each relaunch. A web deep link is a path that starts with / on the app's origin, or a full http or https URL. On a mobile session, --app-link on revyl device start, or app_link on start_device_session, replaces the profile's deep link.

Variables become {{KEY}} in the steps you run in the session, such as revyl device instruction and revyl device validation. A plain variable ranks below any variable the session already has. The agent sees a secret variable only as its placeholder, and Revyl fills its value in at the device.

File formats

Every file is UTF-8 text, and a leading byte order mark is ignored. A line ends at LF, and a CR right before the LF is dropped. A last line without an LF still counts. Invalid UTF-8 or a NUL character fails the start.

The four KEY=VALUE files (both launch environment files and both variables files) hold one KEY=VALUE per line, split at the first = with no trimming. Blank lines are ignored, and any other line that isn't KEY=VALUE or a KEY<<DELIMITER block fails the start:

  • A key matches ^[A-Za-z_][A-Za-z0-9_.-]*$, has at most 256 characters, and doesn't start with DYLD_, SIMCTL_CHILD_, or COGNISIM_ in any letter case.
  • An empty value fails the start.
  • A key that appears twice fails the start, within one file or across the plain and secret files of the same kind.

A multi-line value uses KEY<<DELIMITER, then the value's lines, then a line that is exactly the delimiter. The value is those lines joined with LF; to end it with a newline, add an empty last line. Pick a random delimiter, because a line of the value that equals it ends the value early:

SIGNING_CERT<<EOF_7f3a9c
-----BEGIN CERTIFICATE-----
MIIB...
-----END CERTIFICATE-----
EOF_7f3a9c

The iOS arguments file holds one token per line, with no trimming. A line <<DELIMITER starts a multi-line token that a line equal to the delimiter ends. An empty token, such as a blank line, fails the start, except blank lines at the end of the file.

The deep link file holds one non-empty line.

The storage state file is Playwright storage state JSON, the format of Playwright's storageState(). Each origin is an http or https origin with no path. An unknown field fails the start, and so does an unpaired UTF-16 surrogate escape such as a lone \ud800. In this example, <session-cookie> stands for the session cookie your app's sign-in returns:

{
  "cookies": [
    {
      "name": "session",
      "value": "<session-cookie>",
      "domain": "app.example.com",
      "path": "/",
      "expires": -1,
      "httpOnly": true,
      "secure": true,
      "sameSite": "Lax"
    }
  ],
  "origins": [
    {
      "origin": "https://app.example.com",
      "localStorage": [{ "name": "onboarding-done", "value": "true" }]
    }
  ]
}

Platform rules and limits

A file written for a platform it doesn't apply to fails the start, as the output table shows. On web, the launch environment files also fail when the build is a deployed URL, an external pull request preview URL, or a static bundle, because only an app Revyl runs with a start command has a process to take them. A web deep link can't contain ${NAME} references.

A web session's launch environment follows the per-session environment override rules: names match [A-Za-z_][A-Za-z0-9_]{0,127}, the runtime's own names are refused, a session takes at most 32 values from the profile and --launch-env together, each value is at most 4,096 bytes with no control characters, and names plus values stay within 128 KiB.

OutputLimit
Each file1 MiB
Both launch environment files128 keys, 32 KiB per value, 256 KiB of keys and values
Both variables files256 keys, 256 KiB of keys and values
iOS arguments256 tokens, 64 KiB
Deep link8 KiB
Storage state1 MiB as compact JSON

The limits apply after Revyl fills in ${NAME} references, so a reference to a large stored value can push a file over its limit and fail the start.

When a profile fails

Revyl never shows, logs, or stores the script's standard output and standard error, because setup scripts often print credentials. To debug a script, run it on your machine as Run the script on your machine shows.

The script must finish within 300 seconds. When it exits or times out, Revyl stops its whole process group.

A failure fails the start with a reason that never includes a value. A CLI start fails before the device or browser starts. A mobile deep link that fails to open also fails the start, and the CLI stops the session. After a relaunch in a revyl dev loop, a deep link that fails only warns.

On the Open preview link, a failed profile fails the session and shows the reason, so the preview never opens the app without its setup. Revyl never retries a failed run; open the preview again for a new session.

Before the script runs, the CLI checks that the Revyl API supports session profiles, and once the session starts, it checks that the API started it with the profile. Errors lists what each failure reports.

Precedence

When several sources set the same launch environment key on a mobile session, the higher one wins. From lowest to highest:

  1. Launch configurations attached to the test a session starts from, when it starts from one.
  2. The profile's launch environment files.
  3. Stored launch configurations the start selects, such as --launch-var and the IDs in REVYL_INHERITED_LAUNCH_ENV_VAR_IDS.
  4. Inline values, such as --launch-env.

iOS launch arguments are a list, so Revyl keeps every token and orders them, from first to last:

  1. Argument sets attached to the test a session starts from, in their usual order.
  2. The profile's iOS arguments file.
  3. --launch-arg-set sets, in flag order.
  4. --launch-arg tokens.
  5. The -KEY value pairs from launch environment values.

Revyl doesn't remove repeated flags; your app's argument parser decides what they mean.

On web, the profile's launch environment merges over the environment of the build's run: it replaces the values of names it sets and keeps the build's other values, including the organization's secrets and the sign-in its project configures. A --launch-env value beats the profile's value for the same name, and any --launch-env override drops the organization's secrets and sign-in for that session, as Per-session environment overrides describes. A profile's launch environment also works on a pull request preview bundle Revyl runs, which takes no --launch-env overrides.

References to stored values

A launch environment value, in either file, or a mobile deep link can contain ${NAME}, where NAME is the key of an environment launch configuration in your organization. Revyl fills in the stored value when the session starts, so the script never sees it and needs no right to reveal it:

echo 'REVYL_AUTH_BYPASS_TOKEN=${REVYL_AUTH_BYPASS_TOKEN}' >> "$REVYL_LAUNCH_ENV_FILE"
echo 'myapp://revyl-auth?token=${REVYL_AUTH_BYPASS_TOKEN}' > "$REVYL_DEEP_LINK_FILE"

NAME matches [A-Za-z_][A-Za-z0-9_]*. A value that fills a secret launch configuration stays secret wherever it travels. A ${NAME} that names no stored environment launch configuration fails the start. A start made with a key that can't use secret launch configurations, such as a computer's key, can't reference one either.

Once per session

A profile script may seed data, so it runs at most once per session, and the result belongs to the session for its whole life:

  • Reusing or attaching to a session, relaunching the app, a revyl dev rebuild, and revyl dev auth refresh never run the script again.
  • revyl dev auth refresh reopens the deep link the profile wrote when the session started. A web session, a session that started without a profile, and a profile that wrote no deep link or whose deep link --app-link replaced leave it nothing to reopen, so it fails and suggests revyl dev stop and then revyl dev.
  • A mobile deep link's ${NAME} keeps the value the session's launch environment got when it also fills there. If that launch configuration changes while the session runs, reopening the deep link fails until you start a new session.
  • A failed hosted run is never retried.
  • A different profile needs a new session. Picking another profile for a session that revyl dev would reuse, or that a running revyl dev loop holds, fails until you stop the loop with revyl dev stop, or stop_dev_loop in MCP.

Revyl never refreshes outputs during a session, so a token the script mints has to last the whole session, a long revyl dev --remote build included. When it expires, stop the session with revyl device stop or revyl dev stop and start a new one.

Who can read secrets

A profile script that computes something from a stored secret reads it with revyl global var get <name> --reveal or revyl global launch-var get <key> --reveal, described in Global variables and Launch configuration. Most scripts don't need to, because a reference passes a stored value through without the script seeing it.

Who can reveal a secret depends on the credential the script runs with. A CLI start on your machine runs the script with your login.

Your own login or personal API key reveals any secret unless your role is Viewer. Every other key, such as a CI or agent key, a proof run's key, or the key Revyl's hosted runner uses for the Open preview link, reveals only a secret marked Readable by automated runs. Only a member signed in with their own login or personal API key can set or clear the mark, and a marked secret is readable by every automated run in the organization.

Set or clear the mark in the Library, or with --readable-by-automated-runs on revyl global var set and revyl global launch-var update. Nothing is marked automatically, and Revyl audits every reveal by the secret's name.

Revyl's own workers fill secrets into sessions with their own credentials, so the mark doesn't change what runs receive. When a run resolves global variables (/api/v1/variables/global/resolve), the mark limits only the hosted runner's key; other keys read secrets there whether or not they're marked.

Compared with the before script and auth bypass settings

session.before_script and session.auth_bypass are the other way to prepare a session, described in Auth and session prep. A profile script can do what each setting does:

SettingWhat the profile script does
session.before_scriptRuns the same script and copies its KEY=VALUE lines to a launch environment file.
session.auth_bypass.launch_varsWrites KEY=${KEY} to REVYL_LAUNCH_ENV_FILE for each key. Revyl fills each reference from the organization launch variable with that key, and a secret one stays secret.
session.auth_bypass.deep_linkWrites the deep link to REVYL_DEEP_LINK_FILE. A ${NAME} there fills only from organization launch variables, so a token the script minted goes into the link as its value.
session.auth_bypass.sign_inOn a deployed URL, signs in over HTTP and writes browser storage state. On an app Revyl runs, writes a sign-in URL as the deep link, with a code the script mints. Revyl doesn't check that this URL signs in, as it does for sign_in.

The two ways differ in these ways:

  • A profile's launch values rank below --launch-var, and session.before_script values rank above it. See Precedence.
  • A profile script has 300 seconds and no timeout_seconds setting.
  • A profile also runs for web sessions, and session.before_script runs only for iOS and Android. The script reads REVYL_PLATFORM (ios, android, or web) to tell them apart.
  • revyl dev auth refresh reopens the profile's deep link, as it reopens session.auth_bypass.deep_link, and doesn't run the script again.
  • The Open preview link runs the profile on Revyl's hosted runner, which has only the variables Revyl sets, as The hosted runner's environment describes. session.before_script doesn't run there, and the preview link applies session.auth_bypass from organization launch variables.

Set up a session profile shows a profile script that does what both settings do.

Errors

Each message below is what the CLI reports, with the cause and the fix. In the messages, <name> is the profile's name and <script> is its script value.

MessageCauseFix
session.default_profile is not a supported field or session.profiles is not a supported fieldThe Revyl CLI predates session profiles.Update the CLI on that machine or CI job.
session.auth_bypass cannot be combined with session.profiles; write its launch values or deep link from a profile scriptThe config sets both session.profiles and session.auth_bypass, and a config uses one or the other.Keep one: remove session.profiles and session.default_profile, or remove session.auth_bypass and write its values from the profile script, as If your config uses before_script or auth_bypass shows.
session.before_script cannot be combined with session.profiles; make it a profile scriptThe config sets both session.profiles and session.before_script.Keep one: remove session.profiles and session.default_profile, or remove session.before_script and run its script from the profile script.
session.default_profile requires session.profilesThe config sets session.default_profile without session.profiles.Add session.profiles, or remove session.default_profile.
session.default_profile must name a profile in session.profiles, or be "none"The default names a profile the config doesn't define.Name a profile from session.profiles, or none.
session profile "<name>" isn't defined; this project defines: <names> (or none)The start picked a profile the config doesn't define.Pick one of the listed names, or none.
session profile "<name>" isn't defined: this project has no session.profiles in .revyl/config.yaml (pick none to start without one)The start picked a profile, and the config has no session.profiles.Pick none, or add the profile to the config.
session profile "<name>" can't run inside a computer; pass --session-profile none or --computer noneThe start runs inside a computer, where no session profile runs.Pass --session-profile none, or --computer none to start outside the computer.
This project's session profiles need a newer Revyl backendThe Revyl API the CLI uses doesn't support session profiles.Start with --session-profile none until the API supports them.
session profile "<name>": could not check whether the Revyl backend supports session profiles: <error>The CLI couldn't complete its check with the Revyl API.Fix the error it names, such as the network or your sign-in, and start again.
session profile "<name>": script <script> was not found in the repositoryNo file exists at the script path.Commit the script at that path, written from the project root.
session profile "<name>": no .revyl/scripts/<script> file and no Library Script named "<script>" existThe script is a name, and neither .revyl/scripts/ nor the Library has a script with it.Add .revyl/scripts/<script>.sh, .py, .js, or .ts, create the Library Script, or correct the name.
session profile "<name>": .revyl/scripts holds more than one file named <script>; keep one.revyl/scripts/ has files with that name and different extensions.Delete or rename all but one of them.
session profile "<name>": <count> Library Scripts are named "<script>"; rename all but oneSeveral Library Scripts have that name.Rename all but one in the Library.
session profile "<name>": Library Script "<script>" uses runtime "<runtime>", which session profiles can't runThe Library Script's runtime isn't one in Script references.Use a Library Script in one of those runtimes, or a script file in the repository.
session profile "<name>": Library Script "<script>" is emptyThe Library Script has no code.Add its code in the Library.
session profile "<name>": script <script> is not executable (chmod +x it)The script file has no executable bit.Run chmod +x on it and commit it.
session profile "<name>": <runtime> scripts need <interpreter>, which isn't installed or isn't on PATHThe interpreter for a named script's runtime is missing.Install it, such as python3 or node, on the machine that runs the CLI.
session profile "<name>": script <script> exited with code <code>The script failed.Run it on your machine as Run the script on your machine shows.
session profile "<name>": script <script> did not finish within 300 secondsThe script ran past its limit.Make the script finish within 300 seconds.
session profile "<name>": REVYL_LAUNCH_ENV_FILE line 3: key "API_URL" appears twiceAn output file broke a rule in File formats or Platform rules and limits. The message names the file, the line, and the rule.Fix what the script writes on that line.
session profile "<name>": its deep link failed to openThe device couldn't open the profile's deep link, so the CLI stopped the session.Check that the app handles the link, as Auth bypass deep links describes.
session profile "<name>": Launch configuration ${<key>} changed after this session started, so its deep link would no longer match the session's launch environment; start a new session to use the new valueA launch configuration that fills both the deep link and the session's launch environment changed while the session ran, so the deep link would no longer match. The message names each changed key.Stop the session with revyl dev stop and start a new one.
session profile "<name>": Launch variable "<key>" could not be loaded. Re-save or remove it, then try again.Revyl couldn't read the stored value of a launch configuration the deep link uses.Re-save or remove it in the Library, then start the session again or run revyl dev auth refresh.
session profile "<name>": the Revyl backend started the session without it, so the session was stoppedThe Revyl API started the session without the profile, so the CLI stopped it.Start the session again.
--cookies-file needs a newer Revyl backendThe Revyl API the CLI uses doesn't take cookies without a script on this command.Start without --cookies-file until the API supports it.
--cookies-file: is not Playwright storage state (at cookies[0].domain)The file broke a rule in File formats; the message names the field.Fix that field, here by adding the cookie's domain.
--cookies-file can't apply inside a computer; pass --computer noneThe start runs inside a computer, where no session profile applies.Pass --computer none to start outside the computer.

On this page