Improve homepage, use cases, features, and templates

agent-os/connect-your-os.mdx

@@ -3,10 +3,63 @@ title: "Connect Your AgentOS"
 description: "Connect your AgentOS to the control plane for monitoring and management."
 ---
 
-## Connect Your AgentOS
+Connect a local or deployed AgentOS runtime to monitor and manage its agents, teams, and workflows from the [AgentOS Control Plane](https://os.agno.com).
 
-1. Open [os.agno.com](https://os.agno.com) and sign in
-2. Click **"Add new OS"**
+## Before You Connect
+
+| Runtime | Requirements |
+|---------|--------------|
+| Local | AgentOS running on your machine and reachable from your browser, usually at `http://localhost:7777` or `http://localhost:8000` |
+| Live | AgentOS available at a browser-reachable HTTPS URL with [Security & Auth](/agent-os/security/overview) configured for production traffic |
+
+<Note>
+Live AgentOS connections require a paid plan.
+</Note>
+
+## Connect the Runtime
+
+<Steps>
+  <Step title="Open the Control Plane">
+    Open [os.agno.com](https://os.agno.com), sign in, and click **CONNECT OS**.
+  </Step>
+
+  <Step title="Enter the connection details">
+    Choose **Local** or **Live**, then complete the form:
+
+    | Field | Value |
+    |-------|-------|
+    | **Environment** | **Local** for a runtime on your machine. **Live** for a browser-reachable HTTPS endpoint. |
+    | **Endpoint URL** | The AgentOS base URL, such as `http://localhost:7777`. Do not include `/docs` or another route. |
+    | **Name** | The label shown in the runtime selector, such as `Development`. |
+    | **Tags** | Optional labels such as `dev`, `stg`, or `prd`. |
+  </Step>
+
+  <Step title="Connect the runtime">
+    Click **CONNECT**. For Control Plane-managed JWT authorization, enable **Token-Based Authorization (JWT)** before connecting. The Control Plane creates a signing key pair and shows the public verification key.
+  </Step>
+
+  <Step title="Configure Control Plane-managed JWT authorization">
+    If you enabled **Token-Based Authorization (JWT)**, copy the generated public key into `JWT_VERIFICATION_KEY`, run AgentOS with `authorization=True`, then restart or redeploy the runtime.
+
+    ```bash
+    export JWT_VERIFICATION_KEY="your-public-key"
+    ```
+
+    The Control Plane keeps the matching private signing key and uses it to issue scoped tokens. See the [Authorization quickstart](/agent-os/security/authorization/quickstart) for the complete runtime configuration.
+
+    Keep your existing credential setup when the runtime already uses `OS_SECURITY_KEY` or self-managed JWTs. See [Security & Auth](/agent-os/security/overview) for the available authentication paths.
+  </Step>
+
+  <Step title="Verify the connection">
+    Select the runtime again after it restarts.
+
+    | Check | Expected |
+    |-------|----------|
+    | Connection | A green indicator appears beside the runtime name. |
+    | Components | Registered agents, teams, and workflows appear on Home. |
+    | Test run | Select a component in Chat and start a new session. |
+  </Step>
+</Steps>
 
 <Frame>
   <video
@@ -21,21 +74,14 @@ description: "Connect your AgentOS to the control plane for monitoring and manag
   </video>
 </Frame>
 
-## Configure Connection
-
-| Field | Description |
-|-------|-------------|
-| **Environment** | Local (`http://localhost:7777`) or Live (your HTTPS URL) |
-| **Endpoint URL** | Where your AgentOS is running |
-| **OS Name** | A descriptive name, e.g. "Development OS" |
-| **Tags** | Optional. Organize with labels like `dev`, `stg`, `prd` |
-
-Click **"CONNECT"**. If successful, your OS appears in the dashboard.
+<Tip>
+If your browser blocks a local connection, allow local-network access for `os.agno.com`. See [AgentOS Connection Issues](/faq/agentos-connection) for browser-specific steps.
+</Tip>
 
-## Verify Connection
+## Next Steps
 
-| Indicator | Expected |
-|-----------|----------|
-| Status | "Running" |
-| Features | Chat, Knowledge, Memory, Sessions accessible |
-| Agents | Configured agents appear in the chat interface |
+| Task | Guide |
+|------|-------|
+| Run a component and inspect its session | [AgentOS Control Plane](/agent-os/control-plane) |
+| Configure authentication and permissions | [Security & Auth](/agent-os/security/overview) |
+| Call the runtime from an application | [Using the AgentOS API](/agent-os/using-the-api) |