Skip to content

Quick Start: Onboard Local Agents with the CLI

The fastest way to get value out of Preloop is to install the Preloop CLI on the machine where your AI agents already run. The CLI discovers supported agents (Claude Code, Codex CLI, Gemini CLI, Hermes, OpenClaw, OpenCode, Cursor, Windsurf, …), creates an account if you don't have one yet, and rewrites their configuration so every tool call goes through the Preloop MCP Firewall and every model call through the Preloop Gateway — all without touching the agent's source code.

60 second flow

  1. Run the install command.
  2. The CLI scans your machine and lists every supported agent it found.
  3. It opens your browser to sign in or sign up.
  4. You're redirected back to /console/agents with everything wired up live.

Step 1: Install the Preloop CLI

Run this on macOS or Linux:

curl -fsSL https://preloop.ai/install/cli | sh

The installer:

  1. Downloads the preloop binary into ~/.preloop/bin (or /usr/local/bin if writable) and prints the path it added to your shell.
  2. Runs preloop agents discover --no-onboard-prompt so you can see your detected agents before signing up.
  3. Asks whether you want to log in (default), sign up, or skip authentication. Picking sign‑up routes the browser to /register instead of /login.
  4. After authentication completes, runs preloop agents discover to walk through onboarding for every detected agent (default Y).
One command: install, discover, sign up, onboard.

Unattended installs

Set PRELOOP_CONFIRM=1 (truthy values: 1, y, yes, true, on) to auto‑approve every interactive prompt — both in the install script itself and in the CLI subcommands it invokes. This is the recommended way to bake Preloop into your provisioning scripts, devcontainers, or CI runners.

PRELOOP_CONFIRM=1 curl -fsSL https://preloop.ai/install/cli | sh

Step 2: Sign in or sign up

If this is your first time, choose s (sign up) at the prompt. The CLI opens a browser to https://preloop.ai/register?… and remembers the OAuth context it was about to consent to. After you create your account:

  1. Preloop auto‑logs you in (no detour through the sign‑in page).
  2. The OAuth consent page resumes where it left off and authorizes the CLI.
  3. Your browser lands on https://preloop.ai/console/agents?cli=connected, the live canvas of your account's agents.

If you already have an account, choose Y (default) and the same flow runs from /login instead.

SSH and headless hosts

On a headless host the CLI auto‑falls back to the copy/paste flow (preloop login --headless). Force it with preloop login --headless or preloop signup --headless to skip the loopback callback entirely. After pasting the code, the consent page shows a Continue to your agents button.

Step 3: Confirm onboarding in the console

The agents page opens to the canvas view by default — every detected agent shows up as a card connected to its tools and AI models. You can switch to the cards layout from the toolbar or pan/zoom the canvas to inspect each runtime.

Newly onboarded agents land on the live agents canvas.

Each card shows the onboarding state for that agent:

Badge Meaning
Fully onboarded Tool calls are routed through the MCP Firewall and model calls go through the Gateway.
MCP only Tool calls are firewalled, but the agent still uses its own model credentials.
Gateway only Model traffic is gated, but the agent still calls tools directly.
Discovered Detected on disk — not yet onboarded. Run preloop agents onboard <name> to connect it.

You can also kick off onboarding from the Onboard agents dialog at the top right of the page — it shows the same three CLI commands and one‑click copies for users who want to step through manually.

Step 4: Useful CLI commands

These are the commands the installer wires up for you. They also work standalone:

preloop login                  # OAuth login (loopback or copy/paste)
preloop signup                 # Same OAuth flow, but lands on the sign-up page
preloop auth status            # Show the active token + API URL
preloop auth logout            # Forget local credentials

preloop agents discover        # Detect local agents and walk through onboarding (Y/n per agent)
preloop agents discover --yes  # Onboard everything found, no prompts
preloop agents onboard <name>  # Explicitly onboard a known agent

preloop policy list            # List policies on your account
preloop policy validate <file> # Validate YAML before applying
preloop policy apply <file>    # Apply a policy
preloop approvals pending      # List approvals waiting on you

What discover actually does

preloop agents discover reads each supported runtime's config (e.g. ~/.codex/config.toml, ~/.claude/settings.json, OpenClaw policies, Gemini CLI MCP servers, etc.), proposes any missing additions, and — once you confirm — rewrites the relevant entries to point at https://preloop.ai/mcp/v1 (firewall) and https://preloop.ai/gateway/v1 (gateway). Original config is backed up next to it so you can roll back at any time.

What's Next?

  • Layer policies on top

    Now that your agents go through Preloop, set up allow / deny / approval rules.

    Continue to Part 1: Safety Layer

  • :material-flow-chart: Build agentic flows

    Trigger your prelooped tools from event‑driven workflows.

    Continue to Part 2: Flows

  • Approve from your phone

    Install the mobile app to approve risky tool calls on the go.

    Mobile apps

  • CLI reference

    Full reference for every preloop subcommand and flag.

    CLI guide