Box-run demo

Runtime: python — a stdlib-only Python 3.11 environment inside the box.

A minimal demo, not a real project

This is here to give you the idea in as few steps as possible. The box it runs prints a line and exits: enough to watch the trust chain work end to end, and deliberately not an example of what is worth packing. For boxes that carry something real — a language model, ffmpeg, a dataset — see the other demos.

Try it now

This demo is only about running a box someone else built and signed. Nothing is compiled, nothing is resolved, and no toolchain is installed — which is the point: consuming a box asks far less of a machine than building one.

Open it in GitHub Codespaces for an instant VM with the repository ready and a walkthrough to follow:

Open in GitHub Codespaces

Runs the Linux x86_64 CPU demo using your GitHub Codespaces account.

To go the whole way instead — from an empty project to a box you built yourself — see the end-to-end demo.

Local setup

Building a box needs pixi and conda-pack. But consuming does not:
If you only want to see what a box is, and how to run it, try this public demo.

You can find the demo box GitHub release here.

Downloads

Download the demo for your system:

macOS (Metal)	Linux (CPU)	Windows (CPU)
macos-aarch64-metal	linux-x86_64-cpu	windows-x86_64-cpu

NOTE

The file you download (eg. hello-box-1.0.0-macos-aarch64-metal.zip) is NOT the demo box — it is a container, named so you can tell which machine it is for, holding the box together with two ready-to-run examples.

The demo box is the .zip inside it under box/, next to its .release.json. Do not unzip that one: it's ready to run. Leave both named as they are and side by side, because that is how verify finds the box.

Run the box

Once you have downloaded the demo, follow these steps:

1. Unpack the demo into a folder of its own:

unzip hello-box-1.0.0-<target>.zip -d scrollcase-demo
cd scrollcase-demo

box/ holds 2 files: the demo box .zip to run, and its matching .release.json. Beside it you already have run-box.ts and run_box.py — nothing to retype.

---

2. Download the demo public key, next to the box rather than inside it:

mkdir keys
curl -o keys/example-signing-public.json \
  https://raw.githubusercontent.com/suffro/scrollcase/main/examples/keys/example-signing-public.json

or alternatively here's its GitHub link: example-signing-public.json

Why the key lives outside the box

A signature only proves where something came from if the key does not travel with it. Keeping the key in its own folder — and downloading it from the repository rather than the release — is the habit to carry into a real project, where the key will not be a demo key.

---

3. Verify and run the box:

This path needs the CLI, and nothing else — no pixi, no conda-pack, no build:

npm install -g scrollcase

scrollcase verify box/*.release.json --public-key keys/example-signing-public.json
scrollcase run    box/*.release.json --public-key keys/example-signing-public.json

scrollcase verify (Get-ChildItem box\*.release.json).FullName --public-key keys\example-signing-public.json
scrollcase run    (Get-ChildItem box\*.release.json).FullName --public-key keys\example-signing-public.json

The box/*.release.json above is a real shell glob, not a placeholder — your shell replaces it with the one release document in the folder. PowerShell does not expand globs for a command like this, which is why it needs Get-ChildItem. Either way you can always type the file name you see after unzipping. You never name the box archive: verify finds it beside the release document, under the hash that document commits to.

What just happened

verify checks the signature, the archive's size and hash, the entry names and manifest agreement, and works on any machine. run extracts the box to a temporary directory and executes its entry point with the interpreter inside it — so it needs a machine matching the box's target. The box output makes that outcome explicit instead of presenting its temporary extraction paths as the demo:

Hello from inside a Scrollcase box!

  signed -> verified -> relocated -> running

Success: the box's own Python runtime executed this program.
No dependencies were resolved or installed to make this run.

  Runtime  Python 3.11.15
  Host     Linux / x86_64

The final two lines reflect the box you downloaded and the matching machine running it.

Run it from your own app

The CLI is the quickest way to see a box work, but an application does not shell out to it: every consumer exposes the same verify-then-run semantics as a library. run-box.ts and run_box.py are already in the folder you unpacked, so this is two commands, not a copy-paste.

npm install
npx tsx run-box.ts

run-box.ts — the file you just ran

/**
 * Runs the demo box through the typed Node consumer.
 *
 * SETUP (once, from this folder):
 *   npm install
 *
 * RUN:
 *   npx tsx run-box.ts
 *
 * The public key is not shipped with the box: download it first, as the guide describes. A
 * signature only proves where something came from if the key does not travel with it.
 */
