sha256:4d88c02489c92231…

Your application’s files, stored once and read every way.

vola is a self-hosted, multi-tenant, content-addressable file service: upload or resume an upload, stream with Range, get thumbnails and OCR, keep folders and versions, hand out share links, and encrypt per file.

docker compose -f docker-compose.yaml up -d --build
A thumbnail of aurora.jpg, 256 pixels square
GET …/thumb/256202 Accepted generating200 OK ready, 1960 bytes

One file, every way to read it

One upload to the live examples instance, then what vola answered. These are recordings of real requests, cut to fit the column: nothing here was typed by hand.

  1. Upload it

    The file is stored under the SHA-256 of its bytes. The same bytes uploaded twice, by anyone, are one blob on disk.

    POST /vola/files/demo/00000000 HTTP/1.1
    Authorization: Bearer $KEY
    
    <multipart: file=aurora.jpg, 41167 bytes>
    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "id": "01a19fd3",
      "hash": "4d88c02489c92231…",
      "size": 41167,
      "filename": "aurora.jpg",
      "mime_type": "image/jpeg",
      "kind": "image",
      "encryption": "none",
      "processing_status": "PENDING"
    }
  2. Ask what it is

    The worker is already rendering thumbnails, so processing_status moves on its own.

    GET /vola/files/demo/00000000/01a19fd3/info HTTP/1.1
    Authorization: Bearer $KEY
    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    
    {
      "id": "01a19fd3",
      "hash": "4d88c02489c92231…",
      "size": 41167,
      "filename": "aurora.jpg",
      "mime_type": "image/jpeg",
      "kind": "image",
      "encryption": "none",
      "processing_status": "RUNNING"
    }
  3. Read part of it

    A Range header gets you a 206 with just those bytes: bytes 8192-16383/41167. It's how video seeks and how a broken download picks up where it stopped.

    GET /vola/files/demo/00000000/01a19fd3 HTTP/1.1
    Authorization: Bearer $KEY
    Range: bytes=8192-16383
    HTTP/1.1 206 Partial Content
    Content-Type: image/jpeg
    Content-Length: 8192
    Content-Range: bytes 8192-16383/41167
    Accept-Ranges: bytes
    ETag: "4d88c02489c92231…"
    Cache-Control: private, no-cache
    Content-Disposition: inline; filename="aurora.jpg"
    
    <8192 bytes of image/jpeg>
  4. See a thumbnail

    Rendering happens off the request path. The first answer is a 202 with a grey placeholder, and the next one is the image. Your client has to tell them apart, because 202 counts as success.

    GET /vola/files/demo/00000000/01a19fd3/thumb/256 HTTP/1.1
    Authorization: Bearer $KEY
    HTTP/1.1 202 Accepted
    Content-Type: image/webp
    Content-Length: 44
    Cache-Control: no-cache
    X-Thumbnail-Status: generating
    
    <44 bytes of image/webp>
    HTTP/1.1 200 OK
    Content-Type: image/webp
    Content-Length: 1960
    ETag: "4d88c02489c92231….thumb-256-cover.webp"
    Cache-Control: private, max-age=86400
    X-Thumbnail-Status: ready
    
    <1960 bytes of image/webp>
  5. Hand out a link

    Anyone with the link can open the file without a key. It can carry a password, an expiry and a download cap, and you can revoke it.

    POST /vola/shares HTTP/1.1
    Authorization: Bearer $KEY
    Content-Type: application/json
    
    {
      "file_id": "01a19fd3",
      "expires_at": "2026-11-04T05:13:03Z",
      "max_downloads": 3
    }
    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "file_id": "01a19fd3",
      "has_password": false,
      "expires_at": "2026-11-04T05:13:03.000Z",
      "max_downloads": 3,
      "download_count": 0,
      "token": "KYHHic7w…",
      "url": "https://examples.stage.vol-a.com/vola/s/KYHHic7w…"
    }
    HEAD /vola/s/KYHHic7w… HTTP/1.1
    HTTP/1.1 200 OK
    Content-Type: image/jpeg
    Content-Length: 41167
    Accept-Ranges: bytes
    ETag: "4d88c02489c92231…"
    Cache-Control: private, no-store
    Content-Disposition: inline; filename="aurora.jpg"
    X-Robots-Tag: noindex, nofollow
  6. List it with everything else

    The same file is a row of the files UDC collection, which you can filter, sort, page and subscribe to.

    POST /vola/udc/list HTTP/1.1
    Authorization: Bearer $KEY
    Content-Type: application/json
    
    {
      "collection": "files",
      "filter": {
        "and": [
          {"field": "instance_type", "op": "eq", "value": "demo"},
          {"field": "instance_id", "op": "eq", "value": "00000000"},
          {"field": "filename", "op": "eq", "value": "aurora.jpg"}
        ]
      },
      "sort": [{"field": "created_at", "dir": "desc"}],
      "page": {"limit": 1}
    }
    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    
    {
      "rows": [
        {
          "id": "01a19fd3",
          "filename": "aurora.jpg",
          "kind": "image",
          "size": 41167,
          "hash": "4d88c02489c92231…",
          "processing_status": "DONE",
          "thumb_url": "/vola/files/demo/00000000/01a19fd3/thumb/256",
          "download_url": "/vola/files/demo/00000000/01a19fd3"
        }
      ],
      "total": 2
    }
