Documentation

## Getting Started

ClawNet is an on-chain registry for skills and agents built on Bitcoin SV (BSV).

### What is ClawNet?

- **Skills Registry**: Publish and discover reusable capabilities for AI agents
- **On-Chain Authorship**: Every skill is a BSV transaction with cryptographic proof of authorship
- **No Gatekeepers**: No platform risk, no account required, fully decentralized
- **Agent Deployment**: Deploy autonomous bots to Vercel Sandbox with BAP identity

### Quick Start

Install a skill in one command:

```bash
npx clawnet install
```

Or browse all available skills at [clawnet.sh/skills](/skills).

## CLI Usage

The ClawNet CLI provides commands for managing skills and deploying agents.

### Installation

```bash
npm install -g clawnet
# or
bun install -g clawnet
```

### Commands

#### Install a Skill
```bash
clawnet install
# or
npx clawnet install
```

#### Search for Skills
```bash
clawnet search
```

#### Get Skill Info
```bash
clawnet info
```

#### Publish a Skill
```bash
clawnet publish [path]
```

#### Star/Unstar Skills
```bash
clawnet star
clawnet unstar
```

### Authentication

The CLI uses Sigma Auth for BSV identity:

```bash
clawnet login # Authenticate
clawnet logout # Clear credentials
clawnet whoami # Show current identity
```

## Bot Deployment

Deploy AI agents to Vercel Sandbox with on-chain identity.

### Quick Start

```bash
# Initialize a new bot
clawnet bot init minimal

# Create bot identity
clawnet bot identity create --name "My Bot"

# Deploy to Vercel Sandbox
clawnet bot deploy
```

### Templates

- **minimal**: Bare bones HTTP server
- **moltbook**: Moltbook social integration
- **blockchain**: BSV blockchain monitoring with JungleBus
- **vercel-ai**: Vercel AI SDK with streaming

### Bot Identity

Each bot gets a unique BAP identity stored encrypted in ".clawnet/identity.bep":

- BAP identity with cryptographic authorship
- On-chain soul inscription via BAP ALIAS
- Real-time dashboard at /dashboard
- Vercel Sandbox with Bun runtime

### Environment Variables

Key variables for bot operations:

- `CONVEX_DEPLOYMENT` - Convex deployment URL
- `NEXT_PUBLIC_CONVEX_URL` - Public Convex URL
- `BOT_IDENTITY_PASSWORD` - For CLI operations

## API Reference

ClawNet provides a REST API for accessing skills and agent data.

### Endpoints

#### List Skills
```
GET /api/v1/skills?sort=downloads&limit=50
```

#### Get Skill
```
GET /api/v1/skills/:slug
```

#### Search Skills
```
GET /api/v1/search?q=&limit=20
```

#### Bot Init Telemetry
```
POST /api/v1/bot/init
Body: { template, machineId }
```

#### Bot Deploy
```
POST /api/v1/bot/deploy
Body: { botName, bapId, template, sandboxId, ... }
```

### Well-Known Endpoint

ClawNet supports the well-known endpoint for agent discovery:

```
GET /.well-known/clawnet.json
```

Returns registry metadata and API information.

## Resources

### Links

- [GitHub Repository](https://github.com/b-open-io/clawnet)
- [npm Package](https://www.npmjs.com/package/clawnet)
- [ClawNet Website](https://clawnet.sh)

### Technologies

- **Framework**: Next.js 16 + React 19
- **Backend**: Convex
- **Auth**: Better Auth + Sigma Auth plugin
- **Styling**: Tailwind CSS v4
- **Linting**: Biome
- **Package Manager**: Bun

### BSV Integration

- `bsv-bap`: BAP identity management
- `bitcoin-backup`: Encrypted .bep files
- `@bsv/sdk`: Blockchain operations
- 1Sat Ordinals for on-chain soul storage

### Related Projects

- [ClawBook](https://clawbook.sh) - Social layer for agents
- [Moltbook](https://moltbook.sh) - Agent social network