import { readdirSync } from 'node:fs';
import { join } from 'node:path';
import { runBox } from 'scrollcase/consumer';

// The release document is named for its own SHA-256, so it is found rather than hard-coded. The box
// archive is never named here: the consumer resolves it beside this document, under the hash the
// document commits to.
const release = readdirSync('box').find((name) => name.endsWith('.release.json'));
if (!release) throw new Error('No .release.json in box/ — unpack the downloaded archive first.');

const result = await runBox(join('box', release), {
  publicPath: 'keys/example-signing-public.json',
  stdout: 'inherit',
  stderr: 'inherit',
  // Fires after the signature, the archive hash and the manifest have been checked, and before the
  // box interpreter starts, so an application can show what it is about to run without repeating
  // the trust chain itself.
  onPrepared: ({ boxId, version, targetId }) => {
    console.log(`Running ${boxId} ${version} (${targetId})`);
  },
});

if (result.signal) console.error(`Box exited after ${result.signal}.`);
process.exitCode = result.exitCode ?? 1;

python -m pip install scrollcase-consumer
python run_box.py

run_box.py — the file you just ran

"""Runs the demo box through the typed Python consumer.

The Python consumer is published separately on PyPI, and needs no Node at all.

SETUP (once):

    python -m pip install scrollcase-consumer

RUN (from this folder):

    python run_box.py

The public key is not shipped with the box: download it first, as the guide describes. A signature
only proves where something came from if the key does not travel with it.
"""

from __future__ import annotations

import sys
from pathlib import Path

from scrollcase_consumer import PreparedBox, run_box

# The release document is named for its own SHA-256, so it is found rather than hard-coded. The box
# archive is never named here: the consumer resolves it beside this document, under the hash the
# document commits to.
releases = sorted(Path("box").glob("*.release.json"))
if not releases:
    raise SystemExit("No .release.json in box/ — unpack the downloaded archive first.")


def report(prepared: PreparedBox) -> None:
    """Runs after verification and before the box interpreter starts."""

    # Flushed because the box writes straight to this process's stdout, and an unflushed line would
    # appear after the output it introduces.
    print(
        f"Running {prepared.box_id} {prepared.version} ({prepared.target_id})",
        flush=True,
    )


result = run_box(
    releases[0],
    public_key_path="keys/example-signing-public.json",
    on_prepared=report,
)

if result.signal:
    print(f"Box exited after {result.signal}.", file=sys.stderr)
raise SystemExit(result.exit_code if result.exit_code is not None else 1)

runBox verifies the signature, extracts to a private temporary directory, executes, and cleans up after itself — the same chain scrollcase run performs, minus the terminal. onPrepared fires after verification and before execution, which is how an application shows what it is about to run without repeating the trust chain itself.

Neither file names the box archive. Both find the release document by its suffix and let the consumer resolve the archive beside it, under the hash that document commits to.

The Python package and the Rust crate are published separately: npm install scrollcase installs neither, and pip install scrollcase-consumer or cargo add scrollcase-consumer needs no Node at all. There is no Rust file in the folder, but the same two calls verify and run this same box from a native application. Full surface in the Library APIs reference.

The demo key is a demo key

Those boxes are signed with a key that exists only for the example. It signs nothing else and no trust chain depends on it. A signature from it means the example is intact — nothing more.

---

4. Check out the results, that's it.

At this point the folder looks like this — the box untouched in its own directory, the key in another, the runnable examples above both:

scrollcase-demo/
├── box/                               # from the download, left exactly as it arrived
│   ├── <archive sha256>.zip
│   └── <document sha256>.release.json
├── keys/                              # step 2, from the repository — never from the release
│   └── example-signing-public.json
├── run-box.ts                         # from the download
├── run_box.py                         # from the download
├── package.json                       # from the download
└── README.md                          # from the download

Everything except keys/ came out of the one file you downloaded. The key is the deliberate exception, and the reason is above.