That file as the server rendered it: every size at its true pixel size, then each crop.
aurora.jpg at 64 pixels64
aurora.jpg at 128 pixels128
aurora.jpg at 256 pixels256
aurora.jpg at 512 pixels512
aurora.jpg, crop cover, 256 pixels256 ?crop=cover
aurora.jpg, crop fit, 256 pixels256 ?crop=fit
aurora.jpg, crop attention, 256 pixels256 ?crop=attention

The examples, live

A running vola with a demo tenant and a read-only key for you. Nothing to install or sign up for. You can upload, share and encrypt there; what you leave is purged after a day.

Open the live examples

  • Browse

    /examples/browse

    Folders, thumbnails and the row menu over the demo files. The list stays live over a WebSocket, so an upload elsewhere appears here.

  • Upload

    /examples/upload

    One multipart POST under 1 MiB, the resumable protocol above it, with progress, cancel and resume.

  • Thumbnails

    /examples/thumbnails

    Every size and crop of one file. Regenerate drops the renditions so you can watch 202 become 200.

  • Range & streaming

    /examples/streaming

    A video and an audio element playing from vola, and a Range probe showing the 206 the page itself got.

  • Share

    /examples/share

    Make a link with a password, an expiry and a download cap, open it in a new tab, then revoke it.

  • Encrypted files

    /examples/encrypted

    Tenant-encrypted files that read as usual, and a private folder behind a PIN that counts down and locks.

  • API

    /examples/api

    The routes behind these pages and curl commands with the demo key filled in.

Encrypted at rest, still seekable

A copy of the disk, the database and the backups shows who stored how much and when, and nothing of the content: no file name, type, bytes, thumbnail or OCR text.

Every encrypted file gets its own random key and is sealed in 1 MiB segments, so a Range read decrypts only the segments it touches, and changing who can open a file rewrites 64 bytes, never the blob.

How the keys fit together

The JSV v1 encrypted blobA 24-byte header holding the magic, version, segment size, nonce prefix and plaintext length, followed by segments of 1 MiB. Each segment is AES-256-GCM ciphertext with a 16-byte tag. The nonce is the prefix and the segment index. The additional authenticated data is the header, the file id, the index and a last-segment flag.header24 Bmagic3 Bver1 Bsegment_size4 Bnonce_prefix8 Bplaintext_length8 Bblobsegment 01 MiB + tagsegment 11 MiB + tagsegment n−1≤ 1 MiB + tag⋯segment ict_i ∥ tag_i = AES-256-GCM(FK, nonce_i, plaintext, aad_i)nonce_i = nonce_prefix ∥ iaad_i = header ∥ file_id ∥ i ∥ last
Three ways to hold the key, chosen per file at upload
ProviderChoose it whenThe keyA request carries
tenantDumps and backups should be useless without the server's key, and your application has no per-user secret. The usual choice.A key line in VOLA_KEY_FILE, derived per tenantNothing
keyringA person's private files that even the operator must not open.A master key per person, behind a 6-digit PIN and a recovery keyX-Vola-Unlock, a short-lived token
callerServer to server, when you already manage keys and want vola to keep none.A 32-byte key per request, never storedX-Vola-Content-Key

The API

Plain HTTP under one prefix, /vola. A key belongs to one tenant and holds scopes; another tenant's file is a 404, never a 403.

These commands work as written against the live examples, with the key that instance gives everyone.

Every route, with its answers and error codes

