Start

Install and set up

This page gets you from nothing to a computer that is ready to build apps. You do it once. Plan on 45 to 90 minutes, most of it signing up for accounts. You can stop at any point and continue later.

In this guide, "Claude" means Claude Code following Shipyard's instructions.

Before you start

You need three things on your computer.

1. Claude Code, logged in with a Pro plan. If you do not have it yet, follow the install steps on the Claude Code website. To check, open a terminal (the text window where you type commands), type claude and press Enter.
2. Node.js, the LTS version. Node.js is a free program that runs the tools Shipyard uses. Download the LTS installer from nodejs.org and run it. Shipyard needs version 20 or newer. Close your terminal and open a new one afterwards, then check with node --version.
3. Git. Git keeps a history of your code. On a Mac, the first time you use it, the computer offers to install it. On Windows, Claude Code already needs Git for Windows, so you have it.

You will also need the GitHub tool, called gh. You do not need to install it now. Setup checks for it and shows you the exact line to type for your computer.

Mac or Windows

Everything works on both. The differences are small.

• On a Mac, gh is installed with brew install gh (Homebrew is a free installer for Mac tools). Setup shows you this line if you need it.
• On Windows, gh is installed with winget install --id GitHub.cli. Run Shipyard from the terminal that Claude Code runs in, not an old Command Prompt window that does not know Node.
• On Windows, your keys file is at %USERPROFILE%\.shipyard\secrets.env. On a Mac it is at ~/.shipyard/secrets.env.

Install the plugin

A plugin is an add-on for Claude Code. Shipyard comes from a public GitHub page. In Claude Code, run these two lines, one after the other.

/plugin marketplace add philipposk/shipyard
/plugin install shipyard@shipyard

If Claude Code does not know the Shipyard commands yet, close it and open it again.

Then turn on updates, so fixes reach you without any work:

Done when: typing /shipyard: in Claude Code lists the six Shipyard commands.

Run setup once

/shipyard:setup

Setup works through a list of steps. After each one it checks that the step really worked before moving on. It does the technical parts itself. You sign up, click in your browser, and paste one key into a file. Here is the list in order.

1. Tools. It checks Node.js, git, gh, npx (a helper that comes with Node) and a small browser used for phone-size checks. If something is missing, it shows the line to type. It never runs installers that need an admin password. It installs the small browser itself.
2. GitHub. GitHub stores your app's code. If you have no account, sign up at github.com with an email you can read. Setup starts a login, shows you a short code and opens github.com/login/device. You paste the code and approve.
3. Vercel. Vercel puts your app on the internet. Sign up at vercel.com, choose Continue with GitHub and pick the free Hobby plan. Setup then opens a page where you confirm the login.
4. Supabase. Supabase holds your app's database and sign-in. Sign in at supabase.com with GitHub. Then create an access token (a long password that lets Shipyard manage your Supabase projects) at supabase.com/dashboard/account/tokens. Name it "shipyard" and copy it.
5. AI keys (optional). Only needed if your app will use AI. You can skip it and add it later.
6. Email (optional). Only needed for emails your app sends, such as password resets. Skip for now.
7. Stripe (optional). For taking payments later, in test mode with no real money. Skip unless you know you need it.
8. Domain. A domain is a web address of your own. The answer to start with is "none for now". Your apps get a free name.vercel.app address. You can buy one later.
9. Profile. So you are not asked the same things for every app: your name, contact email, country, languages, your usual menu layout, whether apps should be installable on phones, and budget mode (recommended on).
10. Habits. Setup shows you a short list of working habits for Claude Code, kept in a notes file Claude reads at the start of every session (called CLAUDE.md). It asks before adding them to your own file. Say no if you prefer.

Where your keys go

Your keys live in one file on your computer, ~/.shipyard/secrets.env. Setup opens it for you. You paste the Supabase token after SUPABASE_ACCESS_TOKEN=, with no spaces or quotes, save the file, close it and tell Claude "done".

Never paste a key into the Claude chat. Anything you type in the chat is sent to Claude's servers and kept in your session history. A key in a file stays on your computer. Shipyard also adds a guard that stops Claude from reading that file or your .env files. The scripts read the keys themselves and only ever show a tick or a cross next to each name, never the value.

If you paste a key into the chat by mistake, go to that service's dashboard, revoke the key, make a new one and put the new one in the keys file only.

Stopping and continuing

Setup saves its progress as it goes. If you close the window, run out of Claude usage or go to bed, run /shipyard:setup again. It reads what is already done and carries on from the next step.

Done when: setup says no required step is open, and a settings page opens in your browser.

The settings page

Setup ends by opening a settings page. It is one page on your computer, with no internet connection needed. It shows your accounts, which keys are saved (never the values), your defaults, your company details and your apps. Each Change button copies a sentence for you to paste into Claude Code, and Claude makes the change.

You can open it again any time:

/shipyard:setup settings

If something fails

Fix one thing at a time and run /shipyard:setup again. These three cover most first-day problems:

• "node" or "npx" not found right after installing Node. Your terminal started before the install. Close it, open a new one and run node --version.
• The GitHub login code stopped working. The code expires after a few minutes. Ask Claude to run the GitHub login again.
• The Supabase check says the token is missing. Open the keys file again. The line must read SUPABASE_ACCESS_TOKEN= followed by the token, with no spaces, quotes or line breaks.

The troubleshooting page has the full list. If none of it fits, copy the exact error text and open an issue on GitHub. Never include a key.

What next

Setup is a one-off. After it, every new app starts with /shipyard:new-app. The guide begins with how AI coding agents work, which makes everything after it easier to follow. If you want to build first and read later, go straight to module 2.

Read module 1 Skip to your first app