Fly.io Setup

Before you start this guide: You must have completed 07 — Polar Setup.

Fly.io is the cloud company that will run your backend API server and host the AI agents for your customers permanently. It replaces the need for you to leave your computer running 24/7.

Create a Fly.io Account

• 1.1 Go to https://fly.io

• 1.2 Click Sign Up (or "Sign In" with GitHub).

• 1.3 Important: Add a credit card or debit card which accepts international transactions to your Fly.io billing settings.

Unlike Vercel, Fly.io requires a credit card on file just to verify you are a real human, even to use their free tier. You will not be charged unless you massively exceed the free limits.

Install the Fly CLI

Before we can send your code to Fly, we need to install their command-line tool on your computer.

If you are on Windows (PowerShell): Open PowerShell and run this exact command:

pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"

If you are on Mac or Linux: Open your Terminal and run this exact command:

curl -L https://fly.io/install.sh | sh

Log in with the Terminal

Now we need to connect the terminal on your computer to your shiny new Fly account.

• 3.1 In your terminal, type this command:

fly auth login

• 3.2 Your browser will automatically pop open and ask you to log in to Fly.io again. Click "Continue".

• 3.3 The browser will say "Successfully logged in". You can close the browser tab.

• 3.4 Go back to your terminal window. It should now say Successfully logged in as [your email].

Get Your Organization Token

For your backend server to be able to dynamically spawn new, isolated AI Machines for every single customer that signs up, it needs an "Organization-level" master password to talk to Fly.io.

[CRITICAL SHIFT - DO NOT USE DEPLOY TOKENS!] We must explicitly generate an Organization Token from the Fly Dashboard. Standard deploy tokens will crash your SaaS because they lack permission to spawn new containers.

• 4.1 Go back to your Fly.io Web Dashboard in your browser (https://fly.io/dashboard).

• 4.2 Look at the left sidebar menu. Scroll down and click on Tokens.

• 4.3 On the Tokens page, locate the Organization Tokens section.

• 4.4 Click the purple Create Organization Token button. (You can leave the name and expiration boxes completely blank so the token never expires).

• 4.5 Fly will reveal a very long password starting with fo1_...

• 4.6 Copy this token.

• 4.7 Open your .env file in VS Code.

• 4.8 Find the FLY_API_TOKEN line and paste the token:

FLY_API_TOKEN=fo1_your_cool_token_here_...

Declare Your App Names

To keep things perfectly organized in the cloud, you need to decide right now what you want to name your API backend.

Remember the URL you reserved inside Polar in Step 7? (e.g. shipclawfast-api.fly.dev). Your name is whatever comes before .fly.dev.

• 5.1 In your .env file, add these two lines at the very bottom:

FLY_API_APP_NAME=shipclawfast-api
AGENT_APP_NAME=shipclawfast-agent

(Obviously, replace shipclawfast-api with the exact name you promised Polar you would use).

What are these? FLY_API_APP_NAME: This is the bucket holding your billing/backend math. AGENT_APP_NAME: This is the bucket holding the massive AI Agent containers for your customers. You must never mix these two names up, or Fly will crash with a MANIFEST_UNKNOWN error when building robots!

Checklist — Before moving on

• I created a Fly.io account and added a billing card
• I installed the Fly CLI on my computer
• I logged into my Fly CLI using the terminal
• I created an Organization Token in the web dashboard and pasted it into .env
• I added my chosen app names into .env

When every checkbox above is ticked, move on to 09 — Deploy API.