Configure Agents

Agents are the bridge between the IAS Hub 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/agent.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: The local runtime will only claim jobs for repos that are explicitly mapped. This ensures you always control which repos an agent can operate on.

Starting the Local Runtime

Start the local agent runtime with:

ias start

You will see output like:

[ias] Starting...
[ias] Config: /Users/you/.ias/agent.json
[ias] Runtime bound to workspace acme-eng
[ias] Tip: press Ctrl+C to stop. Use `ias start --daemon` for background mode.

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

Background mode (daemon)

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

ias start --daemon

Manage the daemon with:

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

Task types

The local runtime handles these task types:

Running multiple agents

You can run multiple agents for different scenarios:

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

Each runtime 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 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 status          # Check if daemon is running
ias logs            # View recent agent output

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