How To

Step-by-step developer guides for building with and on the PointSav platform. Each guide addresses a specific task — follow it start to finish, then refer back to the related architecture articles when you need the underlying theory.

For the concepts behind each guide, start in architecture or patterns. For platform architecture overview, see totebox-orchestration-development.

Getting started

The foundation: authenticate your device, install the toolchain, and open your first session.

Pair a new device — enroll a machine using machine-based authorization; no username or password required
Install the development toolchain — set up Rust and the staging-tier commit helper on a workspace VM
Open your first Totebox session — navigate to an archive, read your inbox, and start contributing
Explore the console — tour the three-zone TUI, the status bar, and the F-key slots

Working in the console

Use the platform's terminal interface and its built-in Cartridges.

Navigate the console TUI — status bar fields, F-key switching, universal key bindings
Use the F-key model — default slot assignments, Cartridge architecture, Email / SLM / Input Machine
Read the command ledger — view WORM ledger entries from the F12 LEDGER tab and export to C2SP format
Run your first SLM query — submit an inference prompt in F9 and read the Doorman health dashboard

Records & storage

Work with the WORM audit ledger and entity data.

Read and write Totebox archives — session start reading protocol, commit flow, draft staging, cross-archive mailbox
Verify a WORM ledger entry — confirm hash-chain integrity and validate against a signed Sigstore checkpoint
Query the DataGraph — search named entities, navigate relationships, handle Tier A outages
Export structured data — four export paths: DataGraph, wiki Markdown, GeoJSON, ledger tiles

Machine authorization

Credential and access control operations.

Pair a new device — the core enrollment flow; all four pairing types (ADMIN, INPUT, USER, INTERFACE)
Enroll a PPN node — register a compute node with the fleet controller and verify heartbeat enrollment
Issue a capability token — generate an Ed25519 token for a device or service at a specific scope
Rotate keys and tokens — replace a keypair and its token with a new one through the three-phase rotation sequence
Authenticate binary downloads — verify and fetch signed binaries from the private distribution endpoint

Multi-entity scale

Manage multiple tenants, users, and fleet nodes.

Configure a tenant namespace — register a tenant, set quotas, verify isolation, issue the root credential
Scale user access tiers — promote users between READ / USER / INPUT tiers and bulk-update a team
Add a node to a running fleet — enroll a second node without interrupting existing fleet operations

Integration & data

Connect external data pipelines and build location-intelligence applications.

Build a co-location map — query the GIS engine API and render a MapLibre cluster layer
Connect to the OSM data pipeline — write a chain ingest YAML, run the ingest script, and rebuild the cluster layer
Federate archives via content mounts — mount wiki content from one archive into a second instance using declarative TOML mounts
Use declarative knowledge mounts — add a secondary content repository to a running wiki instance via knowledge.toml

Self-hosting

Deploy the platform on your own infrastructure.

Self-host a deployment — provision a Totebox Archive on a supported compute node
Configure the Doorman gateway — set tier upstream addresses, circuit-breaker thresholds, and verify the health endpoint
Deploy a knowledge instance — build and start app-mediakit-knowledge pointed at a local content repository
Run local SLM inference — start the SLM service, verify Doorman Tier B, and submit inference requests from the console or API