Install and commands

Everything you might type: the install line and its options, the stuurman command, the few things run by hand in a Ship's folder, and a Ship built from source.

Installing

One line installs the stuurman command and a new Ship. It needs Docker with Compose, on macOS or Linux, amd64 or arm64.

curl -fsSL https://install.stuurman.io | bash

Or with Homebrew:

brew install twimba/stuurman/stuurman && stuurman install

The line downloads the command for your machine, checks it against its SHA-256 and puts it in /usr/local/bin, or in ~/.local/bin when that cannot be written. It never runs sudo. Then it runs stuurman install. Read the script first at install.stuurman.io/install.sh. The check finds a damaged download; it does not prove where the release came from.

Options go on to stuurman install, and a version can be chosen:

curl -fsSL https://install.stuurman.io | bash -s -- --name "Twimba" --port 9000

curl -fsSL https://install.stuurman.io | STUURMAN_VERSION=v0.3.0 bash

stuurman install checks that Docker runs, then makes a new Ship:

Its name: It asks Name your Ship:, or takes --name. 1 to 40 characters, changed later on the Settings page. An empty answer leaves it for the Bridge to ask.
Its ID: Two words it picks, such as brave-heron, that never change. The Ship's Docker Compose project is stuurman-<id>.
Its folder: ~/stuurman/<id>, or the one --dir gives: .env with a new secret key, compose.yaml, and data/helm and data/ship.
Its port: 43560 for the first Ship and the next free one for each further Ship, or --port.

It starts the Ship and prints the setup code and the Bridge's address; on a Mac it opens the address, unless you give --no-open. Everything else is set on the Bridge: you never edit a file to configure the Ship. Back up .env: without its key the Ship's secrets cannot be read.

/usr/local/bin/stuurman        the command (or ~/.local/bin/stuurman)
~/.config/stuurman/ships/      the list of the Ships on this machine
~/stuurman/brave-heron/        one Ship's folder
├── .env
├── compose.yaml
└── data/
    ├── helm/
    └── ship/

The `stuurman` command

It works on this machine's Docker, from any folder. With DOCKER_HOST or DOCKER_CONTEXT set in your shell, most commands refuse and say which to unset.

stuurman install: Installs a new Ship and starts it: --name, --port, --dir, --no-open. It never touches a Ship that exists.
stuurman list: The Ships on this machine: name, ID, running or stopped, version, address and folder, with * before the default one.
stuurman use <ship>: Makes that Ship the default.
stuurman start: Starts the Ship's containers and gives the Bridge's address.
stuurman stop: Stops the Ship's containers. This is not all stop.
stuurman status: The folder, whether the containers run, the versions, the address and the Ship's state.
stuurman logs: The Helm's log; -f follows it.
stuurman doctor: Checks the data folder, free space, the HALT flag, Docker, the crew network and the ports of the gateways.
stuurman upgrade: Brings the command and the Ship to the latest version; --all for every Ship, --now not to wait for a turn that is running (see Upgrading).
stuurman remove <ship>: Stops that Ship and takes it off the list, after asking. Its folder, data and key are kept.
stuurman adopt <folder>: Puts a Ship that is installed already on the list, such as one built from source, and changes nothing else.
stuurman version: The version of the command and, when it runs, of the Helm.
stuurman help: Lists the commands.

Several Ships on one machine

Run stuurman install again for another Ship: one you rely on beside one you try things on, say. Ships share nothing: each has its own folder, data, key, port, containers and networks, its own Slack workspace and its own crew. All stop halts one Ship and leaves the others underway.

stuurman install --name "Twimba"
stuurman install --name "Trials"
stuurman list

A command acts on the Ship that --ship <ship> names, else the Ship whose folder you are in, else the default Ship, else the only one. --ship takes the ID, the start of one, or the name.
Each Bridge is localhost on its own port. Your passkeys carry their Ship's name; a passkey of one Ship is never accepted by another.
stuurman remove deletes no file. To delete a Ship for good, remove its folder yourself afterwards.

By hand, in the Ship's folder

A few things have no stuurman command. Run them in the Ship's folder, and name the Ship every time with its Docker Compose project, stuurman-<id>: without it, Compose makes up a project from the folder's name, and that is not your Ship. stuurman list shows each Ship's ID and folder.

cd ~/stuurman/<id>
docker compose -p stuurman-<id> run --rm --no-deps -T helm <command>

The commands of the Helm worth knowing, each in place of <command>:

allstop: All stop, without the Bridge or Slack. underway resumes.
bridge reset-passkey: Removes the Captain's passkey and prints a new setup code. It works whether or not the Helm runs.
settings reset: Puts the settings of the Settings page back to the defaults, with the Helm stopped. It needs no key.
developer off: Turns the developer features and the Database page off, also while the Helm runs.
secret show claude_token: Prints the stored Claude token.
safe new-authority: Makes a new certificate authority for the safe when the stored one cannot be read. With the Helm stopped; it needs the key in .env.
doctor, version, origin: The checks of stuurman doctor; the version; the Bridge's address as the Helm uses it.

For example, all stop for the Ship brave-heron:

docker compose -p stuurman-brave-heron run --rm --no-deps -T helm allstop

Reaching the Bridge from another device

The Bridge is published on 127.0.0.1 only, and nothing else of the Ship faces the internet. To reach it from another device, put it behind a private VPN such as Tailscale and change the one line STUURMAN_BRIDGE_ORIGIN in the Ship's .env to the https address it gives you. A passkey is tied to the address, so the new address needs a new passkey (bridge reset-passkey, above).