Privateer Agent

curl -fsSL https://privateer.pro/install.sh | sh    # macOS / Linux — installs the `privateer` command
irm https://privateer.pro/install.ps1 | iex         # Windows (PowerShell)
npx privateer-agent                                 # or run it instantly, nothing installed

Point it at a frontier model today and a local Ollama model tomorrow — OpenRouter, Anthropic, OpenAI, Google, xAI, Groq, Mistral, Z.ai (GLM), DeepSeek, Qwen, local Ollama, NEAR AI or Tinfoil (verifiable TEE inference), Venice / Fireworks (no-retention inference), and any custom OpenAI-compatible endpoint (LM Studio, vLLM, llama.cpp…) are interchangeable at /model time, including mid-session. No model lock-in, no separate code paths. MCP servers, sub-agents, scheduled routines, multi-step workflows, chat-app bridges, and one-tap approval from your phone are included — and every one of the agent's actions runs through a safe-by-default permission gate.

Privateer runs in three places, over one account and one config: the terminal, a background daemon for unattended work, and the Privateer app on phone, web, and desktop.

Why Privateer?

• No lock-in. One agent, every provider. /model swaps mid-session and your config, commands, and agents come along for the ride. No vendor's models are privileged.
• No API key required. Bring your own key from any supported provider, run keyless against a local Ollama — or /signin to bill a Privateer account instead.
• Safe by default. Every edit, shell command, and network call is classified and gated before it runs; destructive commands are blocked even in unattended runs. You stay in control, whether you're watching or not.
• Privacy you can verify, not just trust. Confidential-enclave (TEE) inference is cryptographically attested — not a policy promise — and an on-device PII gate warns before structured personal data ever leaves your machine for an unverified model.
• It's Pi underneath. Privateer is a distribution of the Pi coding agent — every Pi extension, skill, and command works, and Privateer's own features are just extensions you can read, swap, or build on. Nothing to compile. See Built on Pi.

Built on Pi

Privateer is a distribution of the Pi coding agent (@earendil-works/pi-coding-agent): Pi is the runtime, the model routing, the interactive TUI, and the extension / skill / prompt discovery system — everything that works in Pi works here. What Privateer adds is a moat of Pi extensions layered on top:

