Skip to main content

​
Overview

Connecting your AgentOS is the critical first step to using the AgentOS Control Plane. This process establishes a connection between your running AgentOS instance and the Control Plane, allowing you to manage, monitor, and interact with your agents through the browser.
Prerequisites: You need a running AgentOS instance before you can connect it to the Control Plane. If you haven’t created one yet, check out our Creating Your First OS guide.
See the AgentOS Control Plane documentation for more information about the Control Plane.

​
Step-by-Step Connection Process

​
1. Access the Connection Dialog

In the Agno platform:
  1. Click on the team/organization dropdown in the top navigation bar
  2. Click the ”+” (plus) button next to “Add new OS”
  3. The “Connect your AgentOS” dialog will open

​
2. Choose Your Environment

Select “Local” for development or “Live” for production:
  • Local: Connects to an AgentOS running on your local machine
  • Live: Connects to a production AgentOS running on your infrastructure
Live AgentOS connections require a PRO subscription.

​
3. Configure Connection Settings

​
Endpoint URL

  • Default Local: http://localhost:7777
  • Custom Local: You can change the port if your AgentOS runs on a different port
  • Live: Enter your production HTTPS URL
Make sure your AgentOS is actually running on the specified endpoint before attempting to connect.

​
OS Name

Give your AgentOS a descriptive name:
  • Use clear, descriptive names like “Development OS” or “Production Chat Bot”
  • This name will appear in your OS list and help you identify different instances

​
Tags (Optional)

Add tags to organize your AgentOS instances:
  • Examples: development, production, chatbot, research
  • Tags help filter and organize multiple OS instances
  • Click the ”+” button to add multiple tags

​
4. Test and Connect

  1. Click the “CONNECT” button
  2. The platform will attempt to establish a connection to your AgentOS
  3. If successful, you’ll see your new OS in the organization dashboard

​
Verifying Your Connection

Once connected, you should see:
  1. OS Status: “Running” indicator in the platform
  2. Available Features: Chat, Knowledge, Memory, Sessions, etc. should be accessible
  3. Agent List: Your configured agents should appear in the chat interface

​
Securing Your Connection

Protect your AgentOS APIs and Control Plane access with bearer-token authentication. Security keys provide essential protection for both development and production environments. Key Features:
  • Generate unique security keys per AgentOS instance
  • Rotate keys easily through the organization settings
  • Configure bearer-token authentication on your server
For complete security setup instructions, including environment configuration and best practices, see the Security Key documentation.

​
Managing Connected OS Instances

​
Switching Between OS Instances

  1. Use the dropdown in the top navigation bar
  2. Select the OS instance you want to work with
  3. All platform features will now connect to the selected OS

​
Disconnecting an OS

  1. Go to the organization settings
  2. Find the OS in your list
  3. Click the delete option
Disconnecting an OS doesn’t stop the AgentOS instance - it only removes it from the platform interface.

​
Next Steps

Once your AgentOS is successfully connected:

Explore the Chat Interface

Start having conversations with your connected agents

Manage Knowledge

Upload and organize your knowledge bases

Monitor Sessions

Track and analyze your agent interactions
⌘I