Marblo Getting Started — From Download to Your First Finished Agent

When most people open Marblo for the first time, they close it without ever spawning a single agent. Not because the product is bad, but because they hit three walls before they ever see the value. This guide names those three walls up front and walks you past each one, all the way to the moment your first agent finishes a ticket end to end.

It's written developer-first, but it includes the Node.js install step so that someone new to AI tooling can also get through it alone.

★Before you start — let's be honest (BYOK)

Marblo runs agents on your own AI account. This is called BYOK (Bring Your Own Key). So to start you need two things, and without both you'll get stuck at the first spawn.

• paid plan

ConnectfolderFirstfinishWall ① no Node.js · Wall ② no paid Claude auth · Wall ③ free account passes, then first spawn crashes

Requirement 1 — your own paid Claude subscription (or API key)

The agents Marblo spawns run on the Claude Code CLI, and Claude Code only actually works with a paid plan (Claude Pro or higher) or an Anthropic API key. If you run claude login with a free account, the login itself succeeds, but the first task silently fails (that's wall ③).

• Smoothest path: if you already use Claude Pro (or Max), just run claude login.
• API key also works: get an ANTHROPIC_API_KEY and it runs without a subscription. You pay per usage.
• If you'll use Codex, OpenAI is the same — a paid ChatGPT subscription or an OPENAI_API_KEY.

The point: signing in to Marblo is free, but the cost of actually running agents comes out of your AI account. Start without knowing this and you'll get stuck at the first spawn.

Requirement 2 — Node.js / npm

The agent CLIs (Claude Code · Codex) install as npm packages, so your machine needs Node.js and npm. If you're a developer you probably already have them; if not, you'll install them in five minutes in Step 2 below.

To check what you have right now, type this in a terminal:

node -v && npm -v

If version numbers appear (e.g. v20.11.0 / 10.2.4), you're ready. If you see command not found, go to Step 2.

Step 0 — Founder approval & app download

Right now Marblo ships the desktop app only to founders (selected beta users). So if you go straight to the download page, you'll see a sign-in / apply prompt instead of the app.

Here's the order:

1. Apply on the Founders page with a one-line email (it's reviewed and selected, not first-come).
2. If selected, access instructions arrive by email.
3. While signed in, open the download page — only then can you grab the macOS (Apple Silicon · Intel) or Windows build.

🎥 Video slot A — Getting the founder email → signing in → the download button unlocking. (A web screen outside the app, so it can be captured live.)

Step 1 — Install and first launch

Run the file you downloaded.

• macOS: open the .dmg and drag Marblo into your Applications folder.
• Windows: run the installer as-is.

On first launch you may see a macOS Gatekeeper or Windows SmartScreen warning. It's a properly signed and notarized build, so get past it like this:

• macOS: System Settings > Privacy & Security → "Open Anyway".
• Windows: More info > Run anyway.

🎥 Video slot B — Clearing the Gatekeeper/SmartScreen warning on first launch and the app opening.

Step 2 — Install Node.js / npm (Wall ①)

If node -v gave you command not found, fix it here. If you already have it, skip this step.

1. Go to nodejs.org.
2. Click the green "Get Node.js®" button (the LTS version, e.g. v24.x) to download the installer.
3. Run the installer as-is. npm comes bundled with Node.js.

When it's done, open a new terminal and check again:

node -v && npm -v

If both version numbers appear, you've cleared wall ①.

Why is this needed? Marblo auto-installs the agent CLIs with npm install -g. Without npm, that auto-install fails and the app tells you "npm not found. Install Node.js / npm and try again." Installing Node.js first skips that detour entirely.

Step 3 — Confirm CLI auto-install & authenticate (Walls ②·③)

This is where new users get stuck most often. Stay calm; there are only two things to do: (a) confirm the CLIs are installed, and (b) authenticate with your own paid account.

3-1. The required CLIs auto-install

On first launch, Marblo auto-installs Claude Code · Codex · the Marblo MCP in the background. You don't need to install anything by hand from the Harness tab. (If you installed Node.js in Step 2, this auto-install quietly succeeds.)

3-2. ★Authenticate — this is where a paid account is required

When you try to open the orchestrator, Marblo shows a CLI auth gate. Click "Run authentication" and a terminal tab opens with the login command auto-typed. If you'd rather type it yourself:

claude login

When the browser opens, sign in with your own Anthropic account. If you'll also use Codex:

codex login

⚠️ This is wall ②·③. The gate only says "sign in," which makes it look like a free login is enough. But:

• Signing in alone isn't enough — the account you signed in with needs a paid entitlement (Claude Pro/Max or API credit).
• Sign in with a free account and the gate passes you as "ready," but the first spawn dies within 2 seconds (wall ③, pass-through crash). When that happens, don't ask "why did it die?" — check Requirement 1 (a paid subscription/API key) in "Before you start — BYOK" at the top.

Once authentication finishes, each CLI flips to an "authenticated" state. If the state doesn't update, restart the app.

🎥 Video slot C — The CLI auth gate → clicking "Run authentication" → claude login in the terminal → browser sign-in → flipping to "authenticated." (The key moment of getting started.)

Step 4 — Connect a folder → orchestrator opens automatically

Once you're authenticated, it's the easy road. Just pick one project folder and Marblo auto-registers it (zero clicks) and opens the orchestrator automatically.

The orchestrator is your command center. When the folder connects, it greets you and suggests "what ticket should I create / which agent should I attach."

🎥 Video slot D — Picking a folder once → the orchestrator opening automatically and greeting you.

Step 5 — Your first agent spawn

Just tell the orchestrator what you want in natural language. For example:

"Create a ticket to add an installation section to the README, and attach an agent."

The orchestrator creates the ticket and spawns a physical agent (a standalone CLI process). The spawned agent reads and writes actual code in its own terminal tab.

At this moment walls ②·③ are tested again. With auth and a paid entitlement in place, the agent stays alive and starts working. If it dies within 2 seconds into an "error" card → re-check the paid entitlement from Step 3.

🎥 Video slot E — A one-line instruction to the orchestrator → ticket created → an agent tab spawning and actually starting to move.

Step 6 — First completed task (the value moment)

When the agent finishes, it moves the ticket to REVIEW. You check the result (diff, change summary) and approve. The ticket flipping to DONE is Marblo's core value moment — the point where your role shifts from someone who types to someone who delegates and reviews.

If you got here, congratulations. You've cleared all three walls that stop most people, and watched an agent finish a ticket end to end with your own eyes.

🎥 Video slot F — The agent moving work to REVIEW → the user checking the diff → approving → DONE. (Completion = the value moment, the climax of the video.)

Stuck? — Three-wall troubleshooting

| Symptom | Which wall | Fix | | ----------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------- | | App says "npm not found" | Wall ① (no Node.js) | Install Node.js via Step 2, open a new terminal, retry | | Auth gate won't go away / keeps asking to "sign in" | Wall ② (not authenticated) | Complete claude login fully. Sign in via the browser, then restart the app | | Signed in, but the agent dies within 2 seconds (error card) | Wall ③ (free-account pass-through) | Check that the account you signed in with has Claude Pro/Max or API credit. Free accounts stop here | | App won't open on first launch (warning dialog) | Install | Get past Gatekeeper/SmartScreen per Step 1 | | Still stuck | — | Tell us via Report a bug. Where you got stuck shapes the next version |

Next steps

Once you've reached your first completion, the next move is running multiple agents at once. Assign roles to backend, frontend, and test agents, and tie dependent tickets into a DAG — Marblo runs them in parallel while respecting order.

• What is Marblo — the orchestrator-centric big picture
• One developer, many agents — how to work at team scale, solo
• Parallel agents that don't collide — running many agents at once with worktree isolation

Get the two requirements (a paid Claude account + Node.js) in place and Marblo handles most of the rest automatically. You just have to clear the three walls.