Volter World

Use the hosted product

Sign the command into a running platform, make your app's World there from its folder, and push to it.

Before you start

You need a reachable platform URL, an account on it, and permission to use the intended organization. Use the URL supplied by your team or platform operator. The public product and documentation sites are not platform endpoints. Volter cloud signup is available only when the product site offers it; this walkthrough alone does not establish that a hosted service is available.

For a free local World with no account, start with getting started. For a team without a platform, share a World serves one on your own machine. Self-host the platform adds organizations and sign-in on your own servers, without a Volter cloud subscription.

The hosted product runs the same Worlds as a self-hosted platform. Your organization holds Worlds, and the volter command signs in as you. The remote add, push and log commands below work with either platform.

On the platform

Sign in on your platform and create an organization, or use one you have permission to join. This example uses acme; replace it with your actual organization rather than creating one to work around missing access. The World is made from your app's folder below, with the twins your app uses.

Set VOLTER_PLATFORM in your shell to the platform URL you were given. If you choose personal-token sign-in, create the token under Account and keep its value in VOLTER_TOKEN in that shell. These are platform credentials, separate from the throwaway GitHub credential the local app uses.

The app

package.json
{ "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.

.env.example
GITHUB_TOKEN=
.volter/seed.ts
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' });
}
file-issue.mjs
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-github

Sign the command in

For browser sign-in, run volter login "$VOLTER_PLATFORM". The command prints a link and code; you approve that code in your browser. A coding agent cannot approve your sign-in. If your account or organization is missing, ask the platform's operator for access.

If you created the personal token above, use this alternative:

volter login "$VOLTER_PLATFORM" --token "$VOLTER_TOKEN"
signed in
as ada@acme.test
orgs       acme

The CLI keeps the token in your config directory with the platform's address. A remote named org/world then resolves through that platform. volter whoami shows the signed-in platform, person and organizations, and volter logout revokes its token.

Make the org's World from here

Your app's world is local; its origin is the org's hosted world. volter world init finds the vendors your app uses; remote add makes the org's World on the platform with the same twins (--create; without it, the command asks at a terminal), then asks the platform for its address and a key made for this command, so nothing but your personal token is ever typed. Once the World exists, the same remote add links it on a teammate's machine, and volter world pull brings what was pushed to it into their World. With only one org, remote add origin team --create names it for you. The platform's Create World does the same for a person without a terminal.

volter world init
volter remote add origin acme/team --create
made     acme/team
remote   origin
through

volter open opens the World's dashboard, signed in through the platform.

Write, cut a changeset, push

The app runs against your local world as always; a changeset gathers what it wrote; push sends it to the hosted world, which answers with a receipt per twin.

volter world up
volter world run -- node file-issue.mjs
volter world changeset -m "The launch checklist"
volter world push
pushed

The World's page (Open, on the platform) shows the changeset in its Changes and Activity. Your teammates clone from the same origin — see Work from a shared world.

volter world down

Keep a World to some of the org

Every member of an org reaches its Worlds until an admin says otherwise. On the org's Worlds page, Manage access… in a World's menu keeps it to the members you tick; admins always reach it, and the World shows Restricted. A member it leaves out no longer sees it, cannot open it, and gets no key to it; the keys they already held there are revoked when you save, and so are the previews those keys made. Everyone in the org opens it again. An org token acts as the org, so CI keeps working. The same setting is GET and PUT /-/worlds/<org>/<world>/access in the platform API.

View Markdown source

On this page