Skip to main content

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​

ComponentRequirement
Java21 or later
DockerDocker Desktop (macOS/Windows) or Docker Engine (Linux)
Disk~2GB for the karate-agent Docker image
RAM~1GB per concurrent browser session
NetworkDocker 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"
  ]
}
KeyPurposeDefault
portDashboard HTTP port4444
maxSessionsConcurrent worker containers allowed10
modelsAllowed 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.

On This Page