Skip to content

Agent Gateway

The Agent Gateway connects external AI agent frameworks to Glassy, letting you dispatch tasks and share MCP tools from one central workspace.

Overview

The Agent Gateway provides a pluggable adapter system that bridges Glassy with local and cloud-based AI agent frameworks. Each adapter implements a common interface (getStatus, sendTask, getSessions, getConfigSnippet, healthCheck) so you can manage all your agents from a single UI.

Supported Frameworks

Framework Type Default Endpoint Session Continuity
OpenClaw Local http://127.0.0.1:18789 user field in chat completions
Hermes Local http://127.0.0.1:8642 X-Hermes-Session-Key header
Antigravity Cloud Google Gemini API Stateless (no sessions)

Enabling the Agent Gateway

The Agent Gateway is behind a feature flag and disabled by default.

Server-side

Set in your .env:

ENABLE_AGENT_GATEWAY=true

Client-side

Set in your .env:

VITE_ENABLE_AGENT_GATEWAY=true

Both flags must be enabled for full functionality. The server flag mounts the API routes at /api/agents; the client flag shows the sidebar item and settings section.

Using the Agent Gateway

Adding an Agent Connection

  1. Navigate to Settings → Agent connections (or click Add Agent in the Agent Gateway view).
  2. Select the framework type (OpenClaw, Hermes, or Antigravity).
  3. Enter a label for the connection.
  4. For local agents (OpenClaw, Hermes), enter the base URL (defaults are pre-filled).
  5. For Antigravity, enter your Google API key.
  6. Optionally provide a bearer token for authentication.
  7. Click Add Connection.

The gateway will automatically detect if the framework is running on your machine.

Dispatching Tasks

  1. Open the Agent Gateway from the sidebar.
  2. Click Dispatch on any connected agent card.
  3. Type your task in the dispatch panel (up to 10,000 characters).
  4. Press Ctrl+Enter (or Cmd+Enter on macOS) to dispatch, or click the Dispatch button.
  5. The response will appear in the panel and be logged to the activity feed.

Viewing Activity

The activity feed at the bottom of the Agent Gateway view shows recent dispatches, errors, and connection events. You can filter by action type and load more entries with pagination.

MCP Config Snippets

Each agent connection can generate an MCP config snippet that configures the agent to use Glassy's MCP server. Click MCP Config on any agent row in Settings to view and copy the snippet.

The snippet includes:

  • MCP server URL and authentication header
  • Tool filter (where supported) to limit which Glassy tools the agent can access
  • Framework-specific settings (e.g., enabling the chat completions endpoint for OpenClaw, API server for Hermes)

Security

  • SSRF Protection: Local agent URLs are validated against a localhost allowlist (localhost, 127.0.0.1, ::1, host.docker.internal). External URLs are rejected.
  • CLI Safety: Hermes CLI fallback uses execFile with an args array (not exec), preventing command injection.
  • Rate Limiting: 30 dispatches per minute, 12 status polls per minute per user.
  • Activity Logging: All dispatches and errors are logged to the agent_activity table with 30-day retention. MCP keys and auth tokens are never logged.
  • Token Storage: Config tokens are stored locally in the Glassy database. For Clear (self-hosted) instances, this is on your own machine.
  • User Isolation: On hosted (multi-user) instances, all agent connections are scoped by user_id. Users can only see, edit, delete, or dispatch to their own agents. Activity logs are scoped via JOIN on agent_connections.user_id.
  • SaaS Restrictions: On SaaS instances, local-only agent frameworks (OpenClaw, Hermes) are hidden from the framework selector. Only Antigravity (cloud, Google Gemini API) is available. The agent discovery banner is suppressed. Ollama "local" connection type is also hidden — only "cloud" (ollama.com) is offered.

API Reference

All endpoints are mounted at /api/agents and require authentication.

Method Path Description
GET /api/agents List all agent connections with status
POST /api/agents Create a new agent connection
GET /api/agents/:id Get single agent status
PUT /api/agents/:id Update an agent connection
DELETE /api/agents/:id Delete an agent connection
POST /api/agents/:id/task Dispatch a task to an agent
GET /api/agents/:id/sessions List agent sessions
GET /api/agents/:id/config Get MCP config snippet
GET /api/agents/activity List recent activity
GET /api/agents/discover Discover local agent frameworks

Troubleshooting

Agent shows "Offline"

  • Ensure the agent framework is running on your machine.
  • Check that the base URL is correct (must be a localhost address).
  • Verify any required authentication tokens are set.

Agent shows "Setup needed"

  • OpenClaw: Enable the chat completions endpoint in openclaw.json: gateway.http.endpoints.chatCompletions.enabled: true
  • Hermes: Enable the API server by setting API_SERVER_ENABLED=true in your Hermes .env file. Without the API server, tasks will fall back to the Hermes CLI.

"Hermes CLI not found"

Install the Hermes CLI tool or enable the Hermes API server for task dispatch.

MCP key not found

Generate an MCP key in Settings → Knowledge Base → MCP Server before configuring agents. The MCP key is required for agents to access Glassy tools.