RouteWhat it does
POST /files/:type/:idUpload, multipart and streamed
POST /uploadsStart a resumable upload (tus 1.0)
GET /files/:type/:id/:fileIdDownload, with Range, HEAD and ETag
GET …/:fileId/thumb/:sizeA WebP thumbnail; 202 while it renders
GET …/:fileId/info?ocr=fullThe text the worker read
GET /folders/:type/:id[/*path]One level of a folder
POST /sharesA share link: password, expiry, download cap
GET /s/:tokenOpen a share, no key
POST /udc/listFilter, sort and page the files collection
GET /udc/subscribeLive rows over a WebSocket
POST /keyrings/me/unlockOpen a PIN-protected keyring
# The examples instance hands its read-only visitor key to anyone who asks.
VOLA=https://examples.vol-a.com/vola
KEY=$(curl -s $VOLA/examples/config | jq -r .api_key)
# The images folder of the demo instance, through the UDC `files` collection.
curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
$VOLA/udc/list -d '{
"collection": "files",
"filter": {"and": [
{"field": "instance_type", "op": "eq", "value": "demo"},
{"field": "folder_path", "op": "eq", "value": "images"}
]},
"sort": [{"field": "filename", "dir": "asc"}],
"page": {"limit": 3}
}' | tee list.json | jq -r '.payload.rows[] | [.filename, .size, .mime_type] | @tsv'
What it printed
aurora.jpg 41134 image/jpeg
geometry.png 34016 image/png
grid.png 54518 image/png
# The first kilobyte of the first of them, and the headers that came back.
FILE=$(jq -r '.payload.rows[0].download_url' list.json)
curl -s -o /dev/null -D - -H "Authorization: Bearer $KEY" -H "Range: bytes=0-1023" \
"https://examples.vol-a.com$FILE" | grep -iE '^(HTTP|content-range|accept-ranges)'
What it printed
HTTP/2 206
accept-ranges: bytes
content-range: bytes 0-1023/41134

Start where you are

Run your own in Docker or on one SQLite file, call it from a backend, draw it in React, or mount it inside the Fastify application you already have. The commands were run as shown and the programs compile against this repository.

Docker with Compose: the server, the worker, PostgreSQL and Redis, with named volumes.

Terminal
git clone https://github.com/digital-cube/jsvola.git && cd jsvola
echo "POSTGRES_PASSWORD=$(openssl rand -hex 16)" > .env
docker compose -f docker-compose.yaml up -d --build
until curl -sf localhost:8300/vola/health/ready; do sleep 2; done
docker compose -f docker-compose.yaml exec vola vola create-tenant --slug acme --name "Acme Inc"
docker compose -f docker-compose.yaml exec vola vola create-key --tenant acme --name backend \
--env live --scopes files:read,files:write,folders:read,folders:write,shares:write
export KEY=vola_live_... # what create-key printed
export TICKET=$(uuidgen | tr A-F a-f)
curl -s -H "Authorization: Bearer $KEY" -F file=@README.md \
localhost:8300/vola/files/tickets/$TICKET | tee file.json | jq '{filename, size, mime_type, kind}'
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $KEY" -H "Range: bytes=0-9" \
localhost:8300/vola/files/tickets/$TICKET/$(jq -r .id file.json)
What it printed
{"status":"ok","checks":{"database":"ok","redis":"ok"}}
created tenant acme (Acme Inc) id=01a19fc9
created key vola_live… "backend" for tenant acme
id 01a19fc9
scopes files:read, files:write, folders:read, folders:write, shares:write
Plaintext key (shown ONCE — store it now, it cannot be recovered):
vola_live_...
{
"filename": "README.md",
"size": 11945,
"mime_type": "text/markdown",
"kind": "text"
}
206

Step by step, with what each one does

Packages

Six packages and one image, all on the same version. Take only what you need.

About each package

Changelog

PackageVersionOn npmUses
@vol-a/coreZod schemas, inferred types and helpers shared by server, CLI and clients.1.1.0not on npm yetNone
@vol-a/lookupsControlled vocabularies from YAML (file kinds, processing statuses and kinds, share scopes, OCR languages, encryption modes), CSV translations, candidate recording and TypeScript/Zod codegen.1.1.0not on npm yetNone
@vol-a/serverFastify plugin and standalone server, Drizzle on PostgreSQL or SQLite, Redis, tenant isolation, API key auth, UDC collections.1.1.0not on npm yet@vol-a/core@vol-a/lookups
@vol-a/cliTenants, API keys, migrations and the lookups vocabulary for @vol-a/server.1.1.0not on npm yet@vol-a/client@vol-a/core@vol-a/lookups@vol-a/server
@vol-a/clientA fetch-based, dependency-light client for the @vol-a/server API — files, folders, resumable uploads, shares, keyrings, stats — for Node 24+ and browsers.1.1.0not on npm yet@vol-a/core
@vol-a/reactVolaProvider, a live file browser on @jsudc/react, uploads with resumable progress, thumbnails, the keyring PIN gate with auto-lock, and the share dialog.1.1.0not on npm yet@vol-a/client@vol-a/core

Read from packages/*/package.json when this site was built (): one version, 1.1.0, for all 6. Licence: MIT. On npm: the npm registry, asked in the same build: the newest version of each package and when it was published; none is on npm yet.

The imagev1.1.0 released

ghcr.io/digital-cube/jsvola:<version>

latest
the newest tag
edge
main
sha-<short>
one commit