ClawSync Documentation

Complete setup guide for ClawSync, an open source AI agent platform with chat UI, skills system, MCP support, and multi-model routing.

Quickstart

Get ClawSync running locally in under 5 minutes.

git clone https://github.com/waynesutton/clawsync.git
cd clawsyncCopy

npm installCopy

npx convex devCopy

# For Claude (recommended)
ANTHROPIC_API_KEY=sk-ant-...

# For GPT
OPENAI_API_KEY=sk-...

# For Grok
XAI_API_KEY=xai-...Copy

npm run devCopy

Project Structure

clawsync/
├── convex/                 # Backend (Convex functions)
│   ├── agent/              # AI agent core
│   │   ├── clawsync.ts     # Agent definition
│   │   ├── security.ts     # Security checker
│   │   ├── toolLoader.ts   # Dynamic tool loading
│   │   └── modelRouter.ts  # Model resolution
│   ├── lib/                # Shared utilities
│   ├── schema.ts           # Database schema
│   ├── http.ts             # HTTP endpoints
│   └── setup.ts            # Seed data
├── src/                    # Frontend (React)
│   ├── pages/              # Page components
│   ├── components/         # Reusable components
│   ├── styles/             # CSS tokens and globals
│   ├── hooks/              # React hooks
│   └── lib/                # Utilities
├── content/                # Content files
│   └── soul.md             # Default agent personality
└── public/                 # Static assetsCopy

Convex Setup

ClawSync uses Convex as its backend. Convex provides real-time database, serverless functions, and file storage.

Creating a Convex Project

When you run npx convex dev for the first time:

1. You'll be prompted to log in or create a Convex account
2. Choose "Create a new project" when asked
3. The Convex CLI will generate your project and deployment URL

Convex Dashboard

Access your Convex dashboard at dashboard.convex.dev to:

• View and edit data in your tables
• Set environment variables
• View function logs
• Monitor usage and performance

Components

ClawSync uses these Convex components (configured in convex/convex.config.ts):

Environment Variables

Set these in the Convex dashboard under Settings → Environment Variables.

AI Provider Keys

At least one is required:

*At least one AI provider key is required.

SyncBoard Authentication

Generate a password hash:

echo -n "your-password" | shasum -a 256Copy

X/Twitter Integration

AgentMail

WorkOS AuthKit (Optional)

Database Schema

ClawSync's database tables (defined in convex/schema.ts):

Core Tables

Skills & Tools

Channels

Multi-Agent

Model Providers

ClawSync supports multiple AI model providers. Configure your preferred provider in the setup wizard or SyncBoard.

Anthropic (Claude)

Recommended for best agent capabilities.

OpenAI (GPT)

xAI (Grok)

OpenRouter

Access 300+ models through a single API. Set OPENROUTER_API_KEY and use any model ID from openrouter.ai/models.

Agent Configuration

Configure your agent in SyncBoard → Overview or via the setup wizard.

Settings

Soul Document

The soul document defines your agent's personality, knowledge, and behavior. Edit it in SyncBoard → Soul.

Structure

# Agent Identity
You are [name], a [role description].

# Personality
- Trait 1
- Trait 2
- Communication style

# Knowledge Areas
- Domain expertise
- Special capabilities

# Behavioral Guidelines
- How to handle specific situations
- What to avoidCopy

Multi-Agent System

Run multiple agents simultaneously, each with independent configurations. Manage agents in SyncBoard > Agents.

Creating agents

Each agent has its own name, model, provider, soul, skills, and MCP server assignments. Create agents from SyncBoard > Agents or during the setup wizard (which creates your first default agent).

Agent controls

Each agent supports these operational modes:

Shared soul documents

Soul documents can be shared across agents. Create reusable souls in SyncBoard > Souls and assign them to one or many agents. Each agent can also have its own inline soul document.

Per-agent assignments

Each agent can have its own set of skills and MCP servers. Assign them in the Agent Detail page under the Skills and MCP tabs.

Agent-to-agent interaction

Agents can communicate with each other. When multiple agents are configured, each agent gets dynamically generated ask_agent_* tools that let it query other agents. Interactions are logged in the agentInteractions table.

Agent activity feed

