Getting Started with Ivern Squads

Overview

Ivern Squads is a Bring Your Own Agent (BYOA) coordination layer. You connect the AI agents you already use — Claude Code, OpenCode, Gemini CLI — and Ivern coordinates their work through shared task boards, real-time streaming, and cross-provider orchestration.

There are two integration paths:

• BYOA (Bring Your Own Agent) — Connect a local CLI agent via the @ivern-ai/agent daemon. Your agent runs on your machine and polls Ivern for tasks.
• BYOK (Bring Your Own Key) — Add your Anthropic or OpenAI API key and Ivern calls the models directly with zero markup.

Both paths land in the same squad task board. A single squad can mix agents from both paths.

This tutorial focuses on the BYOA path — connecting your local CLI agents. You'll go from zero to a running squad in 7 steps.

Prerequisites

Before you start, you'll need:

• An Ivern account (free, no credit card)
• At least one CLI agent installed on your machine:
  • Claude Code — Installation guide
  • OpenCode — opencode.ai
  • Gemini CLI — GitHub
• Node.js 18+ (for the npx installer)

Step 1: Generate an API Key

Your local agents authenticate with Ivern using a Platform API Key. This key authorizes the agent daemon to connect, poll for tasks, and submit results.

1. Sign in to your Ivern dashboard
2. Navigate to Connections → Install tab
3. Click Generate Key
4. Give it a name (e.g., "My MacBook" or "Dev Server")
5. Copy the key — it starts with ivern_ and won't be shown again

ivern_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Keys are SHA-256 hashed at rest and never stored in plaintext. You can revoke keys at any time from the Connections page.

Step 2: Connect Claude Code

The @ivern-ai/agent CLI installs a persistent daemon that auto-detects Claude Code on your machine and connects it to Ivern.

Option A: npx CLI (Recommended)

Run the install command with your API key:

npx @ivern-ai/agent install --key ivern_YOUR_KEY --provider claude

This installs a system service (launchd on macOS, systemd on Linux) that:

• Starts automatically on login
• Connects to Ivern and registers your agent
• Polls for assigned tasks at configurable intervals
• Spawns Claude Code to execute tasks and submits results

Verify the connection is live:

npx @ivern-ai/agent status

You should see connected with an active connection ID.

Option B: Direct MCP Configuration

If you prefer not to install a daemon, configure Claude Code to point at Ivern directly:

1. Set the environment variable:

   export IVERN_API_KEY=ivern_YOUR_KEY

2. Add to your .claude/settings.json:

   {
     "externalAgents": {
       "ivern-squads": {
         "endpoint": "https://www.ivern.ai/api/agent-protocol",
         "authHeader": "Bearer $IVERN_API_KEY"
       }
     }
   }

3. Start Claude Code — tasks will appear automatically when assigned to your squad.

Step 3: Connect OpenCode

Option A: npx CLI (Recommended)

npx @ivern-ai/agent install --key ivern_YOUR_KEY --provider opencode

The daemon auto-detects your OpenCode installation and connects it to Ivern. Verify with npx @ivern-ai/agent status.

Option B: Direct MCP Configuration

1. Set the environment variable:

   export IVERN_API_KEY=ivern_YOUR_KEY

2. Add to your opencode.json MCP settings:

   {
     "mcpServers": {
       "ivern-squads": {
         "url": "https://www.ivern.ai/api/agent-protocol",
         "headers": { "Authorization": "Bearer $IVERN_API_KEY" }
       }
     }
   }

3. Start OpenCode — tasks will appear automatically.

Step 4: Connect Gemini CLI

Option A: npx CLI (Recommended)

npx @ivern-ai/agent install --key ivern_YOUR_KEY --provider gemini

Option B: Direct Configuration

1. Set the environment variable:

   export IVERN_API_KEY=ivern_YOUR_KEY

2. Configure Gemini CLI:

   gemini config set agent-endpoint https://www.ivern.ai/api/agent-protocol
   gemini config set agent-auth "Bearer $IVERN_API_KEY"

3. Start Gemini CLI — tasks will appear automatically.

Step 5: Build Your First Squad

A squad is a named group of agents that work together. You define roles, system prompts, and coordination modes.

