Revyl Documentation

Runtime

Mac computers

Start a Mac computer in the cloud, watch and control its desktop, and run commands on it.

Mac computers are available on request: contact support@revyl.ai. Organizations on a paid plan, Pro included, already have them. They bill at $0.05 per minute; see Pricing.

A Mac computer is a macOS computer in the cloud that an agent or a person starts, uses, and stops. Its desktop streams to your browser while it runs. You run commands and work with files on it from the CLI, and you can run Web and iOS apps inside it as app sessions. Revyl keeps the steps and app session reports, along with available recordings.

To run a private GitHub Actions job on a single-use Revyl Mac, see GitHub Actions on Mac computers.

Plan requirement

Mac computers are available on request. Contact support@revyl.ai and we'll set up access for your organization. Organizations on a paid plan, Pro included, already have them, with nothing to turn on. Once your organization has access, Start session offers Computer (macOS), and GitHub Actions jobs with runs-on: revyl-macos can get a Mac.

Get help. Contact support@revyl.ai or use in-app support.

Start a computer

From the dashboard:

  1. Open Sessions and click Start session.
  2. Pick Computer (macOS).
  3. Click Start session. The computer's page opens while it starts.

The page can open before the desktop is ready. The desktop goes live after its first frame; if a screen request returns screen_starting (or screen_unavailable with reason: "screen_starting"), treat it as transient and retry after the Retry-After header.

The Start session popover with Platform set to Computer (macOS) and a Start session button
Start session with Computer (macOS) as the platform.

If you start a macOS computer from a Web or iOS app's page, Revyl can also start that app as an app session inside the computer once it's running. Computers appear in Sessions as Mac session.

From the CLI:

revyl computer create --os macos --wait --json

The response includes the computer's ID, which the other revyl computer commands take. --wait returns once the computer is running; without it, create returns while it's still starting. Starting one needs your organization's compute credits and a free device slot.

Watch and control the desktop

While the computer runs, its page shows the desktop live. It's view only until you take control:

  1. Click the screen. The page shows You're in control.
  2. Use your mouse and keyboard on the computer.
  3. Click Release, or click outside the screen, to stop.

One person controls a computer at a time, and control ends after two minutes without input. Only people with the Owner, Admin, or Member role can take control. After the computer stops, its page plays the recording of the desktop when one was saved.

A running Mac session with its live desktop on the left and empty App sessions and Steps sections in the Activity tab on the right
A running computer's live macOS desktop, view only until you click the screen.

Run commands

Use the computer from the CLI with its ID:

revyl computer exec "$COMPUTER_ID" -- git status
revyl computer exec "$COMPUTER_ID" --cwd app --env CI=1 --timeout 45m -- /bin/zsh -lc 'set -o pipefail; xcodebuild test -scheme App 2>&1 | tail -n 200'
revyl computer files write "$COMPUTER_ID" notes.txt --from notes.txt
revyl computer files read "$COMPUTER_ID" notes.txt > notes.txt
revyl computer process list "$COMPUTER_ID" --json
revyl computer get "$COMPUTER_ID"

While it runs, the Connect section of the Info tab has commands for that computer, ready to copy. exec runs a program with its arguments, not a shell line; for a shell line, run /bin/zsh -lc '…' as above. --cwd sets the working directory and --env NAME=VALUE (or --env NAME, which copies a local variable without printing it) sets environment variables.

A command can run for up to an hour. If the CLI disconnects, the command keeps running: read it later with revyl computer operation get, see it in revyl computer process list, and stop it with revyl computer process terminate. While it runs, file reads and stats still work, so you can follow a log it writes; other execs and file writes wait until it ends. Run long work as one command rather than relying on & or nohup processes to outlive it. See the command reference for the commands, limits, and exit codes.

Operation API

Exec, file and process operations share POST /api/v1/computer-runs/{computer_session_id}/operations. The body contains computer_session_id, a unique request_id, and a command object. Authentication and same-organization access are required.

Command text uses padded URL-safe base64 so ordinary shell syntax is not treated as an injection attempt by the network edge. Each argv_b64 entry encodes one UTF-8 argument; path_b64 encodes a UTF-8 workspace-relative path; the optional cwd_b64 encodes the working directory and env_b64 maps each variable name to its encoded value. For example, the command object for /bin/cat state/x.json is:

{
  "kind": "exec",
  "argv_b64": ["L2Jpbi9jYXQ=", "c3RhdGUveC5qc29u"]
}

File read, write and stat use path_b64. File-write data and exec stdin are base64 bytes. Standard base64 is also accepted. The server validates the decoded values against the same limits below. Process list, inspect and terminate use their existing limit or run-owned handle fields and contain no command text. Exec's timeout_ms accepts up to 3,600,000. Send Prefer: respond-async so a long command answers 202 and is read later at GET /api/v1/computer-runs/{computer_session_id}/operations/{operation_id}. A computer whose host hasn't been updated for working directories, environment variables or timeouts over five minutes refuses those with exec_options_unsupported (HTTP 409) and runs nothing.

