Get started

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.yml

Generate 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)" >> .env

Back 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 -d

Open 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 -d

Caddy 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:

VariableRequired / defaultDescription
POSTGRES_PASSWORDRequiredThe database's password, set when the database is first created. Changing it later needs a change in Postgres too.
AUTH_SECRETRequiredHashes sign-in tokens, and signs sandbox commands' tokens.
ENCRYPTION_KEYRequiredEncrypts credentials and vault entries. Never change it.
PROXY_URLhttp://localhostWhere Personal Agent Proxy is opened. An https:// address gets a certificate.
PROXY_VERSIONmainThe image tag to run. See upgrades.
ALLOWED_SIGNUP_EMAILSOptionalWho can create an account.
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, RESEND_KEY, EMAIL_FROMOptionalSign-in and connections with Google, and sign-in links by email.
PLAID_CLIENT_ID, PLAID_SECRET, PLAID_ENVOptionalConnecting banks through Plaid.
TYPESAFE_API_KEY, OPENROUTER_KEYOptionalQuick actions in the command bar; OPENROUTER_KEY also says where each Chat thread stands.
CLAUDE_AGENT_SDK, CLAUDE_AGENT_SDK_TURNSon, 1Whether 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:main

Docker 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.