ClawBox
Open-source cloud file system for AI agents
Semantic search • Folders • File sharing • Self-hostable
Live Demo •
Self-Host Guide
What is ClawBox?
ClawBox is an open-source file storage platform built for AI agents. Upload files, search by meaning, organize into folders, and share with anyone — all via API or CLI.
For agents: Store files, search by meaning, organize into folders — all via API.
For humans: Upload files, get a share link, search across documents. Like a smarter Dropbox with an API-first design.
Key Features
| Feature | Description |
|---|
| Semantic Search | Search files by meaning, not keywords. Powered by Gemini embeddings. |
| Multimodal | Index text, PDF, Word, Excel, PowerPoint, CSV, images, audio, video. |
| Virtual Folders | Organize files with paths like /docs/reports/q1.pdf. |
| File Sharing | Generate share links — anyone with the link can download. |
| Google Login | Sign in with Google for 10 GB storage (1 GB free without login). |
| Self-Hostable | Docker Compose and cloud-friendly deployment options for local or hosted setups. |
Quick Start
Option 1: Agent plugin
Claude Code
claude plugin marketplace add Alfra-AI/clawbox && claude plugin install clawbox@alfra-ai
Then, inside a Claude Code session, install the CLI by running:
/clawbox setup
Option 2: Hosted web UI
No setup needed — just visit clawbox.ink.
Option 3: CLI
pip install clawbox
clawbox init # Get a token
clawbox upload report.pdf # Upload
clawbox search "quarterly revenue" # Semantic search
Self-hosting via pip? Use pip install clawbox[server] to include all server dependencies (FastAPI, SQLAlchemy, etc.).
If you want to connect ClawBox to a coding or task agent, see skills/clawbox/SKILL.md.
Option 4: Self-hosting with docker
git clone https://github.com/Alfra-AI/clawbox.git
cd clawbox
cp .env.example .env # Edit to add your Google API key for search
docker compose up -d
docker compose exec app alembic upgrade head
ClawBox server is then available at http://localhost:8000.
API
All endpoints (except public ones) require Authorization: Bearer <token>.
Core
| Endpoint | Method | Auth | Description |
|---|
POST /get_token | POST | No | Get a free token (1 GB storage) |
POST /files/upload | POST | Yes | Upload a file (with optional path for folders) |
GET /files | GET | Yes | List files (filter by folder, recursive) |
GET /files/{id} | GET | Yes | Download a file |
PATCH /files/{id} | PATCH | Yes | Move/rename a file |
DELETE /files/{id} | DELETE | Yes | Delete a file |
POST /search | POST | Yes | Semantic search across files |
POST /files/embed | POST | Yes | Generate/retry embeddings |
Sharing
| Endpoint | Method | Auth | Description |
|---|
POST /files/{id}/share | POST | Yes | Create a share link |
GET /s/{code} | GET | No | Download via share link |
Auth
| Endpoint | Method | Description |
|---|
GET /auth/google | GET | Start Google OAuth login |
GET /auth/me | GET | Get current user info |
Supported File Formats
| Format | Search Support |
|---|
| Text, Markdown, JSON, XML, CSV | Full text extraction |
| PDF | pdfplumber |
| Word (.docx) | python-docx |
| Excel (.xlsx) | openpyxl |
| PowerPoint (.pptx) | python-pptx |
| Images (PNG, JPEG, GIF, WebP) | Gemini multimodal + captioning |
| Audio, Video | Gemini multimodal embedding |
Self-Hosting
Single Server
docker compose up -d
docker compose exec app alembic upgrade head
With MinIO (S3-Compatible Storage)
docker compose -f docker-compose.cluster.yml up -d
docker compose -f docker-compose.cluster.yml exec app alembic upgrade head
Any Cloud
ClawBox works with any S3-compatible storage. Set S3_ENDPOINT_URL:
JuliusBrussee
anthropics
wshobson
thedotmack
coreyhaines31
Lucklyric