Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

jamstream host

Provision a session server and mint invites.

Usage: jamstream host [OPTIONS]

Ranks the provider's regions by measured latency and price, shows a cost preview, asks for confirmation, launches the machine, verifies it answers a real encrypted handshake, prints one invite per seat, and records the session in a local state file.

With --provider local (the default) there is nothing to rank or bill: the server starts as a process on this computer, the cost line reads that local sessions cost nothing, and the handshake check still runs against the real server. See Playing on the same network.

Options

FlagDefaultMeaning
--provider <PROVIDER>localProvider to host on: local, digitalocean, aws, or gcp. Local runs the server on this computer, with no credentials and no cost.
--region <REGION>picked by rankingRegion id to use, skipping the latency ranking. Local has one region, local.
--musicians <MUSICIANS>4Musician seats in the session, counting you. 1 to 10, where 1 hosts alone and 10 is the server's capacity. --musicians 4 mints your host invite plus 3 musician invites.
--listeners <LISTENERS>0Listener seats in the session; one listener invite is minted per seat. 0 to 20.
--hours <HOURS>3Expected session length in hours, for the cost preview. Does not limit the session.
--destinations <DESTINATIONS>0Stream destination count, for the egress estimate.
--port <PORT>43210UDP port the session server listens on.
--idle-min <IDLE_MIN>10Minutes without musicians before the server shuts itself down.
--max-hours <MAX_HOURS>12Hard cap on session length in hours. Invites expire at the cap.
--recordoffLet this session record. A local session's takes land as FLAC files in a recordings folder on this computer and the launch output prints its path; a cloud session needs --bucket, because the machine deletes itself at the end and a take on its disk goes with it.
--record-stemsoffAlso capture a stereo stem per musician alongside the mix, named for them. Implies --record.
--bucket <BUCKET>noneBucket a cloud session records to, in its own region. Implies --record. Proves the key can write, applies the retention rule, and saves the bucket beside the session record for jamstream recordings. Needs a storage key; see that page for the variables.
--retention <RETENTION>30dHow long the bucket keeps this session's takes: 7d, 30d, 90d, or forever. Applies to --bucket, and is enforced by the bucket's own lifecycle rule, so it keeps working after the machine is gone.
--artifact-url <ARTIFACT_URL>pinned into release buildsOverride the URL of the jamstreamd artifact the VM downloads at boot. Release builds pin their own server build, so hosting on a cloud normally needs no flag; a source build has no pin and must pass both artifact flags. Local mode downloads nothing.
--artifact-sha256 <ARTIFACT_SHA256>pinned into release buildsOverride the expected sha256 of the jamstreamd artifact. Must be passed together with --artifact-url; the VM refuses to start on a mismatch.
--yesoffSkip the launch confirmation.
--jsonoffEmit one JSON object instead of human-readable output.

Examples

A session on this computer, for the people in the room:

$ jamstream host --provider local --yes

The same session able to record, with the folder takes land in printed at launch:

$ jamstream host --record --yes

A two hour duo session (you and one other player) with two spare listener seats, on DigitalOcean, unattended:

$ jamstream host --provider digitalocean --musicians 2 --listeners 2 \
    --hours 2 --yes

The same launch from a source build, which has no pinned server artifact, names one explicitly:

$ jamstream host --provider digitalocean --musicians 2 --listeners 2 \
    --hours 2 --yes \
    --artifact-url https://your-host.example/jamstreamd \
    --artifact-sha256 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

The quickstart shows a full run end to end.

Notes

  • If JamStream-tagged machines already exist on the provider, they are listed with a warning before anything launches; run jamstream sweep if they are strays.
  • --record arms recording, it does not start it: the host presses Record in the session, and each Record to Stop is one take.
  • Finished takes are FLAC files named by date and time in the printed folder (record_dir in the --json output), and they stay there after jamstream end. See Recording a session.
  • --json prints the session id, address, invites, cost estimate, recording folder, and state file path as one object, for scripts.
  • The state file lands under your platform's data directory in jamstream/sessions/ and is what jamstream status and jamstream end read.