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 → Security → 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 token as an env var

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

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

    # Windows CMD
    set MARRISKA_TOKEN=ak_live_...

    Or pass it inline with --token on each invocation.

  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.

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 —token or MARRISKA_TOKEN env var”

Section titled “”Missing —token or MARRISKA_TOKEN env var””

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

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 might still be progressing on the agent host — the event stream just isn’t reaching the cloud. Restart the agent and the run will resume reporting on the next dispatch.

Section titled “Related”