grix-connector

grix-connector

A command-line daemon that connects your local AI coding agents to the Grix platform.

What is Grix?

Grix is an AI Agent scheduling platform. It lets you manage and interact with multiple AI coding agents through a unified chat interface. Register at grix.im to get started.

Get the Client

After installing grix-connector, download the Grix client from grix.im to chat with your agents. Clients are available for iOS, Android, macOS, Windows, and Linux.

Supported Agents

Set client_type in your config to one of the values below. Each client_type maps to a built-in adapter and CLI command — you only need the corresponding CLI installed locally.

client_type	Agent	Adapter	Required CLI
claude	Claude Code (Anthropic)	claude	claude
codex	Codex (OpenAI)	codex	codex
gemini	Gemini (Google)	acp	gemini
qwen	Qwen (Alibaba)	acp	qwen
copilot	GitHub Copilot	acp	copilot or gh
kiro	Kiro	acp	kiro-cli
reasonix	Reasonix	acp	reasonix
cursor	Cursor Agent	cursor	agent
codewhale	CodeWhale	codewhale	codewhale
opencode	OpenCode	opencode	opencode
pi	Pi	pi	pi
openhuman	OpenHuman	openhuman	openhuman-core
agy	Agy (Antigravity)	agy	agy
hermes	Hermes	external	hermes

The ACP adapter (Agent Client Protocol over JSON-RPC) backs Gemini, Qwen, Copilot, Kiro and Reasonix. Hermes is an external agent maintained in a separate project — see grix-hermes-python for setup.

You need to have the corresponding CLI tool installed locally before connecting an agent.

Install

npm install -g grix-connector

Requires Node.js >= 18.

On Windows, grix-connector uses the built-in Task Scheduler with a hidden WScript launcher (no extra dependency required).

Quick Start

1. Register a Grix account

Go to grix.im, sign up and get your API key.

2. Create agent config

Create ~/.grix/config/agents.json. Choose the ws_url for your region — the two regions use different WebSocket domains:

• China mainland: wss://grix.dhf.pub/v1/agent-api/ws
• Global: wss://ws.grix.im/v1/agent-api/ws

China mainland example:

{
  "agents": [
    {
      "name": "my-agent",
      "ws_url": "wss://grix.dhf.pub/v1/agent-api/ws",
      "agent_id": "your-agent-id",
      "api_key": "your-grix-api-key",
      "client_type": "claude"
    }
  ]
}

Global example:

{
  "agents": [
    {
      "name": "my-agent",
      "ws_url": "wss://ws.grix.im/v1/agent-api/ws",
      "agent_id": "your-agent-id",
      "api_key": "your-grix-api-key",
      "client_type": "claude"
    }
  ]
}

Change client_type to match the agent you want to connect (see table above). You can define multiple agents in one file, or use separate files under ~/.grix/config/.

Config Reference

Each agent entry uses one flat structure:

Field	Required	Description
name	yes	Display name for this agent
ws_url	yes	WebSocket endpoint URL (region-specific). China mainland: wss://grix.dhf.pub/v1/agent-api/ws; Global: wss://ws.grix.im/v1/agent-api/ws
agent_id	yes	Agent ID from Grix platform
api_key	yes	API key for authentication
client_type	yes	See Supported Agents table above
prompt_timeout_ms	no	Prompt execution timeout (ms)
pool.maxSize	no	Max adapter pool size (default 20)
pool.idleTimeoutMs	no	Idle adapter eviction timeout (default 300000 = 5 min)

Adapter command/args/options are built in and resolved from client_type. To connect a different agent, simply change client_type — no other config changes needed.

Multi-agent Example

China mainland region (swap the ws_url domain to ws.grix.im for the global region):

{
  "agents": [
    {
      "name": "my-claude",
      "ws_url": "wss://grix.dhf.pub/v1/agent-api/ws",
      "agent_id": "your-agent-id",
      "api_key": "your-grix-api-key",
      "client_type": "claude"
    },
    {
      "name": "my-gemini",
      "ws_url": "wss://grix.dhf.pub/v1/agent-api/ws",
      "agent_id": "another-agent-id",
      "api_key": "your-grix-api-key",
      "client_type": "gemini"
    }
  ]
}

3. Start the daemon

grix-connector start

The daemon connects to Grix via WebSocket and starts routing chat messages to your agents.

Commands

grix-connector start     # Start as system service (auto-installs on first run)
grix-connector stop      # Stop the service
grix-connector restart   # Restart the service
grix-connector reload    # Hot-reload agent configs without restarting the daemon
grix-connector status    # Check service status

Reloading config (reload)

reload applies changes to your config files without restarting the daemon. It re-reads ~/.grix/config/*.json, diffs against what's currently running, and acts per agent:

Change in config	What happens
Agent added	Started and connected
Agent removed	Stopped and disconnected
Agent config changed	That agent restarts (stop old, start new)
Agent unchanged	Left running untouched — its sessions are not interrupted

When to use it. You run a multi-agent setup and want to add, remove, or re-key one agent — or tweak one agent's settings — without dropping the live sessions of the other agents. A full restart would reconnect every agent and interrupt all in-flight conversations; reload only touches the agents whose config actually changed.

Safety. If any config file fails to parse (e.g. you're mid-edit and the JSON is broken), or no valid agent config is found, the reload aborts and the running agents are left exactly as they are — nothing is torn down on a bad config.

Three equivalent ways to trigger it:

grix-connector reload                          # CLI (sends SIGHUP to the daemon)
kill -HUP "$(cat ~/.grix/grix-acp.pid)"        # raw signal (Unix)
curl -XPOST http://127.0.0.1:19580/api/reload  # Admin API — returns the per-agent result as JSON

The CLI/signal form is fire-and-forget; the per-agent result is written to the daemon log. The Admin API form returns the result (added/removed/restarted/unchanged/failed) synchronously.

Ports

The daemon binds two local loopback ports (127.0.0.1 only):

Purpose	Default	Override (env)	Override (CLI)
Health check (/healthz)	19579	GRIX_HEALTH_PORT	--health-port <port>
Admin API (used by the local CLI)	19580	GRIX_ADMIN_PORT	--admin-port <port>

If a port is already in use, the daemon refuses to start and writes a clear message to ~/.grix/service/daemon.err.log and the main log, and marks ~/.grix/daemon-status.json as state: "failed" with a reason like port_bind_in_use:health:19579.

To pick different ports:

# via environment
GRIX_HEALTH_PORT=29579 GRIX_ADMIN_PORT=29580 grix-connector restart

# or via CLI flags (when running the daemon directly)
grix-connector --health-port 29579 --admin-port 29580

To find what is occupying a port:

# macOS / Linux
lsof -nP -iTCP:19579 -sTCP:LISTEN

# Windows (PowerShell or cmd)
netstat -ano | findstr :19579

OpenClaw Plugin

grix-connector can also be installed as an OpenClaw plugin, providing a Grix channel transport with admin tools and operator CLI.

Install

openclaw plugin install grix-connector

Or manually add to your OpenClaw project:

npm install grix-connector

Plugin Features

• Channel: Grix chat transport — routes messages between OpenClaw and your Grix deployment
• Tools: grix_query, grix_group, grix_admin, grix_egg, grix_register, grix_update, grix_message_send, grix_message_unsend, openclaw_memory_setup
• CLI: openclaw grix — agent management and admin commands
• Skills: 9 bundled skills for admin, group, query, registration, update, messaging, memory setup, and egg orchestration

Requirements

• OpenClaw >= 2026.4.8
• A Grix account with agent ID and API key

License

MIT