Setup & Deployment

Karate Agent requires only Java 21+ and Docker — both are likely already on your machine. The dashboard is a single jar; everything else lives next to it.

Quick Setup

# 1. Download the latest release
#    https://github.com/karatelabs/karate-addons/releases
unzip karate-agent-<version>.zip   # extracts to ./karate-agent/
cd karate-agent

# 2. Place your karate.lic in this directory
#    Request: https://karatelabs.io/contact-us#demo

# 3. (Autonomous only) export OPENROUTER_API_KEY=... or ANTHROPIC_API_KEY=...

# 4. Start
./start.sh

That's it. One jar, one Docker image, one directory. No microservices, no databases, no message queues. The dashboard validates the license, pre-pulls the worker image, and (if configured) pings the LLM at boot.

Requirements

Component	Requirement
Java	21 or later
Docker	Docker Desktop (macOS/Windows) or Docker Engine (Linux)
Disk	~2GB for the karate-agent Docker image
RAM	~1GB per concurrent browser session
Network	Docker socket access (/var/run/docker.sock)

Configuration — karate-agent.json

The bundled karate-agent.json carries dashboard settings:

{
  "port": 4444,
  "maxSessions": 10,
  "models": [
    "openrouter/anthropic/claude-sonnet-4-6"
  ]
}

Key	Purpose	Default
port	Dashboard HTTP port	4444
maxSessions	Concurrent worker containers allowed	10
models	Allowed LLM models. First entry is the default. BYO LLM.	(empty)

CLI flags (--port, --max-sessions) override the JSON. See Configuration for details.

API Keys

API keys live in environment variables — never in karate-agent.json. Live mode does not need an LLM.

# OpenRouter (recommended — 100+ models)
export OPENROUTER_API_KEY=sk-or-...

# Anthropic (direct)
export ANTHROPIC_API_KEY=sk-ant-...

The dashboard pings the first model at startup and warns if the key is missing or invalid — autonomous jobs will fail until it's set.

Testing Against Localhost

On a developer machine, worker containers reach your local apps via host.docker.internal:

agent.go('http://host.docker.internal:3000')

Run the dashboard alongside your dev server — test your changes before pushing.

Team Server Deployment

For a shared team setup:

1. Run the dashboard on a persistent machine (Mac Mini, EC2 instance, etc.)
2. Share the dashboard URL with the team
3. Point the flows/ directory at a git repository for collaboration
4. Configure LLM credentials centrally (env vars on the host)

# Custom data directory + env keys
KARATE_AGENT_HOME=/opt/karate-agent \
  OPENROUTER_API_KEY=sk-or-... \
  java -jar /opt/karate-agent/karate-agent.jar

DevOps/admin: install the dashboard as a systemd unit (Linux), launchd plist (macOS), or a service-managed process on AWS. Use KARATE_AGENT_HOME to point the jar at a persistent install directory.

CI/CD Integration

The REST API integrates with any pipeline that can run curl:

# GitHub Actions
- name: Run browser tests
  run: |
    JOB=$(curl -s -X POST $DASHBOARD_URL/api/sessions \
      -H "Content-Type: application/json" \
      -d '{"mode":"auto","prompt":"Run smoke test","flowFiles":["e2e/smoke.js"]}')
    JOB_ID=$(echo $JOB | jq -r .id)
    while true; do
      STATE=$(curl -s $DASHBOARD_URL/api/sessions/$JOB_ID | jq -r .state)
      [ "$STATE" = "stopped" ] && break
      sleep 10
    done

Upgrading

The ZIP extracts to an unversioned karate-agent/ folder by design. Upgrades are a drop-in jar replacement:

lsof -ti:4444 | xargs kill 2>/dev/null
unzip -j karate-agent-<new-version>.zip karate-agent/karate-agent.jar \
  -d /path/to/karate-agent/
cd /path/to/karate-agent && ./start.sh
java -jar karate-agent.jar --version

karate.lic, karate-agent.json, flows/, and sessions/ are preserved. Check release notes for karate-agent.json schema changes before upgrading.

For team servers running under systemd / launchd, drop the jar in, then restart the service unit.

Session Recording

Enable video recording for audit trails. Recordings are H.264 at 8fps with seeking support. Stored alongside session data.

Data Persistence

Everything lives in one self-contained directory:

karate-agent/                  ← cd here to run
├── karate-agent.jar           ← the binary
├── karate-agent.json          ← configuration
├── karate.lic                 ← license file
├── start.sh / start.bat       ← launchers
├── sessions/
│   ├── abc123/
│   │   ├── report.html
│   │   ├── transcript.md
│   │   └── screenshots/
│   └── def456/
│       └── ...
└── flows/
    ├── login.js
    └── hints.md

This directory survives dashboard restarts. Portable — tar it up and move to another machine. Back it up as needed.