Configure Agents

Agents are the bridge between the IAS Console and your code. They run on your machine, poll for tasks from the Console, execute them locally against your Git checkout, and report results back. Without a running agent, tasks sit in "pending" indefinitely.

How agents work

An IAS agent follows a straightforward loop:

1. Connect -- The agent authenticates with the Console backend via the control plane.
2. Heartbeat -- It sends periodic heartbeats so the Console knows the agent is online and healthy.
3. Poll -- It watches for tasks assigned to its mapped repositories.
4. Claim -- When a task appears, the agent claims it from the queue.
5. Execute -- The task runs locally: reading files, writing code, running commands, and producing Git commits.
6. Report -- Results are sent back to the Console: commit SHAs, PR URLs, changed file paths, and execution logs.

This loop repeats until you stop the agent. The Console tracks agent availability and routes tasks accordingly.

Prerequisites

Before starting an agent, make sure you have:

• IAS CLI installed -- npm i -g @lucentivelabs/ias
• Authenticated -- run ias auth login to sign in via your browser
• At least one repo linked -- run ias repo link /path/to/your/repo (see Add a repository)

Verify your setup at any time:

ias doctor

This checks configuration, authentication status, control plane connectivity, and repo mappings.

Configuration

Agent configuration lives at ~/.ias/worker.json. The easiest way to set it up is the guided flow:

ias setup

This walks you through configuring the control plane connection and authentication without manual JSON editing. You can also edit the file directly.

Control plane settings

The controlPlane section connects your agent to the Console:

Repository mappings

The repos.mappings section tells the agent which repositories to watch. Each entry maps a Console repo to a local checkout:

{
  "controlPlane": {
    "convexDeploymentUrl": "https://your-deployment.convex.cloud",
    "consoleAppUrl": "https://app.ias.dev",
    "workspaceSlug": "acme-eng"
  },
  "repos": {
    "mappings": [
      { "repoId": "repos/abc123", "localPath": "/Users/you/code/repo-one" },
      { "repoId": "repos/def456", "localPath": "/Users/you/code/repo-two" }
    ]
  }
}

Safety default: Workers will only claim jobs for repos that are explicitly mapped. This ensures you always control which repos an agent can operate on.

Starting the worker

The worker (setup agent) handles coordination and setup tasks. Start it with:

ias worker start

You will see output like:

[worker] Starting control-plane polling...
[worker] Heartbeat sent. Status: online
[worker] Polling for jobs...

Keep this terminal running while you work. Press Ctrl+C to stop. The Console will show the worker as offline after the heartbeat TTL (approximately 60 seconds).

Background mode (daemon)

On macOS and Windows, you can run the worker as a background service:

ias worker start --daemon

Manage the daemon with:

ias worker status    # Check if the agent is running
ias worker logs      # View recent output
ias worker stop      # Stop the daemon

Task types

The worker handles these task types:

Two task types -- work and pr_review -- are not handled by the worker. They are executed by the hybrid runner, described below.

The hybrid runner

The hybrid runner is the AI execution engine that performs actual coding work and PR reviews. It connects to your chosen AI runtime (Claude Code, Codex CLI, or Gemini CLI) and executes tasks that require code generation, modification, or review.

Starting both together

The easiest way to run the full agent stack is:

ias agent start

This starts both the worker (setup agent) and the hybrid runner (work agent) in a single process. If the hybrid runner is not yet installed in the repo (e.g., before bootstrap with a hybrid or full profile), the worker runs alone and the runner starts automatically once IAS is installed.

Running the runner independently

You can also start the runner on its own:

ias runner start

This is useful when you want separate processes for the worker and runner, or when you want to run the runner against a specific repo.

Runner task types

Running multiple agents

You can run multiple agents for different scenarios:

• Different repos on different machines -- Each machine has its own worker.json with the relevant repo mappings.
• Same repo on multiple machines -- For load balancing or redundancy. Multiple workers can claim different jobs from the same queue.
• One worker per repo -- For fine-grained control over which agent handles which repository.

Each worker should have its own config with the appropriate repos.mappings.

Monitoring agents

The Console provides real-time visibility into agent status:

1. Open the Console.
2. Check the Agents indicator in the top navigation bar for a quick status overview.
3. Go to Settings and select the Agents tab for detailed information about each connected agent.

Each agent shows as Online (heartbeat received within the last ~60 seconds) or Offline.

You can also check agent status from the CLI:

ias worker status

Troubleshooting

If your agent is not showing as online in the Console, check these common issues:

Useful diagnostic commands

ias doctor          # Full setup diagnostic
ias auth status     # Check authentication state
ias worker status   # Check if daemon is running
ias worker logs     # View recent agent output

Next step: With agents running, you are ready to create goals and start building.