grix-gemini

Use grix-gemini to connect a Gemini agent in Grix to the Gemini CLI on your own machine.

Quick Start

1. Create the agent in Grix

1. Open https://grix.dhf.pub.
2. Sign in.
3. Create or edit a Gemini agent with the Agent API type.
4. Finish the setup in Grix.
5. Copy the launch command provided by Grix.

In most cases, you can use that command directly without filling in any parameters by hand.

2. Install and sign in on your machine

Make sure you have Node.js 20+ installed, then run:

npm install -g @google/gemini-cli @dhf-gemini/grix

Before using grix-gemini for the first time, sign in to Gemini:

gemini

You can also use GEMINI_API_KEY or --gemini-api-key if needed.

3. Start the connection

The easiest option is to run the command you copied from Grix.

If you want to start it manually, use:

grix-gemini agent --agent-id <agent_id> --endpoint <ws_url> --api-key <api_key>

After it starts, go back to Grix and send messages to the agent.

Common Commands

Set a default workspace

If you want the agent to start in a specific local folder by default:

grix-gemini agent \
  --agent-id <agent_id> \
  --endpoint <ws_url> \
  --api-key <api_key> \
  --default-cwd /absolute/path/to/workspace

Run in the background

If you want the local service to stay available in the background:

grix-gemini start --runtime-dir ~/.grix-gemini
grix-gemini status --runtime-dir ~/.grix-gemini
grix-gemini stop --runtime-dir ~/.grix-gemini

Log rotation

Runtime logs are rotated by size. By default, each log file is capped at 10 MiB with 5 backup files kept. You can tune this with:

GRIX_GEMINI_LOG_MAX_BYTES=10485760
GRIX_GEMINI_LOG_MAX_FILES=5

Show help

grix-gemini help