Environment variables
Everything the Personal Agent Proxy server reads from its environment.
An empty variable counts as unset. With Docker Compose, the compose file's settings fill in most of them.
Core
The variables marked Required are needed for Personal Agent Proxy to work. The optional Core variables turn on quick actions, and set what the built-in agent on the Chat page runs on.
| Variable | Required / default | Description |
|---|---|---|
DATABASE_URL | Required | The Postgres connection string. Percent-encode special characters in the password (@ is %40). |
APP_URL | Required | Where people open Personal Agent Proxy, such as https://proxy.example.com. Sign-in links and Google sign-in return here, and it is the only origin the api accepts browser requests from. |
AUTH_SECRET | Required | Hashes magic-link tokens before they are stored, and signs the short-lived tokens sandbox commands are given to call back as their agent. Any long random string: openssl rand -hex 32. |
ENCRYPTION_KEY | Required | Encrypts the app passwords, OAuth tokens and vault entries Personal Agent Proxy stores: 32 random bytes, base64 (openssl rand -base64 32). Back it up: changing or losing it makes everything stored with it unreadable. |
TYPESAFE_API_KEY | Optional | A TypeSafe AI API key, for Jev, which picks the widget in the command bar that fits what a person types. What is typed there is sent to it. Without it, or without OPENROUTER_KEY, the command bar says it is not set up; everything else works as before. |
OPENROUTER_KEY | Optional | An OpenRouter API key, for the model that fills in the fields of the widget Jev picks in the command bar (gpt-oss-120b, on Cerebras or Groq), which also writes where each thread on the Chat page stands as its turn ends, from what the thread shows, and for the built-in agent on the Chat page in an organization with the openrouter experiment on, where an agent can be set to run on it (Claude Sonnet 5.5, or GLM 5.3). What is typed there is sent to it. Without it, or without TYPESAFE_API_KEY, the command bar says it is not set up, and without it a Chat thread is done once its agent stops, with no summary; everything else works as before. |
CLAUDE_AGENT_SDK | on | Whether the built-in agent on the Chat page runs on the Claude Agent SDK, under each member’s own Claude account, connected on the Account page: their conversations with it then go to Anthropic directly, as from Claude Code, and count against their plan. off takes the harness away: an agent then runs on OPENROUTER_KEY in an organization with the openrouter experiment on, and the Chat page says it is not set up everywhere else. Each turn on the SDK runs Claude Code as a subprocess of a few hundred megabytes; CLAUDE_AGENT_SDK_TURNS caps how many run at once. |
CLAUDE_AGENT_SDK_TURNS | 1 | How many turns of the built-in agent on the Claude Agent SDK one api instance runs at once; the rest wait their turn. Each is a subprocess of a few hundred megabytes, so raise it only with the memory to match. |
A Chat agent can be set to run on the Claude Agent SDK, under each member's own Claude account,
which runs Claude Code as a subprocess for each turn: a few hundred megabytes of memory while the
turn lasts, on top of the server's own. CLAUDE_AGENT_SDK_TURNS is how many such turns one server
runs at once, one unless you raise it; a server with little memory to spare can turn the SDK off
with CLAUDE_AGENT_SDK=off. Agents then run on OPENROUTER_KEY in an organization that has
OpenRouter turned on, and nowhere else: the Chat page says it is not set
up.
Sign-in
| Variable | Required / default | Description |
|---|---|---|
ALLOWED_SIGNUP_EMAILS | Optional | Who can create an account: comma-separated addresses and domains, such as me@example.com,example.org (@example.org works too). People who already have an account can always sign in. Unset, anyone who can reach Personal Agent Proxy can sign up. |
GOOGLE_CLIENT_ID | Optional | Turns on Google sign-in, with GOOGLE_CLIENT_SECRET, and connecting a Google account (Gmail, Calendar, Drive, Docs, Sheets, Slides, Contacts and Tasks). Register <APP_URL>/auth/google/callback and <APP_URL>/api/connections/google/callback as redirect URIs, enable the Gmail, Calendar, Drive, Sheets, People and Tasks APIs in the client’s Cloud project, and set the app’s publishing status to In production: in Testing, Google ends a connection’s sign-in after 7 days. |
GOOGLE_CLIENT_SECRET | Optional | The secret of the Google OAuth client. |
RESEND_KEY | Optional | Sends magic-link emails through Resend, with EMAIL_FROM. Without it the api writes each link to its log instead, which is enough when you are the only one signing in. |
EMAIL_FROM | Optional | The sender of magic-link emails, such as Personal Agent Proxy <login@example.com>, on a domain verified with Resend. |
Connections
| Variable | Required / default | Description |
|---|---|---|
PLAID_CLIENT_ID | Optional | Turns on connecting bank accounts through Plaid, with PLAID_SECRET: the client id from the Keys page of your Plaid dashboard. Plaid’s free Trial plan, for new teams in the US and Canada, connects up to 10 banks; past that, Plaid bills each connected bank monthly. |
PLAID_SECRET | Optional | The Plaid secret for the environment PLAID_ENV names: Sandbox and Production each have their own. |
PLAID_ENV | production | Which of Plaid’s environments to use: sandbox connects only Plaid’s test banks, signed in to with user_good and pass_good. |
GITHUB_CLIENT_ID | Optional | Turns on connecting GitHub, with GITHUB_CLIENT_SECRET and GITHUB_APP_SLUG: the client id of a GitHub App of your own, registered under your account’s or organization’s developer settings with <APP_URL>/api/connections/github/callback as a callback URL, “Expire user authorization tokens” on and “Request user authorization (OAuth) during installation” off, no webhook, Contents, Pull requests and Issues read and write, and Metadata read. People install it on the repositories they choose and sign in to it here. |
GITHUB_CLIENT_SECRET | Optional | A client secret of the GitHub App, generated on its page. |
GITHUB_APP_SLUG | Optional | The GitHub App’s name as it is in its address, github.com/apps/<slug>, where people are sent to install it on their account or an organization. |
SANDBOX_SERVICE_URL | Optional | Turns on sandboxes, computers of their own that agents can ask for: the address of a sandbox service speaking the protocol in @proxy/contracts/sandbox, such as https://sandboxes.example.com, reached with SANDBOX_SERVICE_TOKEN; hosted Personal Agent Proxy runs its own. dev instead runs commands in a directory on this server with no isolation at all, which only bun run dev takes. Unset, agents are offered no sandboxes. |
SANDBOX_SERVICE_TOKEN | Optional | What the sandbox service takes as the bearer token: the same long random string on both sides. |
FILES_DIR | Optional | Where the bytes of Files, each member’s drive, and of uploads on their way to Google Drive are kept: a directory on this server, such as /data/files, on a volume that is kept. This or FILES_S3_BUCKET is required. For one server; servers that share no disk need a bucket instead, which is used where both are set. |
FILES_S3_BUCKET | Optional | Keeps the bytes of Files and of uploads in a bucket that speaks S3’s protocol, Amazon’s, Cloudflare R2’s or MinIO’s: the bucket’s name, reached with FILES_S3_ACCESS_KEY_ID and FILES_S3_SECRET_ACCESS_KEY. This or FILES_DIR is required. Nothing in it is ever read by a browser from the bucket itself, so it needs no public access. |
FILES_S3_ACCESS_KEY_ID | Optional | The access key’s id for FILES_S3_BUCKET, allowed to put, get and delete its objects. |
FILES_S3_SECRET_ACCESS_KEY | Optional | The access key’s secret for FILES_S3_BUCKET. |
FILES_S3_ENDPOINT | Optional | The address of the store FILES_S3_BUCKET is in, where it isn’t Amazon’s: https://<account>.r2.cloudflarestorage.com for R2. |
FILES_S3_REGION | Optional | The region FILES_S3_BUCKET is in, such as eu-central-1; auto for R2. |
FILES_S3_PREFIX | Optional | What every object goes under in FILES_S3_BUCKET, such as proxy, for a bucket that holds more than this. |
FILES_MAX_MB | 100 | The largest file Files takes, and the largest blob, a file on its way between connections, as an email’s attachment put in Google Drive, in megabytes: at most 2047. |
DRIVE_COPY_MAX_MB | 25 | The largest copy of a Google Drive file kept here before an agent’s task first changes it, in megabytes: a file’s bytes, or a Doc’s, Sheet’s or Slides file’s export, which Google makes up to 10 MB. Past it, an uploaded file’s revision is kept for good in Drive instead, and a Doc’s is only noted. |
Agents' sandbox commands can use their connections through the pap command line tool
(Sandboxes), which the server builds and installs in a sandbox itself:
nothing is downloaded. For that, AUTH_SECRET and APP_URL must be set, as the commands are
given a token signed with the one to call back to the other; the sandboxes must be able to reach
APP_URL; and the sandbox service's image must have Node 20 or newer, which pap runs on.
Deployment
| Variable | Required / default | Description |
|---|---|---|
NODE_ENV | production | development turns on the dev-only sign-in and logs magic links instead of sending them. Only bun run dev sets it. |
PORT | 4000 | The port the api listens on. |
TELEMETRY_ENABLED | true | Sends one anonymous heartbeat a day: a random id, the version and the time. false turns it off. |
APP_VERSION | unknown | The version telemetry reports. The official image sets it. |
ALLOW_PRIVATE_HOSTS | false | Lets database and custom MCP server connections reach private and local addresses, such as 192.168.1.5, 10.0.0.7 or localhost. They are refused otherwise, so a connection can't be pointed at something else on the server's own network. Set it to true when self-hosting beside your database or server. |
Observability
The api writes its log to stdout, one JSON object per line, which docker compose logs api shows.
These ship it to a Loki as well, and its metrics to a Prometheus
or any other store taking OTLP, as hosted Personal Agent Proxy does; a self-hosted server needs
none of them.
| Variable | Required / default | Description |
|---|---|---|
LOKI_URL | Optional | Ships the api’s log to a Loki as well as to stdout: its address, such as loki-ab12:3100 for one of your own on the same private network, which takes no more and no scheme, or https://logs-prod-021.grafana.net for Grafana Cloud’s, with LOKI_USER_ID and GRAFANA_CLOUD_TOKEN. Unset, the log is written to stdout alone, one JSON object per line. |
LOKI_USER_ID | Optional | The numeric user id of the Grafana Cloud stack’s Loki, from its details page; unset for a Loki of your own. |
GRAFANA_CLOUD_TOKEN | Optional | A Grafana Cloud access policy token that may write logs and metrics. |
METRICS_OTLP_URL | Optional | Pushes the api’s metrics, such as request and query counts and latencies, over OTLP: to a Prometheus of your own taking OTLP, by its address alone, such as prometheus-ab12:9090, which takes no more and no scheme, or to Grafana Cloud’s gateway, such as https://otlp-gateway-prod-us-west-0.grafana.net/otlp/v1/metrics, with METRICS_USER_ID and GRAFANA_CLOUD_TOKEN. Unset, nothing is pushed. |
METRICS_USER_ID | Optional | The numeric instance id of the Grafana Cloud stack’s OTLP gateway, from its details page; unset for a Prometheus of your own. |
SLACK_BOT_TOKEN | Optional | Posts each sign-up to Slack, with SLACK_CHANNEL_SIGNUPS: a bot token (xoxb-…) of an app with chat:write, invited to the channel. Unset, nothing is posted. |
SLACK_CHANNEL_SIGNUPS | Optional | The id of the channel each sign-up is posted to, such as C0123456789, at the bottom of the channel’s About pane. |