Architecture
Karate Agent uses a dashboard + worker architecture: a lightweight dashboard server manages browser sessions running in Docker containers.
Components
Dashboard Server
The dashboard server is a single Java process (java -jar karate-agent.jar dashboard). 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
- Create — Dashboard starts a new Docker container with a fresh Chrome instance
- Connect — Client connects via REST API or MCP. In Live mode, the client sends JS. In autonomous mode, the worker drives the LLM loop.
- Execute — JS commands run inside the worker. Results return as structured JSON.
- Complete — Session ends. Container produces: transcript, report, screenshots, optional video recording.
- Cleanup — Container auto-destroys after idle timeout. Session data persists in
karate-agent/.
Design Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Dashboard 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. Dashboard stays simple. |
| File-backed persistence | Session data in karate-agent/ | Survives restarts. No database dependency. |
| VNC proxied through dashboard | noVNC via /sessions/{id}/vnc | Users need only one port open (:4444). |
Deployment Topologies
| Topology | Setup | For |
|---|---|---|
| Solo developer | Dashboard on your laptop | Testing against localhost apps |
| Team server | Dashboard on Mac Mini / EC2 | Shared testing with team dashboard |
| CI-integrated | Dashboard on dedicated infrastructure | Pipeline-submitted jobs |
The same flows, dashboard, and API work at every scale.