← Back to docs

VPS setup

Ptah needs at least one VPS worker to run Claude sessions and host demo projects. This page explains what you need, how the install script works, and how to troubleshoot common issues.

Requirements

  • A VPS with Debian 12+ or Ubuntu 22.04+ and root (or sudo) access
  • At least 4 GB of RAM and 2 CPU cores — 8 GB / 4 cores recommended if you plan to host several demos
  • 40 GB of disk space, 80 GB or more recommended
  • A public IP address
  • Ports 22 (SSH), 80 (HTTP), and 443 (HTTPS) open to the internet
  • Wildcard DNS for your organization: *.<org-code>.byptah.com pointing to the VPS IP

You also need an Anthropic account with an active Claude subscription. The login is performed once on the VPS and is used for every session running on that VPS.

Running the setup wizard

Open VPS → Add VPS in the Ptah web app and follow the wizard:

Step 1 — Connection details

Enter the VPS IP address and the SSH user. Ptah will SSH in during install, so the user must have passwordless sudo (or be root).

Step 2 — SSH key

You have two options:

  • Upload an existing key. Paste a private key that is already authorized on the VPS.
  • Generate a new key. Ptah generates a key pair in-memory, shows you the public key, and asks you to add it to ~/.ssh/authorized_keys on the VPS before continuing.

Ptah stores the private key encrypted in the database and uses it only for agent install and recovery operations.

Step 3 — Install script

Ptah runs an idempotent install script that:

  1. Installs Docker, Docker Compose, Nginx, Certbot, and Git (skips if already present)
  2. Creates the shared Docker network ptah-shared
  3. Starts a shared PostgreSQL container
  4. Installs the Claude Code CLI
  5. Prompts you to log in to Claude (one-time, interactive)
  6. Installs the Ptah Agent as a systemd service
  7. Generates an agent token and registers the VPS with Ptah Cloud

You can watch the install log in real time in the web app. If a step fails, the wizard shows you which step and lets you retry.

Step 4 — DNS configuration

Add a wildcard DNS record for your organization:

*.acme.byptah.com.  A  203.0.113.10

Replace acme with your organization code and 203.0.113.10 with your VPS IP. Ptah automatically requests Let's Encrypt certificates on-demand when a new demo is deployed.

Step 5 — Verification

Ptah runs a smoke test: it creates a temporary demo project, deploys a "hello world" container, hits the demo URL, and then tears everything down. When the smoke test passes, the VPS is marked healthy and available.

Multiple VPS workers

You can connect more than one VPS. Reasons to do so include:

  • Running different tech stacks that conflict on the same host
  • Isolating high-value clients from experimental work
  • Geographic distribution so demos load quickly for clients in different regions

The VPS picker on the project creation page lets you choose which worker to use per project.

Troubleshooting

The agent is stuck in "Connecting" state. Check that ports 80 and 443 are open outbound from the VPS. The agent uses a WebSocket connection to Ptah Cloud and cannot connect through a restrictive firewall.

Claude login fails. The login step is interactive and must be completed manually in the terminal during install. If you skipped it, SSH into the VPS and run claude login as the deploy user, then restart the Ptah Agent with systemctl restart ptah-agent.

Let's Encrypt certificate requests are rate-limited. Let's Encrypt has a staging environment for testing. Set PTAH_ACME_STAGING=1 on the agent before your first few deploys if you expect many retries.

Related pages

  • Architecture — how the agent fits into the overall system.
  • Projects — assigning a project to a VPS.