Host worlds for a team
Many worlds under one URL, each with its own token, and a console that shows them all.
A host serves many shared worlds by <org>/<world>. Every world keeps its own token and its own
history; the host keeps one admin token that provisions and removes worlds, and mounts the console
when it is installed beside it. This page runs a host on your machine and points an app at one of
its Worlds. Running this host needs no Volter platform account or cloud subscription; you supply
the machine and its network access. A hosted platform uses the same console, command and twin packages.
For orgs,
members and sign-in through your own provider (Okta, Entra, Google Workspace, GitHub) instead of
tokens, run the platform in front of the host: Self-host the platform.
The app
{ "name": "acme-web", "private": true, "type": "module", "dependencies": { "@octokit/rest": "^21" } }The app declares the credential it reads. The World issues a throwaway token for its GitHub account,
world; that account is separate from the platform org acme. The seed creates world/web through
Octokit before any issue is written. It can run again without creating a second repository.
GITHUB_TOKEN=import { Octokit } from '@octokit/rest';
const github = new Octokit({ auth: process.env.GITHUB_TOKEN });
const { data: { login: owner } } = await github.users.getAuthenticated();
try {
await github.repos.get({ owner, repo: 'web' });
} catch (error) {
if (error.status !== 404) throw error;
await github.repos.createForAuthenticatedUser({ name: 'web' });
}import { Octokit } from '@octokit/rest';
const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
const { data: issue } = await octokit.issues.create({ owner: 'world', repo: 'web', title: process.argv[2] ?? 'Launch checklist' });
console.log(`filed #${issue.number}`);npm install
npm install -g @volter/world
npm install -D @volter/twin-githubThe host
A host's directory holds the host, the console and the twin packages its worlds use, and one
bare world per <org>/<world>, laid out as the self-hosted image is. Install them, make the
first world, then serve the directory: the host prints the address it is reached at, its admin
token, and the console's URL. The admin token opens the host's own endpoints and nothing under a
world; keep it where you keep any team secret.
Give the shared World the same initial repository as the app, through the seed's SDK calls. Local seed data is not part of the app's later push.
GITHUB_TOKEN=import '../../../../acme-web/.volter/seed.ts';mkdir -p ../worlds && cd ../worlds
npm install @volter/world-host @volter/world-console @volter/twin-github
volter world init --bare acme/team --twins github --world acme/team
volter world up --world acme/team
volter world down --world acme/team
./node_modules/.bin/volter-host serve --dir . --port 4400 --console-port 4401 &
HOST_FRONT_PID=$!
cd ../acme-webhost ready http://127.0.0.1:4400 1 world
admin token tok_a_
console http://127.0.0.1:4401/-/console/Provision a world through the HTTP API
A second world does not need a shell on the host. POST /-/worlds with the admin token makes it,
and GET /-/worlds lists every world the host serves with its base URL and its token.
curl -s -X POST http://127.0.0.1:4400/-/worlds -H "x-volter-token: $(cat ../worlds/.volter-host/admin)" -H 'content-type: application/json' -d '{"org":"acme","world":"staging","vendors":["github"]}'
curl -s http://127.0.0.1:4400/-/worlds -H "x-volter-token: $(cat ../worlds/.volter-host/admin)""name":"acme/staging"
"name":"acme/team"Point your world at one of them
A world on a host is a shared world: remote add records its URL and token, and push sends
your changes to it as a changeset. Nothing about the app changes because the world moved onto a
host.
volter world init
volter remote add origin http://127.0.0.1:4400/acme/team --token "$(cat ../worlds/acme/team/.volter/token)"
volter world pull
volter world up
volter world run -- node file-issue.mjs
volter world changeset -m "The launch checklist"
volter world pushfiled #1
changeset the-launch-checklist 2 changes
pushed the-launch-checklist 2 changes → originThe console
Open the printed console URL, http://127.0.0.1:4401/-/console/ in this example, and paste the admin token: every world the host serves,
with a form to provision another. Open a world and its twins are listed; a twin opens on its log
and its tree, the same log volter world log prints. A world's own token opens the console on that
world alone.
Remove a world
DELETE /-/worlds/<org>/<world> stops the world and removes its directory.
curl -s -X DELETE http://127.0.0.1:4400/-/worlds/acme/staging -H "x-volter-token: $(cat ../worlds/.volter-host/admin)""removed":"acme/staging"Stop the host
The host was started in the background; stop it when you are done. Its directory keeps every
world, so the next volter-host serve brings them all back.
kill "$HOST_FRONT_PID"