arc-host

Lightweight remote server for Arc VCS. Zero dependencies — uses only Node.js built-ins (http, node:sqlite, node:zlib, node:crypto).

Requires Node.js 22+ (for built-in SQLite support).

Quick Start

npx @alvei/arc-host --port 3000

Or install globally:

npm i -g @alvei/arc-host
arc-host --port 3000

Setup

1. Create a project

arc-host project create --name my-project
# Created project: a1b2c3d4e5f6g7h8 (my-project)

2. Generate tokens

arc-host token create --project a1b2c3d4e5f6g7h8 --role writer
# Token (writer): arc_...

arc-host token create --project a1b2c3d4e5f6g7h8 --role reader
# Token (reader): arc_...

3. Connect from Arc

arc remote add origin http://localhost:3000 --token arc_...
arc sync

Server Options

arc-host [--port 3000] [--db ./arc-host.db]

| Flag | Default | Description | |------|---------|-------------| | --port | 3000 | HTTP port | | --db | ./arc-host.db | SQLite database path |

Auth Roles

| Role | Permissions | |------|-------------| | reader | Fetch checkpoints, blobs, refs | | writer | Reader + push checkpoints, blobs, update branches, create tags | | owner | Writer + admin (future: delete projects, manage tokens) |

API

All endpoints require Authorization: Bearer <token> except /health.

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /health | Health check (no auth) | | GET | /api/refs | List branches and tags | | POST | /api/checkpoints/batch | Fetch checkpoints by ID | | POST | /api/checkpoints/have | Check which checkpoint IDs exist | | POST | /api/checkpoints | Upload checkpoints | | POST | /api/blobs/batch | Fetch blobs by hash | | POST | /api/blobs/have | Check which blob hashes exist | | POST | /api/blobs | Upload blobs | | POST | /api/branches/cas | Compare-and-swap branch tip | | POST | /api/tags | Create a tag |

How It Works

arc-host is a dumb object store. It stores checkpoints and blobs as opaque data — all VCS logic (manifests, diffing, merging) lives in the Arc client. The only "smart" endpoint is /api/branches/cas, which atomically updates branch tips using compare-and-swap to handle concurrent pushes.

Data is stored in a single SQLite database with gzip compression.

Learn More

• Arc VCS — checkpoint-based version control
• Alvei — the team behind Arc