Local development on macOS and Windows

Translation of a guide from the project repository; the Czech original is authoritative. The project's documentation, task files, issues and commits are in Czech — Claude Code reads them for you, and you can ask it in English. Discord is Czech-speaking too, but English works as well. The installation scripts print their messages in Czech; this guide quotes them verbatim with the meaning in brackets.

A guide for someone who wants to get Shipard running on their own computer and has never administered a Linux server. At the end you have a running Shipard and its developer dashboard in your browser.

Shipard runs on Ubuntu. On a Mac you therefore run it in a virtual machine (Multipass), on Windows in WSL — in both cases it is Ubuntu inside your computer. The installation is done by one script, scripts/dev-bootstrap.sh.

Do you have a Linux server, or Ubuntu directly on your computer? You don't need this guide — the Linux procedure is in linux-install.md. The bootstrap just runs its steps one after another.

1. What you will need

• a Mac (Apple silicon or Intel), or Windows 10 (version 21H2 or later) or Windows 11
• about 20 GB of disk space and 4 GB of memory for Ubuntu
• an internet connection — the installation downloads packages and takes a while
• a GitHub account only if you want to contribute; you don't need one to try it out

The source code lives inside Ubuntu in the directory ~/sw/shpd, not on the Mac or Windows disk. Files shared from the host are slow and break the permissions the installation relies on.

2. macOS — Multipass

1. Install Multipass following the official page.

2. Download the configuration — in the Terminal app:

curl -fsSLO https://raw.githubusercontent.com/shipard/shipard/stable/scripts/multipass/shipard-dev.yaml

3. Insert your public SSH key (only if you want to connect Claude in chat — chapter 5; otherwise skip this step). Create a separate key for the development machine and just press Enter when asked for a passphrase — remote-dev-bridge can't use a key with a passphrase:

ssh-keygen -t ed25519 -f ~/.ssh/shipard_dev

If you already have the key ~/.ssh/shipard_dev, ssh-keygen asks whether to overwrite it — answer n, the existing key is enough.

Then put the key into shipard-dev.yaml — this command replaces the placeholder line with the contents of the public key, and the second one prints the result:

sed -i '' "s|ssh-ed25519 AAAA_NAHRAD_TENTO_RADEK_SVYM_VEREJNYM_KLICEM|$(cat ~/.ssh/shipard_dev.pub)|" shipard-dev.yaml
grep -A1 'ssh_authorized_keys:' shipard-dev.yaml

Under ssh_authorized_keys: there should be - ssh-ed25519 AAAA… with your key, not the placeholder text AAAA_NAHRAD_… ("replace this line with your public key").

If you want to edit the file by hand: open -e shipard-dev.yaml (TextEdit). On the line - ssh-ed25519 AAAA_NAHRAD_TENTO_RADEK_SVYM_VEREJNYM_KLICEM replace everything after the dash with the contents of the file ~/.ssh/shipard_dev.pub; keep the dash and the indentation. It is always the .pub file that goes in — the file without an extension is the private key and is never copied anywhere.

4. Launch the virtual machine:

multipass launch 26.04 --name shipard --cpus 2 --memory 4G --disk 20G \
    --timeout 1800 --cloud-init shipard-dev.yaml

The command waits until the installation inside finishes. The --timeout option is needed: the installation takes longer than the default 5 minutes, after which Multipass would report an error even though the machine keeps working.

Leave the network at the default. Don't add --network or --bridged. The developer dashboard has no sign-in — on Multipass's default network it is reachable only from your computer; on the local network anyone could see it.

5. Watch the progress — in a second Terminal window:

multipass exec shipard -- tail -f shipard-bootstrap.log

It is done when the output ends with the summary ==> Hotovo — vývojové prostředí Shipardu běží. ("Done — Shipard's development environment is running") and the dashboard address (Ctrl+C stops watching). The same is reported by multipass exec shipard -- cloud-init status --wait — it prints status: done.

6. Open the dashboard. The machine's address is on the IPv4 line:

multipass info shipard

In your browser open http://<IPv4>/_dev/.

Commands that will come in handy:

3. Windows — WSL

1. Install Ubuntu. Open PowerShell as administrator:

wsl --install Ubuntu-26.04

If the installation asks for a Windows restart, restart; if Ubuntu then doesn't open on its own, run the command again. Available distributions are listed by wsl --list --online.

