Skip to main content

Quick Start

1. Prerequisites​

  • Java 21+ on your PATH
  • Docker running (Docker Desktop on macOS/Windows, Docker Engine on Linux)
  • A karate.lic file. Request an evaluation — the license is emailed to you.

2. Download​

The release ZIP is published to GitHub. Browse the latest release and download karate-agent-<version>.zip:

https://github.com/karatelabs/karate-addons/releases

Unzip — it extracts to an unversioned karate-agent/ folder so upgrades are a drop-in jar replacement (see below):

karate-agent/
├── karate-agent.jar
├── karate-agent.json     # config (port, models, maxSessions)
├── start.sh              # macOS / Linux launcher
├── start.bat             # Windows launcher
└── README.md

The version is in the ZIP filename (which you downloaded) and is also surfaced by java -jar karate-agent.jar --version and by the dashboard banner.

3. Place the license​

Drop your karate.lic next to the jar. The dashboard refuses to start without it.

4. (Optional) Set an LLM API key​

Only needed for Autonomous mode. Live mode works without one.

export OPENROUTER_API_KEY=sk-or-...     # for openrouter/* models
# or
export ANTHROPIC_API_KEY=sk-ant-...     # for anthropic/* models

The first model in karate-agent.json is the default for new autonomous jobs.

5. Start​

./start.sh        # macOS / Linux
start.bat         # Windows

Equivalent: java -jar karate-agent.jar from the install directory.

The first run pulls the worker Docker image (~30s). Subsequent starts are immediate. The dashboard validates your license, pulls the worker image, and pings the configured LLM before binding the port.

Open http://localhost:4444.

6. Start a Live Session​

From the dashboard, click New Live Session to start a browser container. Or via curl:

curl -X POST http://localhost:4444/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"mode":"live"}'

The response includes a sessionId. Use it to send commands:

SID={sessionId}

# Create the agent and navigate to a page (first call must define `agent`)
curl -X POST http://localhost:4444/sessions/$SID/proxy \
  -d 'var agent = Agent.create(); agent.go("https://example.com")'

# Discover elements (`agent` persists across proxy calls in the same session)
curl -X POST http://localhost:4444/sessions/$SID/proxy \
  -d 'agent.look()'

# Click a link
curl -X POST http://localhost:4444/sessions/$SID/proxy \
  -d 'agent.act("{a}Learn more", "click")'

7. Watch Live​

In the dashboard, click the session to see the live browser via noVNC.

8. Connect Your LLM Agent​

Via MCP (Claude Code)​

claude mcp add karate http://localhost:4444/mcp

Via REST (any agent)​

The /sessions/{id}/prompt endpoint serves a self-contained API reference your LLM can read:

curl http://localhost:4444/sessions/{sessionId}/prompt

Upgrading​

Drop-in jar replacement — start.sh / start.bat reference karate-agent.jar literally, so the launchers don't need to change. Your karate.lic, karate-agent.json, flows/, and sessions/ are preserved.

# Stop the running dashboard
lsof -ti:4444 | xargs kill 2>/dev/null

# Drop the new jar into your existing install
unzip -j karate-agent-<new-version>.zip karate-agent/karate-agent.jar \
  -d /path/to/karate-agent/

# Restart, verify
cd /path/to/karate-agent && ./start.sh
java -jar karate-agent.jar --version

Always check release notes before upgrading — karate-agent.json schema changes will be called out there.

Checking the running version​

java -jar karate-agent.jar --version    # CLI
curl -s localhost:4444/api/config       # while the dashboard runs

The dashboard banner at startup also prints the version.

Next Steps​

On This Page