Skip to main content

Setup & Deployment

Karate Agent requires only Java 21+ and Docker — tools already present on most developer machines.

Quick Setup​

# 1. Create directory, download jar
mkdir karate-agent && cd karate-agent
curl -L -o karate-agent.jar https://releases.karatelabs.io/karate-agent/latest/karate-agent.jar

# 2. Run setup (checks Java, Docker, creates dirs, pulls image)
java -jar karate-agent.jar setup

# 3. Start the dashboard
./start.sh
# or: java -jar karate-agent.jar dashboard --port 4444

That's it. One jar, one Docker image, one directory. No microservices, no databases, no message queues.

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)

LLM Configuration (for Autonomous Mode)​

Set environment variables before starting the dashboard:

# OpenRouter (recommended — 100+ models)
export KARATE_AGENT_MODEL=openrouter/anthropic/claude-sonnet-4-6
export OPENROUTER_API_KEY=sk-or-...

# Anthropic (direct)
export KARATE_AGENT_MODEL=anthropic/claude-haiku-4-5
export ANTHROPIC_API_KEY=sk-ant-...

# Ollama (local — no API key, no cloud)
export KARATE_AGENT_MODEL=ollama/gemma3
# Ensure Ollama is running: ollama serve

Live mode does not require an LLM on the dashboard — your client-side agent provides the intelligence.

Testing Against Localhost​

On a developer machine, worker containers can 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
# Start with custom data directory
KARATE_AGENT_HOME=/opt/karate-agent \
  java -jar karate-agent.jar dashboard --port 4444

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/jobs \
      -H "Content-Type: application/json" \
      -d '{"prompt":"Run smoke test", "flowFiles":["e2e/smoke.js"]}')
    JOB_ID=$(echo $JOB | jq -r .sessionId)
    while true; do
      STATE=$(curl -s $DASHBOARD_URL/api/jobs/$JOB_ID | jq -r .state)
      [ "$STATE" = "completed" ] && break
      [ "$STATE" = "failed" ] && exit 1
      sleep 10
    done

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.lic                 ← license file
├── start.sh                   ← launch script (created by setup)
├── 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