GatheRing
User Guide
Installation
Requirements
Quick Install
1. Clone the Repository
2. Create Virtual Environment
3. Install Python Dependencies
4. Install Dashboard Dependencies
5. Configure Environment
6. Setup Database
7. Start the Application
Docker Installation
Verifying Installation
Troubleshooting
PostgreSQL Connection Issues
pgvector Extension Not Found
Node.js Version Issues
Next Steps
Quickstart
Prerequisites
Your First Circle
1. Start the Services
2. Open the Dashboard
3. Create Your First Circle
4. Add Agents to the Circle
5. Start a Conversation
6. Watch the Conversation
Using the Workspace
Access the Workspace
Features
What’s Next?
GatheRing User Guide
Table of Contents
Getting Started
Installation
Quick Start
Creating Your First Agent
Basic Agent Configuration
Adding Background and History
Complete Agent Example
Agent Personalities
Understanding Personality Blocks
Available Personality Traits
Combining Personalities
Personality Intensity
Using Tools
Available Tools
Calculator Tool
FileSystem Tool
Adding Tools to Existing Agents
Tool Permissions
Multi-Agent Conversations
Creating Conversations
Managing Conversation Flow
Saving Conversations
Best Practices
1. Choose Appropriate Personalities
2. Provide Rich Backgrounds
3. Use Tools Wisely
4. Memory Management
5. Error Handling
Troubleshooting
Common Issues
“Agent name is required”
“Invalid LLM provider”
“Write permission denied”
Performance Tips
Getting Help
Next Steps
Dashboard Guide
Quick Start Workflow
Overview
Getting Started
Starting the Dashboard
Navigation
Projects
Project List
Importing a Project
Project Features
Agent Management
Agent List
Agent Chat
Agent Dashboard
Skills Configuration
Skills Panel
Available Skills
Enabling Skills
Viewing Skill Tools
Circles (Team Orchestration)
Circle Overview
Circle Features
Task Board
Task Statuses
Conversations
Conversation Features
Goals
Goal Structure
Knowledge Base
Features
Workspace
Supported Features
Git Integration
Features
Settings
Configurable Settings
Keyboard Shortcuts
Troubleshooting
Dashboard won’t connect to API
WebSocket disconnects
Skills not loading
Development
Building for Production
Running Tests
Code Style
Circles
What is a Circle?
Circle Lifecycle
States
Creating Circles
Via API
Via Python
Managing Agents in Circles
Adding Agents
Removing Agents
Listing Circle Agents
Circle Configuration
Conversation Modes
Example Configuration
Circle Operations
Start a Circle
Pause a Circle
Resume a Circle
Archive a Circle
Conversations in Circles
Advancing Conversations
Circle Memory
Accessing Circle Memory
Best Practices
1. Name Circles Meaningfully
2. Limit Circle Size
3. Define Clear Roles
4. Use Appropriate Conversation Modes
Related Topics
Agents
Agent Anatomy
Creating Agents
Basic Agent
Full Agent Configuration
Supported Providers
OpenAI
Anthropic
Ollama (Local)
Choosing the Right Provider
Personality System
Available Traits
Trait Intensity
Communication Styles
Agent Skills
Built-in Skills
Custom Competencies
Agent Tools
Available Tools
Configuring Tools
Agent Memory
Memory Scopes
Memory Operations
Agent States
States
Agent Sessions
Using Personas
Loading a Persona
Best Practices
1. Match Model to Task
2. Define Clear Roles
3. Balanced Personalities
4. Appropriate Memory Scope
5. Tool Permissions
Related Topics
Workspace
Overview
Accessing the Workspace
File Explorer
Features
Keyboard Shortcuts
Context Menu
Code Editor
Syntax Highlighting
Editor Features
Keyboard Shortcuts
LSP Integration
Terminal
Features
Usage
Terminal Sessions
Git Integration
Git Panel
Operations
Viewing Status
Staging Changes
Committing
Viewing Diffs
Other Operations
Media Viewers
Image Viewer
Audio Player
Video Player
PDF Viewer
Layout
Panels
Resizing
Themes
API Endpoints
Workspace Info
File Operations
Git Operations
WebSocket Streaming
Best Practices
1. Use Keyboard Shortcuts
2. Organize Files
3. Commit Often
4. Use the Terminal
5. Review Diffs
Related Topics
Frequently Asked Questions
General
What is GatheRing?
What can I do with GatheRing?
What AI models are supported?
Is GatheRing free?
Installation
What are the system requirements?
How do I install pgvector?
Why am I getting database connection errors?
The dashboard won’t start. What should I do?
Agents
How many agents can I create?
Can agents learn over time?
How do I customize agent personalities?
Can agents use external tools?
Circles
What’s the difference between a circle and a conversation?
Can an agent be in multiple circles?
How do I archive a circle?
Workspace
Why isn’t syntax highlighting working?
How do I enable LSP for Python?
Can I use the workspace without the dashboard?
How do I fix terminal issues?
API
How do I authenticate API requests?
What’s the rate limit?
How do I stream responses?
Performance
How do I improve response times?
Why is memory usage high?
How do I scale GatheRing?
Troubleshooting
Agents aren’t responding
WebSocket connection fails
Database migrations fail
File uploads don’t work
Getting Help
Where can I report bugs?
Is there a community?
How can I contribute?
Developer Guide
Architecture
System Overview
Directory Structure
Core Components
Agent System
Circle System
Memory System
Pipeline Engine
Scheduler
Event System
API Layer
REST Endpoints
WebSocket Channels
Database Schema
Core Tables
Schemas
Frontend Architecture
Tech Stack
State Management
Component Structure
Security
Authentication
API Security
Agent Security
Scalability
Multi-Instance Support
Horizontal Scaling
Performance Optimizations
Distributed Coordination
Problem
Current State
Proposed Solution: Redis-Based Coordination
1. Task Queue (Atomic Claiming)
2. Distributed Locks
3. Event Synchronization
Implementation Priority
Files to Modify
Configuration
Security Considerations
Configuration
Environment Variables
Configuration Files
Related Topics
Contributing
Quick Start
1. Fork and Clone
2. Setup Development Environment
3. Create a Branch
4. Make Changes
5. Run Tests
6. Submit PR
Code Style
Commit Messages
Getting Help
Database
pycopg - Database Layer
Async Database Service (v1.0)
Lifespan Ordering
Advisory Locks (v1.0)
Low-Level Drivers
Database Diagram
Overview
Setup
Prerequisites
Create Database
Enable Extensions
Run Migrations
Schema Details
Agent Schema
Circle Schema
Memory Schema
Vector Search
Creating Embeddings
Similarity Search
Migrations
Creating a Migration
Migration Best Practices
Connection Pooling
Configuration
Backup and Restore
Backup
Restore
Performance
Indexes
Query Optimization
Troubleshooting
Connection Issues
pgvector Issues
Performance Issues
Related Topics
API Development
Architecture
Creating a New Router
1. Create the Router File
2. Create Schemas
3. Register the Router
Dependency Injection
Database Connection
Current User (Future)
Custom Dependencies
Error Handling
HTTP Exceptions
Custom Exception Handlers
Request Validation
Path Parameters
Query Parameters
Request Body
Response Models
Single Item
List with Pagination
WebSocket Endpoints
Background Tasks
Testing API Endpoints
API Documentation
Adding Documentation
Related Topics
WebSocket
Overview
Server Implementation
Basic WebSocket Endpoint
Message Types
Sending Messages
Client Implementation
JavaScript/TypeScript
React Hook
Python Client
Event Bus Integration
Authentication
Token-based Auth
Connection on First Message
Heartbeat/Keepalive
Testing WebSocket
Related Topics
Testing
Test Structure
v1.0 Test Categories
Running Tests
All Tests
With Coverage
Specific Tests
Verbose Output
Writing Tests
Basic Test
Async Tests
Parametrized Tests
Test Classes
Fixtures
Basic Fixtures
Scoped Fixtures
Factory Fixtures
Mocking
Basic Mocking
Patching
Async Mocking
API Testing
Testing Endpoints
Testing WebSocket
Database Testing
Test Database
Testing Queries
Test Markers
Test Coverage
Configuration
Running Coverage
Best Practices
1. Follow AAA Pattern
2. One Assertion Per Test (When Possible)
3. Use Descriptive Names
4. Isolate Tests
5. Mock External Services
Continuous Integration
Related Topics
API Reference
GatheRing API Reference
Core Interfaces
IAgent
Methods
ILLMProvider
Methods
ITool
Available Tools
Tool Result
IPersonalityBlock
Available Personality Traits
IConversation
Methods
Data Classes
Message
ToolPermission
Exceptions
ConfigurationError
LLMProviderError
ToolExecutionError
Complete Examples
Creating a Research Assistant
Multi-Agent Collaboration
Custom Tool Integration
API Endpoints
Health & Status
GET /health
GET /health/system
GET /health/checks
GET /health/ready
GET /health/live
Agents
GET /agents
POST /agents
GET /agents/{id}
PATCH /agents/{id}
DELETE /agents/{id}
GET /agents/{id}/sessions
POST /agents/{id}/sessions
GET /agents/{id}/memories
Circles
GET /circles
POST /circles
GET /circles/{name}
PATCH /circles/{name}
DELETE /circles/{name}
POST /circles/{name}/start
POST /circles/{name}/pause
POST /circles/{name}/resume
POST /circles/{name}/archive
GET /circles/{name}/agents
POST /circles/{name}/agents
DELETE /circles/{name}/agents/{agent_id}
Conversations
GET /conversations
POST /conversations
GET /conversations/{id}
GET /conversations/{id}/messages
POST /conversations/{id}/advance
POST /conversations/{id}/end
Workspace
GET /workspace/{id}/info
GET /workspace/{id}/files
GET /workspace/{id}/files/{path}
PUT /workspace/{id}/files/{path}
DELETE /workspace/{id}/files/{path}
POST /workspace/{id}/files/{path}/rename
GET /workspace/{id}/git/status
GET /workspace/{id}/git/commits
POST /workspace/{id}/git/stage
POST /workspace/{id}/git/unstage
POST /workspace/{id}/git/commit
POST /workspace/{id}/git/push
POST /workspace/{id}/git/pull
GET /workspace/{id}/git/diff
Memory
GET /memory/search
POST /memory
DELETE /memory/{id}
Dashboard
GET /dashboard/circles
GET /dashboard/agents
GET /dashboard/activity
GET /dashboard/stats
Settings
GET /settings
PATCH /settings/providers/{provider}
PATCH /settings/application
POST /settings/providers/{provider}/test
Tools (Agent Capabilities)
GET /tools/skills
GET /tools/skills/categories
GET /tools/agents/{agent_id}
PATCH /tools/agents/{agent_id}/skills/{skill_name}
POST /tools/agents/{agent_id}/skills/bulk
POST /tools/agents/{agent_id}/skills/enable-all
POST /tools/agents/{agent_id}/skills/disable-all
GET /tools/agents/{agent_id}/enabled
Rate Limiting
Error Responses
400 Bad Request
404 Not Found
422 Validation Error
500 Internal Server Error
API Models
Agent Models
AgentCreate
AgentUpdate
AgentResponse
PersonalityConfig
AgentConfig
AgentStatus
Circle Models
CircleCreate
CircleResponse
CircleConfig
CircleStatus
Conversation Models
ConversationCreate
ConversationResponse
ConversationAdvance
MessageResponse
Workspace Models
WorkspaceInfo
FileInfo
FileContent
FileWrite
GitStatus
GitCommit
GitStage
GitCommitCreate
Memory Models
MemoryCreate
MemoryResponse
MemorySearchResult
MemoryScope
MemoryType
Dashboard Models
DashboardStats
ActivityItem
Common Models
PaginatedResponse
ErrorResponse
ValidationErrorResponse
GatheRing
Index
Index