Stuurman

Quickstart

From nothing to a first conversation with the First Mate. Have the requirements ready.

  • 4steps
  • 30minutes, about
  • 1command to start

  1. Install

    One command.

    Install macOS · Linux · needs Docker 
    curl -fsSL https://install.stuurman.io | bash

    Installs the stuurman command and a new Ship in ~/stuurman. Read the install script first.

    It asks for a name for your Ship, starts it, and prints a setup code and the Bridge's address. Keep both for the next step.

    The curl line checks the download against its SHA-256 and never runs sudo. The check finds a damaged download; it does not prove where the release came from. With Homebrew: brew install twimba/stuurman/stuurman && stuurman install.

  2. Open the Bridge

    One code, one passkey.

    Open the Bridge at http://localhost:8080, or at the address the installer printed. Enter the setup code and press Register passkey.

    You are now the Captain. There is no password to remember.

    Use localhost, not 127.0.0.1: a passkey is tied to the address.

  3. Fit out the Ship

    Three parts, and the Bridge lists them.

    The Overview's "Fit out the Ship" lists these three parts, in this order, and checks each one as you finish it.

    Claude

    On your own machine, run claude setup-token. Paste the token into "Claude token" and press Save token.

    The Bridge never shows it again. It gives full use of your subscription, and anyone who has the host and the Ship's .env file can read it.

    Slack

    Create two public channels, #bridge and #ships-log. Then, under "Connect Slack":

    1. On api.slack.com/apps, under Your App Configuration Tokens, generate a token for your workspace. Paste both values and press Save.
    2. Press Create the Helm app, then Get the install link, and press Allow in Slack.
    3. On the app's Basic Information page, under App-Level Tokens, generate a token with the connections:write scope. Paste it as "App-level token" and press Save and check.
    4. Enter your Slack member ID (your profile, the three dots, Copy member ID) and the two channel names, and press Save.

    #bridge gets "Stuurman is connected."

    The First Mate

    On the Crew page, tick "This is the First Mate" and press Sign on. Then give it its Slack app, as you did for the Helm: Create Slack app, Get the install link and Allow, then its app-level token with Save and check.

    The Overview says "The Ship is fitted out."

    Crew

    1 signed on
    • alfaFirst Mate
      off watch
    An example: the crew list with the First Mate signed on.

  4. Say hello

    In Slack, or from the Bridge.

    In #bridge, mention the First Mate's app (type @ and pick it), or send it a direct message. It marks your message with 👀 while it works, and answers where you wrote.

    An example first conversation in #bridge.

    Or open the Crew page, press its name and Hail it from the Bridge. Ask it who else should sign on.

Early preview, v0.2.0. Install it at your own risk. There is no support.

If something goes wrong

All stop halts the Ship and removes every crew container: the stop in the Bridge's top bar, or /allstop in Slack. Resume with Underway on the Bridge, which asks first, or /underway in Slack.

stuurman doctor checks the Helm's surroundings, stuurman logs -f follows its log, and stuurman status shows the Ship's state.

Back up

Back up the Ship's folder, ~/stuurman/<id>: its .env file and its data folder. Without the key in .env, the Ship's secrets cannot be read.

Keep no secret in a cabin.

If the Bridge and Slack cannot be reached

All stop needs neither the Claude token nor Slack. This one is a Docker command, not a stuurman one: the stuurman command has no all stop, and stuurman stop only stops the Ship's containers. Run it in the Ship's folder, with your Ship's ID in place of <id> (stuurman list shows the ID and the folder).

docker compose -p stuurman-<id> run --rm --no-deps -T helm allstop