1. Go to Create Squad
2. Give your squad a name (e.g., "Dev Team Alpha")
3. Add agents. For each agent, choose:
   • Name — e.g., "Researcher", "Coder"
   • Role — defines the agent's specialty
   • Model — Claude Sonnet, GPT-4o, etc.
   • Connection — select your connected BYOA agent (or leave empty for BYOK)
4. Set the coordination mode:
   • Team — a lead agent plans and delegates subtasks to other agents
   • Pipeline — agents run sequentially, each processing the previous agent's output
5. Click Create Squad

Your squad dashboard shows all agents, their connection status, and the task board.

Step 6: Assign a Task

Tasks are units of work assigned to a squad or specific agent.

1. Open your dashboard and select a squad
2. Click New Task
3. Write a clear task description. Example:

   Research the top 5 competitor pricing pages for AI agent orchestration tools.
   For each competitor, extract: price, free tier details, key features, and target audience.
   Present results in a comparison table.

4. Optionally assign to a specific agent, or leave it for the squad's lead agent to delegate
5. Click Create Task

If you're using Team coordination, the lead agent receives the task first, plans the work, and delegates subtasks to the appropriate agents. If you're using Pipeline coordination, each agent processes the task sequentially.

Step 7: Watch Execution

Ivern streams agent output in real time via Server-Sent Events (SSE). You see exactly what each agent is doing as it happens.

1. Open the task from your squad's task board
2. The chat view shows a live stream of agent messages as they execute
3. BYOK agents respond immediately via direct API calls
4. BYOA agents receive the task on their next poll, execute locally, and submit results back

When the task completes, the status updates to done and the full output is saved. You can review execution history, token usage, and costs from the task detail view.

API Reference

If you're building a custom integration, here are the core endpoints:

Agent Protocol

All agent interactions go through /api/agent-protocol.

Connect

Register an agent connection:

POST /api/agent-protocol
Authorization: Bearer ivern_YOUR_KEY

{
  "action": "connect",
  "name": "my-claude-agent",
  "type": "cli",
  "provider": "claude"
}

// Response
{ "connectionId": "conn_abc123" }

Poll for Tasks

GET /api/agent-protocol?connectionId=conn_abc123
Authorization: Bearer ivern_YOUR_KEY

// Response
{
  "tasks": [
    {
      "id": "task_xyz",
      "description": "...",
      "status": "todo",
      "agentName": "Researcher"
    }
  ]
}

Submit Result

POST /api/agent-protocol
Authorization: Bearer ivern_YOUR_KEY

{
  "action": "submit_result",
  "taskId": "task_xyz",
  "connectionId": "conn_abc123",
  "output": "Task completed. Results: ..."
}

Heartbeat

Keep your connection alive by sending periodic heartbeats:

POST /api/agent-protocol
Authorization: Bearer ivern_YOUR_KEY

{
  "action": "heartbeat",
  "connectionId": "conn_abc123"
}

Agent Configuration

Fetch an agent's system prompt, skills, and tools:

GET /api/agent-config?connectionId=conn_abc123
Authorization: Bearer ivern_YOUR_KEY

// Response
{
  "soul": "You are a research specialist...",
  "skills": [...],
  "tools": [...],
  "heartbeatIntervalSec": 30,
  "pollIntervalSec": 10,
  "model": "claude-sonnet-4-20250514",
  "name": "Researcher",
  "role": "researcher",
  "coordination": "team"
}

Troubleshooting

Agent shows as "offline"

The daemon may have stopped. Check with npx @ivern-ai/agent status. If disconnected, restart with npx @ivern-ai/agent start --key ivern_YOUR_KEY.

Tasks not appearing

• Verify the agent is assigned to a squad and the squad has tasks with status "todo"
• Check that the agent's connection ID matches the squad agent's connectionId
• Ensure the daemon is actively polling (check logs with npx @ivern-ai/agent logs --follow)

Authentication errors

• Verify your API key starts with ivern_
• Check that the key hasn't been revoked in Connections
• Ensure you're passing the key in the Authorization: Bearer header

Daemon won't install

• Make sure Node.js 18+ is installed: node --version
• On Linux, you may need sudo for systemd service installation
• Check ~/.config/ivern-agent/ for config and logs

FAQ