> ## Documentation Index
> Fetch the complete documentation index at: https://docs.redpill.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Private AI Proxy

> The desktop app and CLI that verifies the RedPill gateway on your machine and connects your agents to a verified local API.

Private AI Proxy runs on your computer. It signs in to your RedPill account, verifies the gateway's
attestation before any prompt leaves your machine, and gives your agents a local API so they never
hold your RedPill credential. It is open source in
[Dstack-TEE/private-ai-gateway](https://github.com/Dstack-TEE/private-ai-gateway/tree/main/apps/desktop)
and published by dstack TEE.

```text theme={null}
your agent  →  Local API on 127.0.0.1:4180 (agent-scoped token)
            →  Private AI Proxy, verified and pinned channel
            →  RedPill gateway (attested), signed receipt per response
```

![Private AI Proxy overview screen, light theme](https://mintcdn.com/phala-47f19b07/eJAq2Kk_XKzgmNBM/images/private-ai-proxy/overview-light.png?fit=max\&auto=format\&n=eJAq2Kk_XKzgmNBM\&q=85\&s=4e150226ca9d1436f1eee0ee53d10d43)

Overview: Protected, the current session, the Local API, and connected agents

The sections below follow the app's screens: Profiles, Privacy, Agents, Local API, Usage, and
Settings, then the CLI.

## Install

### Desktop app

[Start building](https://redpill.ai/start-building) detects your platform and downloads the current
stable build.

> [tab] Direct download
>
> | Platform | Download |
> | - | - |
> | macOS, Apple Silicon | [`.dmg`](https://redpill.ai/download/private-ai-proxy/macos-arm64) |
> | macOS, Intel | [`.dmg`](https://redpill.ai/download/private-ai-proxy/macos-x64) |
> | Windows, x64 (Preview) | [`.exe`](https://redpill.ai/download/private-ai-proxy/windows-x64) |
> | Windows, ARM64 (Preview) | [`.exe`](https://redpill.ai/download/private-ai-proxy/windows-arm64) |
> | Linux, x64 | [`.deb`](https://redpill.ai/download/private-ai-proxy/linux-x64.deb) · [`.rpm`](https://redpill.ai/download/private-ai-proxy/linux-x64.rpm) · [Arch `.pkg.tar.zst`](https://redpill.ai/download/private-ai-proxy/linux-x64.pkg.tar.zst) |
> | Linux, ARM64 | [`.deb`](https://redpill.ai/download/private-ai-proxy/linux-arm64.deb) · [`.rpm`](https://redpill.ai/download/private-ai-proxy/linux-arm64.rpm) · [Arch `.pkg.tar.zst`](https://redpill.ai/download/private-ai-proxy/linux-arm64.pkg.tar.zst) |

> [tab] Homebrew (macOS)
>
> ```bash theme={null}
> brew install --cask dstack-tee/private-ai/private-ai-proxy
> ```

Linux requires glibc 2.35 or newer. Windows Desktop is currently Preview.

### CLI

The official scripts are the recommended installation method. They detect the operating system and
CPU, verify the release checksum, and install `pap`, `private-ai-proxy`, and `aci`.

> [tab] macOS / Linux
>
> ```bash theme={null}
> curl -fsSL https://redpill.ai/private-ai-proxy/install.sh | sh
> ```

> [tab] Windows
>
> ```powershell theme={null}
> irm https://redpill.ai/private-ai-proxy/install.ps1 | iex
> ```

> [tab] Homebrew
>
> ```bash theme={null}
> brew install dstack-tee/private-ai/private-ai-proxy
> ```

> [tab] npm
>
> ```bash theme={null}
> npm install --global private-ai-proxy
> ```
>
> Do not use `--omit=optional`; npm selects the native package through an optional dependency.

On Homebrew 6+, each fully qualified command above automatically taps the repository and trusts
only the item being installed. To use short names such as `brew install private-ai-proxy` or
`brew upgrade private-ai-proxy`, trust the whole tap first:

```bash theme={null}
brew tap dstack-tee/private-ai
brew trust dstack-tee/private-ai
```

Trust for an item installed by its fully qualified name persists, so later upgrades continue to
work. Older Homebrew versions do not have tap trust; the fully qualified one-line commands still
work there.

Verify the installation:

```bash theme={null}
pap --version
pap doctor
```

Rerun an official script to update a script-managed installation. Homebrew and npm manage their own
upgrades and removal. Release signatures and checksums are on the
[GitHub Releases page](https://github.com/Dstack-TEE/private-ai-gateway/releases).

## Profiles and sign-in

A profile is one RedPill workspace plus its credential. Add one with either:

* **Account login**: the app shows a device code and opens your browser. Approve the code, then
  pick a workspace in the app to receive an inference key for that workspace. The flow uses device
  authorization (RFC 8628), with no local callback, client secret, or refresh token; the sign-in
  token stays in memory. If saving fails, **Retry** reuses the approval.
* **API key**: **Get API key** opens the [dashboard](https://www.redpill.ai/dashboard); paste the key.

Credentials live in an owner-only, plaintext `credentials.toml` file in the app's settings
directory. The operating system's credential store is used only to migrate old installations;
profile exports never contain credentials. Sign in again or paste a new key to replace one; revoke
old keys in the dashboard. Phala Cloud profiles use the same form with Phala's device authorization;
custom endpoints accept API keys only.

## Privacy: what Protected does

Switching on **Protected** runs the ACI relying-party checks against the gateway with a fresh nonce:

1. the hardware quote verifies to the TEE vendor root and binds the report data;
2. the attested keyset digest matches the statement for that nonce;
3. the keyset has not expired;
4. source provenance is present and the app compose matches its measured hash; and
5. the TLS key actually used for the connection is in the attested keyset.

On success the app pins the channel to that keyset for the session and enables inference through
the Local API. A verification failure or network loss keeps connected agents pointed at the Local
API, which refuses requests until protection is verified again. Stopping Protected, choosing
**Stop All and Quit**, stopping the service, or disconnecting an agent restores its previous
configuration. Quitting only the desktop app leaves the backend running. Verification is never
restored from disk after a restart; it is redone.

## Agents

The **Agents** screen lists the agents the app can configure. **Connect** writes RedPill into the
agent's own provider settings, in the protocol the agent speaks, with an agent-scoped token for the
Local API. **Disconnect** restores the file you had before; edits you made in the meantime are
preserved, and an incomplete restore stays retryable.

| Agent | Protocol | Where the app writes | After connecting |
| - | - | - | - |
| Claude Code | Messages | Claude Code settings | Restart `claude` |
| Codex | Responses | Custom model provider in `config.toml` | Restart `codex` |
| DeepSeek Harness | Chat Completions | `~/.dsh/cordis.patch.yml` and `.credentials.yaml` | New session; restart headless/ACP processes |
| OpenCode | Chat Completions | `opencode.json` | Restart OpenCode |
| Pi | Chat Completions | Pi provider settings | Restart Pi |
| Hermes | Chat Completions | `config.yaml` | Restart Hermes |
| OpenClaw | Chat Completions | Native-host provider with a local token reference | Restart OpenClaw |
| Oh My Pi | Chat Completions | Local token and models file | Restart `omp` |

Only agents that are both connected and currently protected are authorized on the Local API.
Connecting from the CLI previews the change first and applies it with a revision, so a file that
changed in between is rejected rather than overwritten.

## Local API

While Protected is on, the app serves an OpenAI-compatible API on your machine:

| Field | Value |
| - | - |
| Base URL | `http://127.0.0.1:4180/v1` |
| API key | The client key shown on the Overview and Local API screens (`sk-pap-…`) |
| Models | The verified catalog for the active profile |

Any tool that accepts an OpenAI-compatible endpoint can use it, for example
[Cline](https://docs.redpill.ai/guides/integrations/coding-tools/cline.md). The Local API is plain HTTP on loopback by default; send
ordinary request bodies. It rejects end-to-end encryption headers because the app already owns the
verified channel. Its listener runs with the backend, but inference is refused without verified
protection. Rotate the client key from Local API settings or `token rotate`.

## Usage

Responses stream to the agent immediately. The app fetches the signed receipt for each response
afterwards and audits it against the attestation. **Usage** records every request with the agent,
model, tokens, estimated cost, and the audit result; an audit failure is recorded but cannot recall
bytes the agent already received. The Overview screen shows the current session's totals. Usage can
be filtered, exported to CSV, and cleared.

## Settings

* **Protect on launch** starts protection when the background service starts.
* **Open at Login** is an operating system preference set from the desktop app.
* **Advanced > Reset settings** stops protection, disconnects agents, restores defaults, generates
  a new web UI password, and disables Open at Login. Profiles, API keys, the local client key, and
  usage history are kept.
* Closing the window or choosing **Quit** from the tray or menu leaves the backend running.
  **Stop All and Quit** stops protection, restores agent configuration, and stops the backend.

## CLI

`pap` drives the same background service without a window. It comes with the desktop app or
[on its own](#cli). The macOS app registers it automatically; add `~/.local/bin` to your terminal's
PATH if needed. The Windows installer registers it on the user PATH, and Linux packages install
it system-wide. Settings > Advanced > **pap command** manages registration in the desktop app.
`private-ai-proxy` and `aci` are the same executable.

```bash theme={null}
pap doctor                  # local installation, settings, and backend diagnostics
pap service start           # background service
pap start --profile work    # verify the gateway and turn on Protected
pap agents connect codex    # add --model MODEL to pick a model yourself
pap status --json
pap stop                    # stop Protected and restore agent configuration
```

| Task | Command |
| - | - |
| Service and protection | `service start`, `start`, `stop`, `status --watch` |
| Profiles and credentials | `profiles login/list/show/add/edit/verify/use/remove`, `token clear-credential` |
| Agents | `agents list/connect/disconnect/disconnect-all` |
| Catalog and usage | `models list --refresh`, `usage list/show/export/clear` |
| Local API settings and token | `settings show/set`, `token show/rotate` |
| Verify any ACI service | `verify <url>`, `sessions <url>`, `serve <url>` |

Credentials are entered through a hidden prompt or `--key-stdin`, never as an argument. For
scripts, `--json --non-interactive` returns data and `--yes` approves a change; agent changes are
previewed with `--dry-run` and applied with the returned `--revision`. Exit status is `0` on
success, `2` for invalid arguments, `1` for operation failures. `verify`, `sessions`, and `serve`
work against any ACI service without a profile; `serve` refuses to start unless verification passes.

## Troubleshooting

| Symptom | Check |
| - | - |
| Protected will not turn on | Run `pap doctor`; it reports local installation, settings, and backend checks separately, with warnings for credentials other users can read or profiles without a saved key. |
| An agent still uses its old provider | Confirm it shows **Connected**, that Protected is on, and restart the agent. |
| A tool cannot reach `127.0.0.1:4180` | Confirm the backend is running and check Settings > Local API; inference requires verified protection. |
| Settings look wrong after an update | Settings > Advanced > Reset settings. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.