View all agent activity in a unified feed at SyncBoard > Agent Feed, or filter by individual agent. Each activity log entry includes which agent performed the action.

Database tables

API

The HTTP API supports multi-agent:

# List all agents
GET /api/v1/agents

# Chat with a specific agent
POST /api/v1/agent/chat
{
  "message": "Hello",
  "agentId": "optional-agent-id"
}Copy

Skills System

Skills extend your agent's capabilities. Manage them in SyncBoard → Skills.

Skill Types

Template Skills

Pre-built skills from the template library. Select a template and customize parameters.

Webhook Skills

Call external APIs when the agent invokes the skill.

{
  "url": "https://api.example.com/action",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer {{secret:API_KEY}}"
  }
}Copy

Code Skills

TypeScript functions that run in Convex. (Coming soon)

Skill Approval

All skills require admin approval before they can be used. This prevents unauthorized tool usage.

Security Controls

• Rate limiting: Max invocations per minute
• Timeout: Maximum execution time
• Security check: Input validation before execution

MCP Servers

Connect to external MCP (Model Context Protocol) servers to give your agent access to additional tools.

Adding an MCP Server

1. Go to SyncBoard → MCP
2. Click "Add MCP Server"
3. Enter the server name and URL
4. Approve the server to enable its tools

Server Requirements

• Must implement the MCP protocol
• Must be accessible from your Convex backend
• Tools are discovered automatically

Channel Integrations

Connect your agent to messaging platforms. Configure in SyncBoard → Channels.

Supported Channels

Webhook Setup

Each channel sends webhooks to your Convex HTTP endpoint:

https://your-deployment.convex.site/webhook/telegram
https://your-deployment.convex.site/webhook/discord
https://your-deployment.convex.site/webhook/whatsapp
https://your-deployment.convex.site/webhook/slack
https://your-deployment.convex.site/webhook/emailCopy

X/Twitter Integration

Connect your agent to X (Twitter) to read tweets, reply to mentions, and post updates.

Setup

1. Create a developer account at developer.twitter.com
2. Create a project and app with Read and Write permissions
3. Generate OAuth 1.0a credentials
4. Set environment variables (see Environment Variables section)
5. Enable features in SyncBoard → X

Features

AgentMail Integration

AgentMail provides email inboxes for your AI agent. Send, receive, and process emails programmatically.

Setup

1. Get an API key from console.agentmail.to
2. Set AGENTMAIL_API_KEY in your Convex environment variables
3. Enable AgentMail in SyncBoard → AgentMail
4. Create your first inbox

Features

Environment Variable

AGENTMAIL_API_KEY=your-api-key-hereCopy

SyncBoard Dashboard

SyncBoard is your private admin dashboard for managing all aspects of your agent.

Sections

Authentication

SyncBoard Password Auth

Basic password protection for the admin dashboard. Set SYNCBOARD_PASSWORD_HASH in your environment variables.

WorkOS AuthKit (Optional)

For enterprise SSO, ClawSync has placeholders for WorkOS AuthKit integration:

1. Create a WorkOS account at workos.com
2. Create an application and configure OAuth
3. Set the environment variables
4. Uncomment the AuthKit provider in src/main.tsx

API Keys

Generate API keys in SyncBoard → API to allow external applications to interact with your agent.

API Endpoints

# Send a message
POST /api/chat
{
  "message": "Hello agent",
  "threadId": "optional-thread-id"
}

# Get thread messages
GET /api/threads/:threadId/messages

# Create new thread
POST /api/threadsCopy

Authentication

Include your API key in the Authorization header:

Authorization: Bearer your-api-keyCopy

Deployment

ClawSync uses Convex for hosting and deployment.

Deployment Options

Deploy Commands

# Development
npm run dev

# Production (Convex Storage)
npm run deploy

# Production (Cloudflare)
npm run deploy:cfCopy

Production Checklist

Security

• Set a strong SYNCBOARD_PASSWORD_HASH
• Enable rate limiting on all channels
• Review and approve only trusted skills
• Audit connected MCP servers

Configuration

• Configure your AI provider API key
• Set up your soul document
• Test all enabled channels
• Verify webhook endpoints are accessible

Monitoring

• Check activity logs regularly in SyncBoard
• Monitor Convex dashboard for errors
• Set up alerts for failed skill invocations