Plain argv and path fields are rejected with HTTP 422 and a client-upgrade message. Use an updated CLI or SDK; there is no plaintext fallback. An HTTP 403 with text/html, a nonempty cf-ray header, and a body that is not valid JSON is reported as an edge block, not a reason to sign in again. Encoding is not encryption and does not replace authentication or authorization.

Command user and home directory

Commands run as the computer account, not root. Each exec starts in /Users/computer/workspace with HOME set to that directory. Relative file paths start there too, so the example above writes /Users/computer/workspace/notes.txt. The workspace's Library/Keychains is a link to the account's login keychains, so an app started from exec, such as Chrome, finds its keychain instead of asking for one.

A Terminal opened on the desktop uses the same account but has the login home /Users/computer; it does not inherit an exec process's environment or working directory. Run cd /Users/computer/workspace in Terminal to use the same files. If a tool stores its configuration under $HOME, run it with HOME=/Users/computer/workspace there to use the exec workspace's configuration. Changing directory alone does not change HOME, and changes made in one exec do not persist into the next.

Administrator access

On macOS the computer account is an administrator, and its password is revyl. When macOS asks for an administrator's name and password, for example to turn on Screen & System Audio Recording, Accessibility, Camera or Microphone for your app in System Settings, or to install a package, enter computer and revyl.

Commands can use sudo with the same password. An exec has no terminal, so pass the password on standard input with sudo -S:

printf 'revyl\n' | revyl computer exec "$COMPUTER_ID" --stdin - -- sudo -S installer -pkg MyApp.pkg -target /

Every computer starts from a fresh copy of the image and is deleted when it stops, so nothing you change as an administrator carries over to another computer.

Run an app inside the computer

Mac computers can host Web and iOS apps.

In the computer's Activity tab, under App sessions, click Start app session and pick an app and a build:

  • A Web app runs in a browser on the computer from a registered deployment URL build, not a managed Web bundle. It runs in Chrome unless you pick Safari, which a Mac computer offers once its image supports it.
  • An iOS app, from one of the app's simulator builds, runs as an app session inside the computer, with its own session page, live stream, and video.

Start app session offers the platforms this computer can run. Hosted Web app sessions don't need separate Web enablement for your organization.

From the CLI, pass the computer's ID:

revyl device start --platform ios --app "$APP_ID" --computer "$COMPUTER_ID" --json
revyl device start --platform web --app "$WEB_APP_ID" --computer "$COMPUTER_ID" --json
revyl device start --platform web --app "$WEB_APP_ID" --computer "$COMPUTER_ID" --browser safari --json
revyl computer hosting "$COMPUTER_ID"    # platforms and browsers it can host now
revyl computer sessions "$COMPUTER_ID"   # app sessions inside it

For a mobile start, the JSON output's computer_session_id names the computer the app session runs inside, or is null for a standalone device.

The app launches with its defaults, so launch variables and test-backed starts aren't available inside a computer. For hosted iOS starts, --device-model "iPhone Air" runs an iPhone Air when the computer's image supports it; otherwise the backend refuses the start. Each app session has its own session ID, live stream, actions, and report, and you stop it with revyl device stop. Stopping an app session leaves the computer running; stopping the computer ends its app sessions. An app session's report shows only the actions Revyl took, and commands you run on the computer can change the app too.

Reports and evidence

A computer's page keeps:

  • Activity: each command, file read, write, or stat, and process action, with its outcome, and the computer's app sessions. Once a recording is available, click a recorded step to jump to that moment.
  • The recording of the desktop, when one was saved, after the computer stops.
  • Info: when the computer was created and when it expires, its ID, and the Connect commands.

Commands show as a shell-quoted program and arguments (up to 200 characters), with the credentials Revyl recognizes replaced by <redacted>, so pass secrets in a file or on stdin rather than as arguments. Command output and stdin aren't included in steps or reports. From the CLI, revyl computer get lists the same steps, and revyl computer report "$COMPUTER_ID" --format json returns a summary without the commands.

To show a computer to someone outside your organization, click Share (Owners, Admins, and Members), enable Share to web, and copy the public link. Anyone with that link can watch the desktop live, view only, while the computer runs, and any saved recording after it stops, plus its details, its steps without command text, and its app sessions.

Stop a computer

Click Stop above the desktop and confirm Stop session. Its app sessions stop too, and its steps and reports are kept. From the CLI:

revyl computer stop "$COMPUTER_ID" --json

Pricing

Mac computers cost $0.05/min. Plans with included credits use those credits first. App sessions hosted inside the computer add no compute charge; only the outer computer bills.

Limits

  • A computer runs for up to two hours from creation. Its Info tab shows its exact expiry.
  • A computer takes one device slot from the same limit your iOS sessions use. Hosted app sessions take no additional slots.
  • exec, files, and process commands time out after 30 seconds by default. Use --timeout for up to an hour on exec and five minutes on the others, bounded by the computer's remaining lifetime.
  • exec accepts at most 64 arguments, 64 environment variables and 16,384 bytes of UTF-8 arguments, stdin, working directory and environment together. It keeps the first 1 MiB of combined stdout and stderr; later output is dropped.
  • File reads accept at most 1 MiB; file writes accept at most 64 KiB.
  • Viewers can watch the desktop and read reports, but can't start, control, run commands on, or stop a computer.

On this page