Adapters Overview

Adapters are the bridge between Vagaris's orchestration layer and agent runtimes. Each adapter knows how to invoke a specific type of AI agent and capture its results.

Canonical reference. This page is the practical guide. The full as-built description of the execution seam — transports, sessions, event mapping, cancellation, authority boundaries, failure handling, and known deficits — lives in the repo at docs/specs/2026-08-02-agent-execution-adapter-layer.md ("The Agent Execution Adapter Layer"). Where the two disagree, that document wins.

How Adapters Work

When a heartbeat fires, Vagaris:

1. Looks up the agent's adapterType and adapterConfig
2. Calls the adapter's execute() function with the execution context
3. The adapter spawns or calls the agent runtime
4. The adapter captures stdout, parses usage/cost data, and returns a structured result

Built-in Adapters

Adapter	Type Key	Description
Claude Local	claude_local	Runs Claude Code CLI locally
Codex Local	codex_local	Runs OpenAI Codex CLI locally
Gemini Local	gemini_local	Runs Gemini CLI locally, resuming sessions across heartbeats via --resume. Note: key-free gemini-cli auth is no longer available for individual Google accounts, so this adapter needs an API key or Vertex/GCP project
ACPX Local	acpx_local	Runs an agent over Agent Client Protocol via ACPX (targets Claude, Codex, or a custom ACP server command). Requires Node >=22.12.0
Grok Build Local	grok_local	Runs the native Grok Build CLI locally, with resumable sessions via --resume and skills staged into Grok's native discovery paths (Agents.md, .claude/skills)
OpenCode Local	opencode_local	Runs OpenCode CLI locally (multi-provider provider/model)
Cursor	cursor	Runs Cursor in background mode
Cursor Cloud	cursor_cloud	Runs Cursor Cloud Agents through the official Cursor SDK — durable remote sessions across heartbeats; requires repoUrl
Pi Local	pi_local	Runs an embedded Pi agent locally
Hermes Local	hermes_local	Runs Hermes CLI locally (hermes-paperclip-adapter)
OpenClaw Gateway	openclaw_gateway	Connects to an OpenClaw gateway endpoint
Process	process	Executes arbitrary shell commands
HTTP	http	Sends webhooks to external agents

External (plugin) adapters

These adapters ship as standalone npm packages and are installed via the plugin system:

Adapter	Package	Type Key	Description
Droid Local	@henkey/droid-paperclip-adapter	droid_local	Runs Factory Droid locally

External Adapters

You can build and distribute adapters as standalone packages — no changes to Vagaris's source code required. External adapters are loaded at startup via the plugin system.

# Install from npm via API
curl -X POST http://localhost:3102/api/adapters \
  -d '{"packageName": "my-vagris-adapter"}'

# Or link from a local directory
curl -X POST http://localhost:3102/api/adapters \
  -d '{"localPath": "/home/user/my-adapter"}'

See External Adapters for the full guide.

Adapter Architecture

Each adapter is a package with modules consumed by three registries:

my-adapter/
  src/
    index.ts            # Shared metadata (type, label, models)
    server/
      execute.ts        # Core execution logic
      parse.ts          # Output parsing
      test.ts           # Environment diagnostics
    ui-parser.ts        # Self-contained UI transcript parser (for external adapters)
    cli/
      format-event.ts   # Terminal output when the CLI streams a run

Registry	What it does	Source
Server	Executes agents, captures results	createServerAdapter() from package root
UI	Renders run transcripts, provides config forms	ui-parser.js (dynamic) or static import (built-in)
CLI	Formats terminal output for live watching	Static import

Choosing an Adapter

• Need a coding agent? Use claude_local, codex_local, opencode_local, hermes_local, or install droid_local as an external plugin
• Need to run a script or command? Use process
• Need to call an external service? Use http
• Need something custom? Create your own adapter or build an external adapter plugin

UI Parser Contract

External adapters can ship a self-contained UI parser that tells the Vagaris web UI how to render their stdout. Without it, the UI uses a generic shell parser. See the UI Parser Contract for details.