Your First Run: From Zero to a Working Sapior Session in 5 Minutes

Every developer tool eventually faces the same quiet test: the first five minutes after installation. If those minutes are spent staring at a blank terminal or hunting for a missing environment variable, the tool has already lost the room.

Sapior is different. We built it so that the distance between “I’ve cloned the repo” and “I’m watching a real browser carry out my commands” is measured in heartbeats, not hours. Here’s exactly where to begin—and what to do next.

1. Prerequisites

You’ll need **Node.js 18+** and a package manager (npm, pnpm, or yarn). Sapior’s runtime is deliberately lightweight; it ships a single binary for Chrome-for-Testing, so you don’t need to install a system browser.

2. Install the CLI and SDK

Open a terminal and run:

npm install -g @sapior/cli
sapior login

The login flow opens a browser window once. It’s OAuth, no credentials stored locally.

Next, scaffold a project (or add sapior to an existing one):

mkdir my-first-sapior && cd my-first-sapior
npm init -y
npm install @sapior/sdk

3. Create Your First Script

Create `index.ts` (or `.mjs`) with the canonical “open a page and print the title” example:

import { SapiorSession } from '@sapior/sdk';

async function main() {
  const session = await SapiorSession.create();
  const page = await session.newPage();
  await page.goto('https://example.com');
  const title = await page.title();
  console.log(title); // "Example Domain"
  await session.stop();
}

main();

4. Configure (Just a Little)

Create a `.env` file with your API key (found in the Sapior dashboard under **Settings → API Keys**):

SAPIOR_API_KEY=sp_1A2b3C4d...

The SDK reads this automatically. No config file needed.

5. Run It

npx tsx index.ts

You’ll see a link in the terminal that opens the **Sapior LiveView**—a real-time canvas of the remote browser. This is your workspace. The script executes, the page title prints, and the session closes gracefully.

6. Next Useful Steps

**Run in stealth mode.** Add `{ stealth: true }` to the session options. Sapior automatically rotates fingerprints, manages WebGL noise, and balances CAPTCHA avoidance—without any proxy setup on your side.

**Re-use a session.** Long‑lived sessions are great for multi‑page workflows:

const session = await SapiorSession.create({ keepAlive: 300 }); // 5 minutes

**Integrate into CI.** Sapior supports GitHub Actions natively. Add a simple workflow file and your tests run against a fully‑managed browser fleet, no Docker-in-Docker headaches.

The Real Lesson

The fastest way to learn Sapior is to break it. Open `about:blank`, inject a script, play with the DevTools protocol. Our [docs](https://docs.sapior.dev) mirror this philosophy: every page has a live, runnable example embedded right below the explanation. Copy, paste, modify.

At Browserbase, the team famously said, “If the first run takes more than two minutes, we’ve failed.” We took that to heart. Start with the five lines above, and you’ll already be past the blank‑screen stage. The rest is just exploration.