Configuration

Gyrus stores its configuration in a global JSON file that tracks all your workspaces and settings.

Configuration File Location

The configuration file is located at:

~/.config/gyrus/config.json

On different platforms:

• macOS: ~/.config/gyrus/config.json
• Linux: ~/.config/gyrus/config.json
• Windows: %USERPROFILE%\.config\gyrus\config.json

Configuration Structure

{
  "version": 1,
  "default": "personal",
  "workspaces": [
    {
      "name": "personal",
      "path": "~/gyrus",
      "description": "Personal knowledge and projects"
    },
    {
      "name": "work",
      "path": "~/work/brain",
      "description": "Work projects"
    }
  ],
  "settings": {
    "serve": {
      "port": 3333
    },
    "daemon": {
      "port": 3334
    }
  }
}

Configuration Fields

Top-Level Fields

Field	Type	Description
version	number	Configuration schema version (currently 1)
default	string	Name of the default workspace
workspaces	array	List of registered workspaces
settings	object	Global settings

Workspace Fields

Field	Type	Required	Description
name	string	Yes	Unique identifier for the workspace
path	string	Yes	Path to the workspace directory
description	string	No	Human-readable description

Settings Fields

Field	Type	Default	Description
serve.port	number	3333	Port for the dashboard server
daemon.port	number	3334	Port for the HTTP/SSE MCP server

Path Resolution

Paths in the configuration support:

• Absolute paths: /Users/name/gyrus
• Home directory: ~/gyrus (expanded at runtime)
• Relative paths: ./brain (relative to current directory when registered)

WARNING

Relative paths are stored as-is. They resolve relative to where you run Gyrus commands.

Managing Configuration

View Current Configuration

The configuration file is plain JSON. View it directly:

cat ~/.config/gyrus/config.json

Or use the doctor command to see parsed configuration:

gyrus doctor

Adding Workspaces

Use the init command to add workspaces:

gyrus init ~/new-workspace --name new --description "New workspace"

This automatically updates the configuration file.

Changing Default Workspace

gyrus use work

This updates the default field in the configuration.

Manual Editing

You can edit the configuration file directly, but be careful to maintain valid JSON:

# Open in your editor
code ~/.config/gyrus/config.json

After manual edits, verify the configuration:

gyrus doctor

Workspace Structure

Each workspace directory should contain:

<workspace>/
├── knowledge/
│   ├── README.md
│   ├── index.md
│   ├── instructions.md
│   ├── projects/
│   ├── patterns/
│   ├── tools/
│   ├── gotchas/
│   └── decisions/
└── adrs/
    └── template.md

The gyrus init command creates this structure automatically.

Environment Variables

Gyrus respects the following environment variables:

Variable	Description
GYRUS_CONFIG	Override the config file location
GYRUS_WORKSPACE	Override the default workspace

Example:

GYRUS_WORKSPACE=work gyrus mcp

Troubleshooting

Configuration Not Found

If Gyrus can't find the configuration:

# Initialize a workspace (creates config if missing)
gyrus init

Invalid Configuration

If the configuration is corrupted:

1. Back up the existing file
2. Delete or rename ~/.config/gyrus/config.json
3. Re-initialize your workspaces

Workspace Path Changed

If you moved a workspace:

# Re-initialize at the new location with the same name
gyrus init /new/path --name existing-name

This updates the path in the configuration.

Configuration Validation

Gyrus validates the configuration on startup. Common validation errors:

Error	Cause	Solution
Invalid JSON	Syntax error in config file	Fix JSON syntax or regenerate
Missing version	Old or corrupted config	Re-initialize workspaces
Duplicate workspace name	Two workspaces with same name	Edit config to rename one
Invalid workspace path	Path doesn't exist	Update path or remove workspace