Capsium

Documentation

Everything about capsules, in one place

The Capsium ecosystem is documented end to end: the standard that defines the format, generated API references for the Ruby and TypeScript implementations, and a five-minute walk from an empty folder to a served capsule.

Start here

Pick your path

Read the standard

CC 62001 — the normative Capsium package format, hosted here as HTML and PDF.

Open

Try the playground

Pack, inspect, and serve a capsule entirely in your browser — nothing to install.

Open

Ruby API — capsium gem

RDoc for the reference implementation: Capsium::Package, Packager, Reactor, and Registry.

capsium 0.3.0 · RDocOpen

TypeScript API — @capsium/*

TypeDoc for @capsium/core, @capsium/packager, @capsium/reactor-node, and @capsium/swsws.

0.2.0 · TypeDocOpen

Tutorial

Your first capsule

From an empty folder to a verified, served capsule with the capsium CLI (Ruby gem, version 0.3.0).

  1. Install the CLI

    Capsium's reference implementation ships as a Ruby gem:

    $ gem install capsium

  2. Lay out a tiny site

    A capsule starts as a plain directory. Make one with two files:

    $ mkdir my-site

    my-site/index.html

    <!doctype html>
<h1>Hello from my first capsule</h1>

    my-site/metadata.json

    {
  "name": "my-site",
  "version": "1.0.0",
  "description": "My first Capsium capsule",
  "guid": "https://example.com/my-site",
  "uuid": "3f6b0d2a-9c4e-4b1a-8e7d-2c5f9a1b0e3d",
  "license": "MIT"
}

    metadata.json is the one file you author: name, version, description, guid, and uuid are required by the canonical schema; license is recommended. The packager generates the manifest, routes, and checksums for you.

  3. Pack the capsule

    From the directory containing my-site/:

    $ capsium package pack -f my-site/

    This writes my-site-1.0.0.cap next to the folder — a ZIP archive with every file fingerprinted in security.json. The -f flag lets you re-pack over an existing capsule.

  4. Validate it

    Check structure, configs, and integrity before serving:

    $ capsium package validate my-site-1.0.0.cap

  5. Serve it

    Start the built-in reactor (it verifies the capsule first, then listens on port 8864):

    $ capsium reactor serve my-site-1.0.0.cap

    Browse to http://localhost:8864 for your page, and to http://localhost:8864/api/v1/introspect/metadata to see the reactor report the capsule's own metadata as JSON.

Build on it

Write a reactor in 5 minutes

A reactor is anything that verifies a capsule and serves it. With @capsium/reactor-node it is five lines of Node.js — checksum and signature verification on load, content and dataset routes, and the introspection API included.

$ npm i @capsium/reactor-node

The @capsium/* packages are pending publication on npm; until they land, install them from source at capsiums/capsium-js. The full API is in the TypeScript reference.

reactor.mjs

import { createServer } from 'node:http';
import { createReactor } from '@capsium/reactor-node';

const handler = await createReactor({ package: './my-site-1.0.0.cap' });
createServer((req, res) => void handler(req, res)).listen(8864);