README.md

---
title: Paperclip
emoji: 📎
colorFrom: purple
colorTo: gray
sdk: docker
app_port: 7860
pinned: false
---

# Paperclip — AI Agent Orchestration

Self-hosted [Paperclip](https://paperclip.ing) using [Fomext](https://fomext-api-router.hf.space) as the LLM backend.

**Models:**
- `qwen3-14b` — reasoning, research, and general agents
- `qwen3-coder-30b-a3b-instruct-fp8` — coding agents

---

## Setup (do this before first deploy)

### 1. Attach a Storage Bucket
**Settings → Storage → Attach bucket** — mounts at `/data`.
All Paperclip state lives at `/data/paperclip` and survives restarts.

### 2. Set Secrets (Settings → Variables and Secrets)

| Secret | Value |
|---|---|
| `FOMEXT_API_KEY` | Your Fomext API key |
| `BETTER_AUTH_SECRET` | Any long random string (signs auth tokens) |
| `PAPERCLIP_PUBLIC_URL` | `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space` |
| `PAPERCLIP_ALLOWED_HOSTNAMES` | `YOUR_USERNAME-YOUR_SPACE_NAME.hf.space` |

### 3. Push these files & let HF build

### 4. Claim your board
After the Space starts, open **Logs → Container** and find the one-time
board-claim URL. Click it to create your admin account.

---

## Configuring agents (after first login)

When creating an agent, use **`opencode_local`** as the adapter type.

**Reasoning / research agent:**
```json
{
  "adapterType": "opencode_local",
  "adapterConfig": {
    "model": "fomext/qwen3-14b"
  }
}
```

**Coding agent:**
```json
{
  "adapterType": "opencode_local",
  "adapterConfig": {
    "model": "fomext/qwen3-coder-30b-a3b-instruct-fp8"
  }
}
```

---

## Keeping the Space alive

Point [UptimeRobot](https://uptimerobot.com) at your Space URL on a
5-minute ping interval — same as your other Spaces.