Get started
Run Personal Agent Proxy on one server with Docker Compose, with Postgres and HTTPS in the same file.
Run Personal Agent Proxy on a server reachable from the internet, such as a VPS, with a domain pointed at it. Agents reach it from wherever they run, and most, such as Claude, Claude Duet, Claude Desktop, Devin, ChatGPT and Poke, run their connectors on their own servers, so they can only use it once it has a public HTTPS address.
The compose file runs three containers: Personal Agent Proxy, Postgres, and Caddy in front of them for HTTPS. Only Caddy is reachable from outside, on ports 80 and 443.
Get the compose file
mkdir proxy && cd proxy
curl -O https://raw.githubusercontent.com/personalagentproxy/proxy/main/docker-compose.ymlGenerate the secrets
They go in a .env file next to the compose file, which Docker Compose reads on its own.
echo "POSTGRES_PASSWORD=$(openssl rand -hex 16)" >> .env
echo "AUTH_SECRET=$(openssl rand -hex 32)" >> .env
echo "ENCRYPTION_KEY=$(openssl rand -base64 32)" >> .envBack up ENCRYPTION_KEY somewhere apart from the server. It encrypts the app passwords and
vault entries in the database, so changing or losing it makes them unreadable, backups
included.
Start Personal Agent Proxy
docker compose up -dOpen http://localhost on the same machine. To try Personal Agent Proxy on your own computer, you can stop here and sign in, but only local MCP clients such as Claude Code, Devin CLI and Hermes Agent can reach it until it has a domain.
Give it a domain
Point an A record for your domain at the server, and make sure ports 80 and 443 are open to it.
Then tell Personal Agent Proxy its address, and who can create an account, before anyone else can
reach it:
echo "PROXY_URL=https://proxy.example.com" >> .env
echo "ALLOWED_SIGNUP_EMAILS=you@example.com" >> .env
docker compose up -dCaddy gets a certificate for the domain from Let's Encrypt on its first request, and renews it.
Sign in
Enter your email on the sign-in page. Until sending email is set up, Personal Agent Proxy writes the sign-in link to its log instead:
docker compose logs proxy | grep "Magic Link"Open the link to sign in. Sign-in sets up sending the links by email, and signing in with Google.
Settings
The compose file reads these from .env:
| Variable | Required / default | Description |
|---|---|---|
POSTGRES_PASSWORD | Required | The database's password, set when the database is first created. Changing it later needs a change in Postgres too. |
AUTH_SECRET | Required | Hashes sign-in tokens, and signs sandbox commands' tokens. |
ENCRYPTION_KEY | Required | Encrypts credentials and vault entries. Never change it. |
PROXY_URL | http://localhost | Where Personal Agent Proxy is opened. An https:// address gets a certificate. |
PROXY_VERSION | main | The image tag to run. See upgrades. |
ALLOWED_SIGNUP_EMAILS | Optional | Who can create an account. |
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, RESEND_KEY, EMAIL_FROM | Optional | Sign-in and connections with Google, and sign-in links by email. |
PLAID_CLIENT_ID, PLAID_SECRET, PLAID_ENV | Optional | Connecting banks through Plaid. |
TYPESAFE_API_KEY, OPENROUTER_KEY | Optional | Quick actions in the command bar; OPENROUTER_KEY also says where each Chat thread stands. |
CLAUDE_AGENT_SDK, CLAUDE_AGENT_SDK_TURNS | on, 1 | Whether a Chat agent can be set to run on members' own Claude accounts, and how many such turns run at once. |
Every other setting is in Environment variables; add one under the
proxy service's environment in the compose file.
Without Docker Compose
The image runs anywhere containers do, with any Postgres. Give it the required variables and put HTTPS in front of port 4000:
docker run -d -p 4000:4000 \
-e DATABASE_URL="postgres://user:password@host:5432/proxy" \
-e APP_URL="https://proxy.example.com" \
-e AUTH_SECRET="…" \
-e ENCRYPTION_KEY="…" \
ghcr.io/personalagentproxy/proxy:mainDocker Compose on one server has no failover, and keeps the database on that server's disk. Back it up, or run the image on its own against a managed Postgres, as above.