Skip to content
Marriska Docs

How to set up the local agent

The local agent is a long-running process on your machine that takes test dispatches from Marriska over WebSocket and runs them with Playwright locally. It’s the right tool when you want:

  • Tests that need to reach a private network or localhost
  • Faster local feedback while iterating
  • A real browser window you can watch (with --headed)

Steps

Section titled “Steps”

  1. Install the agent and Playwright browsers

    Terminal window
    npm install -g @marriska/agent
    npx playwright install chromium

    Add firefox and webkit if you want to dispatch to those:

    Terminal window
    npx playwright install firefox webkit

    The agent auto-detects which browsers are installed at startup — only the ones it can actually launch are reported as capabilities.

  2. Create an API key

    In Marriska, open Settings → API Keys and click Create API Key. Copy it immediately — you’ll only see it once. See How to create and manage API keys.

  3. Set the API key as an env var

    Terminal window
    # Linux / macOS / WSL
    export MARRISKA_API_KEY=ak_live_...
    

    # Windows PowerShell
    $env:MARRISKA_API_KEY = "ak_live_..."
    

    # Windows CMD
    set MARRISKA_API_KEY=ak_live_...

    Or pass it inline with --api-key on each invocation. (MARRISKA_TOKEN / --token still work as deprecated aliases.)

  4. Start the agent

    Terminal window
    marriska-agent start

    On startup, it lists the browsers it found, opens the WebSocket, and prints Connected to Marriska (Your Org Name) followed by Waiting for executions…. Leave the terminal open.

  5. Switch the Runner to Local mode

    In the web app, open Runner. Each queued run shows a target badge — click it to flip between Cloud and Local. With Local selected, the next run dispatches to your agent instead of Marriska’s cloud runners.

    Step events stream back to the browser the same way they would for a cloud run.

Common flags

Section titled “Common flags”
Terminal window
# Watch the browser window (default is headless)
marriska-agent start --headed


# Run multi-browser tests concurrently instead of sequentially
marriska-agent start --parallel


# Point at a custom WebSocket URL (self-hosted, staging)
marriska-agent start --ws-url wss://staging.example.com/ws/agent

Full flag list: CLI reference → marriska-agent.

Stopping the agent

Section titled “Stopping the agent”

Press Ctrl+C. The agent handles SIGINT and SIGTERM, finishes the current dispatch cleanly, and disconnects.

Reconnecting

Section titled “Reconnecting”

If the WebSocket drops (laptop sleep, network blip), the agent reconnects automatically with exponential backoff up to 30 seconds between attempts. You don’t need to restart it after a brief disconnect: a run in progress keeps going, and the results the agent buffered while it was away are delivered when it is back.

A run waits 90 seconds for its agent. If the agent has not reconnected by then, the run ends Failed, and every test it had not reported fails by name — the one it was running says the last step it reported. The report states what we observed (“your agent stopped answering … and did not reconnect within 90s”) and lists the possible causes; if none of them happened, tell us and quote the run id. When the connection ended on our side — a restart of ours, or an error of ours — the run says so, and its origin is ours, not yours.

Running multiple agents

Section titled “Running multiple agents”

Each agent counts against the agents cap on your plan: Starter 1, Pro 3, Team 5, Enterprise unlimited. To run agents on multiple machines (laptop + CI runner, for instance), generate a separate API key per machine — that way you can revoke one without breaking the others. See API keys.

Troubleshooting

Section titled “Troubleshooting”

”No Playwright browsers installed”

Section titled “”No Playwright browsers installed””

Run npx playwright install chromium (or firefox / webkit). The agent exits with code 1 if it can’t find any browser at startup.

”Missing —api-key or MARRISKA_API_KEY env var”

Section titled “”Missing —api-key or MARRISKA_API_KEY env var””

Set the env var or pass --api-key. Exit code 2 means the agent never got a usable API key.

Agent says “Connected” but the Runner can’t dispatch

Section titled “Agent says “Connected” but the Runner can’t dispatch”
  • Make sure the Runner page is showing the Local badge for the queued run, not Cloud.
  • Confirm the agent and the web session are signed into the same organization (the API key determines the org).
  • Check the agent’s terminal — if it’s printing Cancel requested: for every dispatch, the run is being cancelled before it reaches Playwright.

Dispatched run shows “Agent disconnected”

Section titled “Dispatched run shows “Agent disconnected””

The dashboard surfaces this banner when an active local run loses its WebSocket. The run may still be progressing on the agent host — the event stream just isn’t reaching us. If the agent reconnects within 90 seconds the run carries on. After that the run has ended (see Reconnecting) and stays ended: results the agent sends later do not reopen it, so queue it again once the agent is back.

Section titled “Related”