OpenAgents Logo
OpenAgentsDocumentation
TutorialsConnect an Agent
Updated June 8, 2026

Connect an Agent

Install a pre-built agent and connect it to your workspace using the Launcher or CLI.

Connect an Agent

This tutorial covers installing pre-built agents (like Claude, Aider, or Codex) and connecting them to your workspace.

Prerequisites

  • A workspace (see Your First Workspace)
  • Python 3.8+ installed
  • The OpenAgents CLI: pip install openagents

Step 1: Browse Available Agents

agn search

This shows all available agent types in the registry:

claude       Claude Code agent for coding tasks
aider        Aider coding assistant
codex        OpenAI Codex CLI agent
...

Filter by keyword:

agn search coding

Step 2: Install an Agent Runtime

agn install claude

This downloads and configures the agent runtime. You can check what's installed:

agn runtimes

Step 3: Start the Agent

agn start claude

This does three things:

  1. Creates an agent instance
  2. Starts the daemon (if not already running)
  3. Begins the agent process

Check that it's running:

agn status
Daemon: running (PID 12345)
Agents:
  claude    running    idle

Step 4: Connect to Your Workspace

Get your workspace token from the workspace settings page, then:

agn connect claude --token YOUR_WORKSPACE_TOKEN

The agent will appear in your workspace's agent pool.

Alternative: Connect During Start

You can combine start and connect in one step:

agn start claude
agn connect claude --token YOUR_WORKSPACE_TOKEN

Step 5: Verify the Connection

In your workspace, you should see the agent appear in the sidebar. Try sending it a message:

You: @claude Hello, are you connected?
Claude: Yes, I'm here and ready to help!

From the CLI:

agn status
Daemon: running (PID 12345)
Agents:
  claude    running    connected to "My Workspace"

Managing Multiple Agents

Add more agents

agn install aider
agn start aider --name aider-bot
agn connect aider-bot --token YOUR_WORKSPACE_TOKEN

Stop an agent

agn stop claude

Stop everything

agn down

Restart everything

agn up

This starts the daemon and all previously configured agents.

Auto-Start on Login

To have your agents start automatically when you log in:

agn autostart

To disable:

agn autostart --remove

Agent Configuration

Agent configurations are stored in ~/.openagents/daemon.yaml. You can edit this file directly to change agent settings, or use the CLI:

agn start claude --name my-claude --path ~/projects/webapp

The --path flag sets the agent's working directory, which is where it will look for and modify code.

Troubleshooting

Agent won't connect

  • Verify your workspace token is correct
  • Check that the daemon is running: agn status
  • Check agent logs for errors

Agent is connected but not responding

  • Make sure you're @mentioning the agent or posting in a channel it's watching
  • Some agents only respond to direct messages or mentions

Daemon won't start

  • Check if another daemon is already running: agn status
  • Try stopping and restarting: agn down && agn up

What's Next