Quickstart

Zero to running agent
in five minutes.

This guide gets you from nothing to a working Gyre agent that responds to messages. By the end you'll have Gyre running in your terminal with persistent memory.

What You Need

Requirement Notes
macOS, Linux, or Windows WSL Native Windows: use the .msi installer instead
An LLM Claude Code (zero-config) or an API key for Anthropic / OpenAI / Ollama

No database setup required. Gyre uses an embedded libSQL database by default.

1

Install Gyre

macOS / Linux / WSL:

curl -fsSL https://getgyre.com/install.sh | sh

Windows (PowerShell):

irm https://github.com/SargassoLLC/gyre/releases/latest/download/gyre-installer.ps1 | iex

From source (Rust 1.85+):

git clone https://github.com/SargassoLLC/gyre.git && cd gyre
cargo build --release
# Binary is at: target/release/gyre

Verify:

gyre --version
2

Choose Your LLM

Option A: Claude Code (zero-config, recommended)

If you have Claude Code installed, Gyre uses it automatically — no API key needed.

# Verify Claude Code is installed
claude --version

Option B: API key

Set the appropriate env var before running gyre setup:

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI
export OPENAI_API_KEY=sk-...

# Ollama (local, no key needed)
export LLM_BACKEND=ollama
export OLLAMA_MODEL=llama3.2   # or any model you've pulled

You can also set these in a .env file in your working directory.

3

Run the Setup Wizard

gyre setup

The wizard takes about 2 minutes and handles:

Skip everything you don't need — every setting has a sensible default. You can re-run gyre setup at any time to change settings.

4

Start the Agent

gyre run

You'll see the Gyre boot screen, then a > prompt. Type anything to talk to your agent:

> Hello! What can you help me with?

Tip: Type /help to see all available slash commands.

5

Verify It's Working

Run these quick checks:

# 1. Check the agent responds
> What's today's date?

# 2. Check memory is persisting
> Remember that my name is [your name]

# (Start a new session)
gyre run

> What's my name?
# The agent should remember.

If memory recall works, your agent is fully operational.

What's Next

Connect a Messaging Channel

Talk to Gyre from your phone or team workspace:

gyre setup channels

Available channels: Telegram · Discord · Slack · WhatsApp

Give the Agent a Personality

Create SOUL.md in your agent's home directory (~/.gyre/agents/<name>/):

# SOUL.md
You are [name]. [Brief description of personality, tone, focus areas.]

Restart Gyre and the agent will adopt the new identity.

Add Memory Context

Create MEMORY.md in the same directory to seed the agent with background knowledge:

# MEMORY.md
- My timezone is EST
- I work on [project]
- Prefer concise responses

Docker Setup (persistent background service)

# fill in API keys
cp deploy/env.example .env
docker-compose -f docker-compose.simple.yml up -d

See docs/DOCKER.md for full container setup.

Troubleshooting

gyre: command not found

The installer adds Gyre to your PATH. Reload your shell:

source ~/.bashrc # or ~/.zshrc on macOS

Error: No LLM provider configured

Set an API key or install Claude Code:

export ANTHROPIC_API_KEY=sk-ant-...
gyre run

Error: Database locked

Another Gyre instance is running. Find and stop it:

pkill -f "gyre run"
gyre run

Agent doesn't remember things between sessions

Memory requires the database to be writable. Check:

# gyre.db should exist and be readable/writable
ls -la ~/.gyre/

If running in Docker, make sure the volume is mounted: ~/.gyre:/root/.gyre

LLM errors / timeouts

  1. Verify your API key is valid
  2. Check your internet connection
  3. For Ollama: confirm the model is downloaded (ollama list)

Still stuck?

Full Documentation | Community Discord | File an Issue