Deploy the API

Before you start this guide: You must have completed 08 — Fly.io Setup.

We are finally going to blast your backend API perfectly into the cloud! We must do this in a very specific 3-step sequence so the server doesn't crash from missing API keys.

Prepare the Cloud App

First, we tell Fly.io to reserve a bucket in the sky with your name on it, but we do not start the engine yet!

• 1.1 Open your terminal.

• 1.2 You need to go into the correct folder where the API code lives. Run:

cd apps/api

• 1.3 Now, let's look closely at your fly.toml file inside the apps/api folder using VS Code.

• Make sure the very first line matches the exact name you chose in the last guide.

• Change app = "openclaw-wrapper" to app = "your-api-name-here"

• Save the file.

• 1.4 Run this exact command in the terminal to reserve the app. Replace your-api-name-here with what you put in the fly.toml file:

fly launch --name your-api-name-here --no-deploy

Important: The --no-deploy flag is critical! If you forget it, Fly will turn the engine on before we inject your .env file, and the server will instantly crash and reboot endlessly.

1.5 Did you get an error? Fly.io application names are worldwide. If the terminal says Validation failed: Name has already been taken:

1. You must pick a more unique name (e.g. openclaw-wrapper-api-john77).
2. Go into your .env file and update FLY_API_APP_NAME= to this new unique name.
3. Open apps/api/fly.toml and update app = to this new unique name.
4. Try running the fly launch command again with the new name.

Inject the Passwords

Right now, your app bucket is sitting in the cloud safely, but it is totally empty. We need to shove your precious .env passwords directly into its vault so it can connect to the database.

[CRITICAL SHIFT - NO MORE COPY-PASTING!] In the past, Windows and Mac users had to run complicated terminal pipes that frequently corrupted passwords. We have built a native deployment script to perfectly format and sync your passwords automatically.

• 2.1 Make sure your FLY_API_APP_NAME= line in the .env file matches the exact name you used in .fly.toml (e.g., openclaw-wrapper-api).

• 2.2 In your terminal (you should still be inside the apps/api folder), type exactly:

pnpm run secrets:push

• 2.3 Hit Enter. The script will securely read your .env file, strip out all invisible Windows/Mac bugs, extract your FLY_API_APP_NAME boundary, and safely transmit the keys to the Fly.io vault natively.

Wait for confirmation: The terminal will flash and tell you exactly which keys it successfully secured in the vault. If it says "Success!", you are perfectly synced.

Ignite the Engine

Now that the vault is full of passwords, we can finally turn the server on.

• 3.1 In your terminal (you should still be inside apps/api), run:

fly deploy -a your-api-name-here

In my case it is shipclawfast-api

• 3.2 Sit back and watch. Fly will wrap up your NodeJS code, build a perfect Linux server for it instantly, and launch it! This process takes about 2 to 3 minutes.

• 3.3 When it finishes, it will say "Deployed Successfully".

You officially have a live backend!

Checklist — Before moving on

• I changed the app = name inside apps/api/fly.toml
• I ran fly launch --no-deploy
• I used the special Windows/Mac command to inject my .env file
• I ran fly deploy and it showed successful health checks

When every checkbox above is ticked, move on to 10 — Push Agent Image.