2. First start. Ubuntu asks for the name and password of a new user. Remember the password — sudo will want it.

3. Run the bootstrap — in the Ubuntu window:

curl -fsSL https://raw.githubusercontent.com/shipard/shipard/stable/scripts/dev-bootstrap.sh | bash

The script asks for the password once at the start and then runs on its own. It ends with the summary ==> Hotovo — vývojové prostředí Shipardu běží. ("Done — Shipard's development environment is running").

If Ubuntu reports curl: command not found, install it (sudo apt update && sudo apt install -y curl) and repeat the command.

4. Open the dashboard in a browser on Windows: http://localhost/_dev/.

5. Optional: SSH for Claude in chat (chapter 5). Create the key on Windows — in PowerShell, just press Enter when asked for a passphrase:

ssh-keygen -t ed25519

Then, in the Ubuntu window, run the bootstrap again with the --with-ssh option (put your Windows user name in place of <user>):

bash ~/sw/shpd/scripts/dev-bootstrap.sh --with-ssh \
    --ssh-pubkey-file /mnt/c/Users/<user>/.ssh/id_ed25519.pub

SSH then listens on port 2222 and lets in only the holder of the key; signing in with a password is not possible. Both can be done at once during the first installation: curl -fsSL … | bash -s -- --with-ssh --ssh-pubkey-file ….

Things to watch out for:

• Keep the checkout in Ubuntu (~/sw/shpd), never in /mnt/c/….
• Keep the Ubuntu window open while you work. WSL may stop a distribution with no open terminal after a while — the dashboard and SSH then stop responding until you open Ubuntu again.
• The bootstrap needs WSL 2 with systemd. New Ubuntu installations have it enabled; if the script reports that systemd isn't running, it also says what to set.

4. First data source

A data source is one company — its own database and files. You create it in the dashboard with the + New DS button; tick Seed test data so you have something to work with right away. The individual steps and what to do next: dev-daily.md (section 2).

5. Connecting to Claude

The project works with the AI assistant in two roles — described in ai-workflow.md.

Claude Code runs directly inside Ubuntu, in the directory ~/sw/shpd. For everyday work (implementation, tests) it is all you need. The bootstrap doesn't install it — installation, sign-in and first steps are in claude-code-intro.md.

Claude in chat (design, assignments, verification) connects to Ubuntu over SSH through the remote-dev-bridge application on your computer — installation and connecting it to the Claude desktop app are in ai-workflow.md §7. In the bridge's settings add a server and a project with the ID shipard:

At the end of a bootstrap with --with-ssh these values are printed in the summary. After saving, ask Claude in chat for the machine's hostname — that verifies the project points at the right machine.

On macOS use a signed release from the Releases page. A custom unsigned build ends with the error "No route to host" — macOS doesn't give it the Local Network permission, without which it can't reach the virtual machine.

6. Daily work

A terminal in Ubuntu: on a Mac multipass shell shipard, on Windows the Ubuntu window. The code is in ~/sw/shpd.

What to do after git pull, when to run ds-upgrade-all and where the command overview is, is in dev-daily.md — the same for Multipass, WSL and a Linux server. The bootstrap enabled git hooks, so dependencies and the frontend update themselves after git pull.

The bootstrap can be run again at any time — it only verifies the finished steps. The optional parts are added the same way:

bash ~/sw/shpd/scripts/dev-bootstrap.sh --with-render

The checkout is cloned over HTTPS. Once you want to send changes, switch it as described in dev-daily.md (section 5).

7. Something not working?

The bootstrap ended with an error. The last lines say in which step (==> Bootstrap selhal v kroku: …, "Bootstrap failed in step: …"); the cause is above them. On a Mac the output is in a file:

multipass exec shipard -- tail -n 50 shipard-bootstrap.log

After removing the cause, run the bootstrap again — in a terminal inside Ubuntu bash ~/sw/shpd/scripts/dev-bootstrap.sh, and if the checkout doesn't exist yet, with the curl … | bash command from chapter 3 (step 3).

multipass launch reports "timed out". The machine is running and the installation continues — watch it as in step 5 of chapter 2.

The dashboard won't open. On a Mac check the machine's address and state (multipass info shipard); on Windows keep the Ubuntu window open.

The application reports an error, or it still doesn't work? The health check shpd-server doctor, fixing permissions, logs and where to turn — dev-daily.md (section 7). Attach the last lines of the bootstrap output to a report about it.