Architecture
Ptah runs on three layers: the Ptah Cloud (management web app), the VPS workers (where Claude writes and runs code), and the Claude Code sessions (the actual model invocations). This page explains how these layers fit together and why.
The three layers
Layer 1 — Ptah Cloud
The Ptah Cloud is the web app your team logs into at app.byptah.com. It is a React SPA served from S3 and CloudFront, backed by an Elysia (Bun) API hosted on a VPS behind an Nginx reverse proxy, with PostgreSQL for persistent storage and Amazon S3 for file storage.
Responsibilities:
- User, organization, and role management
- Project, document, and session tracking
- WebSocket hub that routes messages between the web UI and VPS agents
- WBS generation pipeline
- Audit logging
The Ptah Cloud never runs client code directly. It only orchestrates VPS workers.
Layer 2 — VPS workers
A VPS worker is a server (typically Debian or Ubuntu) that you own. It runs:
- Docker and Docker Compose for containerized demo builds
- Nginx + Certbot for reverse proxying and Let's Encrypt SSL
- Git for project repositories
- Claude Code CLI (logged in with your Anthropic account)
- Ptah Agent — a small Fastify service that keeps a persistent WebSocket connection to Ptah Cloud
The agent is installed by a single curl command during the VPS setup wizard. It exposes a set of MCP tools that Claude uses to read documents, register annotations, and interact with the project workspace.
Each project has its own folder on the VPS (/projects/<project-id>/). Claude is invoked headless with --directory pointed at the project folder, so it only has access to that specific project's files.
Layer 3 — Claude Code sessions
A Claude Code session is a headless invocation of the claude CLI on a VPS. Ptah spawns a session when a user sends a message in the chat UI, pipes the message to claude -p, and streams the output back over WebSocket to the web app.
Sessions can be resumed, forked, and branched. Forking a session creates a new child session that inherits the full context of the parent, which is useful when you want to try a different approach without losing the original thread.
Shared VPS infrastructure
Ptah follows a convention where every VPS worker runs one shared PostgreSQL container, one shared Docker network (ptah-shared), and a host-level Nginx for serving static frontends. Each project uses its own database (created lazily on first deploy) and its own backend container on the shared network.
This model lets a single VPS host many demo projects without the overhead of a full container stack per project.
Data flow: chatting with Claude
- A user opens a project in the web app and types a message in the chat.
- The web app sends the message over WebSocket to Ptah Cloud.
- Ptah Cloud resolves the project's VPS, looks up the active session, and relays the message to the agent on that VPS.
- The agent invokes
claude -pwith the project directory, the message, and any relevant context. - Claude streams output tokens back to the agent, which forwards them to Ptah Cloud, which forwards them to the web app.
- When Claude finishes, the agent commits any file changes to the project repository and reports the final status.
The user sees tokens appear in real time, just like a local Claude Code session.
Security boundaries
- Organization isolation: all API routes are scoped by
org_idand enforced by middleware. A user cannot read or write data in an organization they are not a member of. - VPS isolation: each VPS is owned by exactly one organization. Agents authenticate with a token generated during setup and scoped to that organization.
- Project isolation: Claude sessions are scoped to a single project folder on the VPS. Cross-project access requires explicit user action.
- Secrets: Ptah Cloud never stores Claude or cloud provider API keys for the user. The Claude login lives on the VPS, owned by the organization.