They're ordinary Pi extensions — inspect them, replace them, or build your own alongside. Extend by discovery: drop an extension into ~/.privateer/agent/extensions/ (move the home with PRIVATEER_HOME), add a skill or prompt beside it, or list an npm/git package under packages in ~/.privateer/agent/settings.json — Pi auto-loads them on next launch, right next to Privateer's own. Any extension from the Pi ecosystem loads the same way. (There's no CLI flag for this — discovery is the entry point.)

The floor you can't lower is the safety gate. While it's loaded, its block on destructive shell commands, secret exfiltration, and plan-mode escapes sits above every relaxation — bypass mode, the approval allowlist, even a phone-approved remote turn can't fire them silently. The moat is swappable; the floor under it holds.

Highlights

• Private, verifiable inference via NEAR AI and Tinfoil: every model runs inside a Trusted Execution Environment, a live status shield reflects the attestation, and /verify fetches and checks the cryptographic report on demand — genuine proof the inference ran on real confidential hardware, not a terms-of-service page.
• On-device PII gate. Before a prompt goes to an unverified channel, Privateer scans it locally for structured personal data (emails, phone numbers, SSNs, cards, IBANs, IPs…) and offers to redact or hold it — detection never leaves your machine, and an attested TEE channel skips the check because it provably can't read your data anyway.
• Honest privacy posture, graded. A verified TEE and a "we promise not to retain" policy are never rendered the same — the badge tells you exactly how strong the guarantee is (cryptographically verified → observable → policy → none).
• Drive it from your phone. Link the terminal with /remote-access (off by default) and the Privateer app can send prompts, stream output, and Allow/Deny every action — while execution stays on your machine. Sub-agent actions surface for approval the same way.
• Manage it from the app. Extensions, skills, routines, workflows, MCP connectors, and chat-app channels are all configurable from your phone or the web app, against any linked terminal. See The Privateer app.
• A desktop app. The same agent hosted inside a local Electron shell — no relay hop, works offline, multi-window with per-window MCP connectors. Shares your CLI login and config.
• Scheduled routines. A background daemon runs approved tasks unattended — cron or one-off — and the agent can schedule its own follow-up work. Results deliver to a file, the next session, your phone, email, or a webhook.
• Declarative workflows. Multi-step agent pipelines as YAML — typed steps, conditional routing between them, and human_gate steps that pause for your approval and resume.
• Chat-app channels. Bridge the agent into Telegram, Slack, Discord, or WhatsApp with role-based approval — admins can approve actions, members are read-only.
• MCP servers, sub-agents & skills. Connect Model Context Protocol servers (local stdio or remote HTTP with OAuth), delegate work to bounded parallel sub-agents, and drop in skills — all gated like everything else.
• Zero-Data-Retention surfacing for OpenRouter — see the selected model's retention posture before you send, and pin routing to zero-retention endpoints.
• Plan mode, checkpoint/rewind, session branching, a modal prompt with / command and @ file autocomplete, ! shell passthrough, background shells, and image attachment for vision-capable models.

Quickstart

curl -fsSL https://privateer.pro/install.sh | sh    # or: npm install -g privateer-agent
export OPENROUTER_API_KEY=sk-or-...                 # one provider is enough — or skip and /signin
privateer                                           # launches the interactive agent

First run walks you through picking a provider and default model. From there, just type. No install at all: npx privateer-agent.

Install

# the one-liner installer — downloads a self-contained bundle, no Node needed:
curl -fsSL https://privateer.pro/install.sh | sh    # macOS / Linux
irm https://privateer.pro/install.ps1 | iex        # Windows (PowerShell)

# or via npm, if you'd rather manage it yourself (needs Node ≥ 22.19):
npm install -g privateer-agent
npx privateer-agent                                 # run without installing

Requirements: macOS (arm64/x64), Linux (x64), or Windows (x64). The installers ship a pinned Node runtime inside the bundle, so you don't need Node or npm on your machine at all — Node ≥ 22.19.0 is only required for the npm / npx path.

Update in place with privateer update (bundle-aware: it re-runs the right installer for how you installed) or check your version with privateer --version.

Windows: the agent's command tool needs a bash, which Windows doesn't ship. Install Git for Windows (or WSL) and Privateer will find it; the launcher checks at startup and tells you how to fix it if not. Override the choice with shellPath in ~/.privateer/agent/settings.json. Linux arm64 and Windows arm64 bundles aren't built yet — arm64 Windows runs the x64 bundle under emulation.

Verifying what you're about to run

Privateer is a coding agent — it runs shell commands and edits files, so "should I trust this package?" is the right question to ask before npx. Two things are checkable without taking anyone's word for it:

npm view privateer-agent dist.attestations   # published from CI with npm provenance:
                                             # a signed link from this tarball to the
                                             # exact commit and build that produced it
npm audit signatures                         # verify registry signatures + provenance

The package also declares no install scripts — no postinstall, nothing. Installing it writes files and executes nothing; npm install -g privateer-agent --ignore-scripts gives an identical result. Code runs only when you run privateer.

See SECURITY.md for the threat model, the permission gate, and how to report a vulnerability.

From source:

git clone https://github.com/privateer-agent/privateer-agent.git
cd privateer-agent
npm install
npm start            # launches the interactive agent

Configure a provider

Privateer reads credentials from environment variables (or sign in to an account and skip keys entirely). One provider is enough to start:

export OPENROUTER_API_KEY=sk-or-...      # gateway to ~everything
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=AIza...            # Google
export XAI_API_KEY=xai-...               # xAI (Grok)
export GROQ_API_KEY=gsk_...              # Groq
export DEEPSEEK_API_KEY=sk-...           # DeepSeek
export OLLAMA_BASE_URL=http://localhost:11434/v1   # local, keyless
export NEAR_AI_API_KEY=...               # verifiable TEE inference (cloud.near.ai)
export TINFOIL_API_KEY=...               # verifiable TEE inference (tinfoil.sh)
export VENICE_API_KEY=vapi_...           # no-retention inference
export PRIVATEER_API_KEY=sk-priv-...      # Privateer developer API (privateer.pro); or /signin instead

Pick a model with /model (browse each configured provider's live catalog) or pass one directly as provider/model — e.g. openrouter/anthropic/claude-opus-4.8, ollama/qwen3-coder, nearai/zai-org/GLM-5.1-FP8. Any OpenAI-compatible server (LM Studio, vLLM, llama.cpp) works as a custom provider — just give it a base URL.

Override the config location with PRIVATEER_HOME.

Context files — PRIVATEER.md

Give the agent standing knowledge about your project — conventions, common commands, domain notes — by dropping a PRIVATEER.md in the directory. Privateer loads it automatically at the start of every turn and prepends it to the model's system prompt, exactly the way Pi loads AGENTS.md / CLAUDE.md (all three are recognized, and all matching files are concatenated).

Run /init to scaffold a starter PRIVATEER.md in the current directory, then edit it. The startup banner shows a ⚓ line with the loaded file's path (and a +N count when ancestor files also apply), or a /init hint when none is found.

Discovery mirrors Pi's context-file lookup: the global agent dir (~/.privateer/agent/PRIVATEER.md) first, then every directory from the filesystem root down to the current one — so a repo-root PRIVATEER.md applies to every subdirectory, and a deeper file can refine it. AGENTS.md and CLAUDE.md continue to work unchanged; use --no-context-files (-nc) to disable context-file loading entirely.

Private & verifiable inference

NEAR AI Cloud and Tinfoil run every model inside a Trusted Execution Environment — a confidential VM where TLS terminates inside the enclave, so your prompt's inputs, weights, and outputs are invisible to the infrastructure provider, the model provider, and the host itself. It isn't "trust us": each request can produce a cryptographic attestation proving the inference ran on genuine TEE hardware.

• A status shield colors the selected model's live posture — 🟢 verified, 🟡 returned but unconfirmed, 🔴 no attestation material.
• /verify fetches the attestation on demand and prints the evidence. Privateer does a pragmatic terminal-suited check; take the printed report to the NEAR AI Cloud Verifier or the Tinfoil verifier for full quote-chain validation.
• The posture is graded honestly. A verified enclave (cryptographic), a pinned zero-retention route (observable), and a provider's retention promise (policy) are labeled distinctly — a claim never gets to read like a proof.

The PII gate

Before any prompt is sent to a channel that isn't verified-private, Privateer scans it locally for structured personal data — emails, phone numbers, SSNs, credit-card numbers (Luhn-checked), IBANs (mod-97), IP and MAC addresses. If it finds any, it warns and offers to redact or send as-is (or remember your choice for the session). Detection is deterministic and on-device — no model ever sees the data in order to find it — and it's skipped entirely on an attested TEE or on-device channel, which provably can't read your prompt anyway. It's best-effort structured-PII detection, labeled as such — a safety net, not a guarantee.

Privateer account (billed inference)

Instead of bringing your own key, run /signin to sign into a Privateer account — an app-brokered device flow where you approve a short code in the Privateer app, so wallet and email accounts work identically and no password or key ever touches the terminal. Inference is then billed to your subscription and defaults to a NEAR TEE model. Sign out any time with /signout; manage linked terminals from the app.

Only approve a sign-in code you generated yourself. The code authorizes this terminal to spend on your account. If someone sends you a code and asks you to approve it, don't — that hands them a billed session on your account.

The Privateer app

The same account drives Privateer from iOS, Android, the web app, and a desktop app. The terminal stays where the work happens — the app is a remote control and a management surface for it.

Linking a terminal

1. Run privateer and /signin. It prints a short device code.
2. Open the app → Link a terminal, enter the code (or tap the deep link). No password or wallet key ever touches the terminal, and the app pins the terminal's public key on first link.
3. In the terminal, turn on /remote-access (off by default). The terminal now shows Online in the app.

Only approve a code you generated yourself. Approving someone else's code hands them a billed session on your account.

What you can do from the app

Config changes that carry secrets or executable content (MCP credentials, channel bot tokens, workflows with script steps) are sealed to the terminal's pinned key and signed by your account — the relay forwards them blind and can neither read nor forge them.

The relay itself is live-only (nothing is archived), carries no API keys, and output is size-truncated and run through a best-effort secret redactor before it leaves your machine.

Desktop app

The desktop app hosts the agent in-process and talks to it over loopback IPC — no relay, no network hop, and it works offline. It reads the same ~/.privateer home, so it shares your CLI login, model config, and MCP catalog. Multi-window, with a per-window subset of your MCP connectors and a native folder picker.

Download for macOS (Apple silicon), macOS Intel, or Windows.

It's an early release and not yet code-signed or notarized — macOS will warn on first open. Routines and channels deliberately aren't hosted here: those belong to the always-on daemon, so background work still wants privateer daemon install.

Run it unattended — the daemon

A resident background daemon runs scheduled routines, executes workflows, and accepts task spawns from the app — with no terminal open.

privateer daemon install      # install as a login service (auto-starts, reachable from the app)
privateer daemon status       # service installed? daemon answering?
privateer daemon run          # or just run it in the foreground
privateer daemon uninstall

Installs as a launchd user agent on macOS or a systemd --user unit on Linux — no root, no sudo. (There's no Windows service path yet; use privateer daemon run.)

Everything the daemon does still runs through the permission gate. Actions needing approval surface in the app; routines you approved once run on their own schedule.

Workflows

A workflow is a YAML file describing a multi-step agent pipeline — a flat graph of typed steps (agent, script, human_gate) with conditional routes between them and {{ }} templating to pass values along. A human_gate step pauses the run for your approval and resumes when you answer it, including from your phone.

The engine ships in the standalone privateer-workflow package. Today the user-facing surface is the app (save, run, monitor, share) and the daemon that executes them — there's no /workflow command in the terminal yet. Schedule one by pointing a routine at it.

Because a workflow can carry script steps, saving one from the app requires your account signature — the server can't inject a workflow onto your daemon.

Chat-app channels

Bridge the agent into Telegram, Slack, Discord, or WhatsApp so you can hand it work from a group chat. Each channel has:

• Roles — admins can approve actions; members are always read-only, no exceptions.
• A posture — readonly, approve (default), or auto.
• A hard tool ceiling — a per-channel allowlist the agent can't exceed even in auto.

Configure a channel from the app, or by hand in the channels block of ~/.privateer/config.json. Changes take effect on restart, by design. Bot tokens set from the app are write-only — the app can name them but never read them back. Note that tokens live in plaintext in config.json on your machine, and every channel action is appended to ~/.privateer/channels-audit.log.

Permission modes

Switch with /mode. Even in bypass, a danger filter blocks destructive shell commands, and protected files (.env, shell rc files…) are guarded — the gate is never fully off.

--no-quarter — lower the moat entirely

For an unattended run in a directory and on a task you fully trust, launch with:

privateer --no-quarter

This is the one exception to "the gate is never fully off." It disables the permission gate for the whole session — every action auto-approves with no prompt, including destructive shell commands, out-of-cwd access, and protected files. Subagents spawned by the session inherit it. There is no /mode equivalent; it's a deliberate launch-time opt-out (env PRIVATEER_NO_QUARTER=1) and prints a red warning banner so it's never a surprise. Use it sparingly.

Extend it

Everything below is a Pi extension loaded by discovery (see Built on Pi) — drop your own into ~/.privateer/agent/extensions/ and it loads the same way, gated like the rest.

• MCP servers (pi-mcp-adapter) — declare them and their tools become first-class, gated like the rest (local stdio, or remote HTTP with interactive OAuth). One catalog at ~/.privateer/agent/mcp-desktop.json is shared by the CLI, the daemon, and the desktop app, so a machine has one coherent connector config.
• Sub-agents (pi-subagents) — delegate investigations to bounded parallel agents. Children run as headless child processes that inherit the moat, so their actions hit the same permission gate and their approvals surface on your phone.
• Routines — saved tasks the daemon runs unattended; ask the agent to schedule work and approve it once.
• Workflows — declarative multi-step pipelines the daemon executes; see Workflows.
• Web tools (rpiv-web-tools) — private-by-default web search/fetch with pluggable backends (self-hosted SearXNG for fully private search).

Command reference

Shell subcommands: privateer (interactive), privateer update, privateer daemon …, privateer --no-quarter, privateer --version.

Develop

npm run typecheck
npm test

Changelog

Release notes and what's new in each version live on the GitHub releases page. Privateer keeps its startup clean — the app won't dump a changelog into your terminal.

License

MIT © Patrick