Architecture

Karate Agent uses a grid architecture: a lightweight grid server manages browser sessions running in Docker containers.

Components

Karate Agent Architecture

Grid Server

The grid server is a single Java process (java -jar veriquant.jar grid). It provides:

  • REST API — Session management, job submission, file operations
  • Dashboard — Web UI for managing sessions, viewing live browsers, reviewing reports
  • Reverse Proxy — Routes HTTP and WebSocket traffic to the correct worker container
  • Docker Management — Creates, monitors, and destroys worker containers via Docker socket

Workers (karate-agent)

Each worker is a self-contained Docker container running:

  • JVM with the Karate Agent server (port 5757)
  • Chrome browser
  • Xvfb display server
  • noVNC for live browser viewing (port 6080)

Workers are “fat” — each contains everything needed to run browser automation independently.

Session Lifecycle

  1. Create — Grid server starts a new Docker container with a fresh Chrome instance
  2. Connect — Client connects via REST API or MCP. In Interactive mode, the client sends JS. In autonomous mode, the GridJobRunner drives the LLM loop.
  3. Execute — JS commands run inside the worker. Results return as structured JSON.
  4. Complete — Session ends. Container produces: transcript, report, screenshots, optional video recording.
  5. Cleanup — Container auto-destroys after idle timeout. Session data persists in the data/ directory.

Design Decisions

Decision Choice Rationale
Grid as separate process Not embedded in karate-agent Keeps workers unchanged. ~200MB vs ~1.2GB.
Docker socket mount /var/run/docker.sock Battle-tested pattern. Workers are sibling containers.
Dynamic port mapping docker -P + inspect Works on macOS (Docker Desktop) and Linux.
Fat workers JVM + Chrome per container Each worker is self-contained. Grid stays simple.
File-backed persistence Session data in data/ directory Survives restarts. No database dependency.
VNC proxied through grid noVNC via /sessions/{id}/vnc Users need only one port open (:4444).

Deployment Topologies

Topology Setup For
Solo developer Grid on your laptop Testing against localhost apps
Team server Grid on Mac Mini / EC2 Shared testing with team dashboard
CI-integrated Grid on dedicated infrastructure Pipeline-submitted jobs

The same flows, dashboard, and API work at every scale.