prd.live

A shared Markdown workspace for people and coding agents. Next.js serves the web client on Vercel. FastAPI runs on Contabo and stores workspace data in MariaDB.

Deployment

• Web: https://prdlive.vercel.app
• API: https://prdlive.5.104.87.93.sslip.io
• API reference: https://prdlive.5.104.87.93.sslip.io/docs
• Health: https://prdlive.vercel.app/health

The API runs as the prdlive system user through prdlive-api.service, listening on 127.0.0.1:8200. Nginx terminates HTTPS and forwards HTTP and WebSocket traffic. The existing MariaDB instance contains a dedicated prdlive database and a prdlive account restricted to that database. MariaDB remains bound to loopback. Existing VPS applications use their own databases and services.

The frontend forwards /api/* and /health to the HTTPS API origin. WebSocket events connect directly to the API. Vercel receives only the frontend configuration and API origin. Deployment credentials and database passwords stay outside the frontend deployment.

Open the workspace

Open the web URL and choose Connect to prd.live. Paste PRDLIVE_OWNER_TOKEN from the root .env to open the shared workspace. Enter dev in the same token field to open a sample workspace. Sample changes stay in this browser and never reach the API or remote database. An initial owner account and an empty shared workspace are provisioned. owner@prd.live is an internal account identifier; no email was sent or verified.

Human sessions expire after seven days. Issue a fresh session using:

server/.venv/bin/python server/deploy/manage.py session

This writes the token and its expiry to .env without printing the token. Set PRDLIVE_OWNER_EMAIL before running the command if you want to provision a different account. Existing sessions keep their original expiry and can be revoked through the API.

Google sign-in and invitation email delivery are not implemented. Development sign-in is disabled on the deployed API and hidden in the deployed client. Account provisioning is performed over SSH, never through an unauthenticated HTTP endpoint.

Repository layout

prd-live/
  .agents/       Local agent files, ignored by Git
  .ops/          Local run and integrated deployment scripts
  .env           All local and deployment configuration, ignored by Git
  AGENTS.md      Agent instructions, ignored by Git
  cli/           TypeScript CLI published as the prdlive npm package
  client/        Next.js source, dependencies, design references and UI artifacts
  server/        FastAPI, optional MCP adapter, migrations and tests
  README.md
  .gitignore

There is one .env, at the root. Both applications read it from there. Its file permissions are 0600. Do not put deployment secrets in variables prefixed with NEXT_PUBLIC_.

Configuration

Variable	Purpose
VERCEL_DEPLOY_KEY	Vercel access token supplied by the operator
VERCEL_ORG_ID, VERCEL_PROJECT_ID	Vercel deployment target
CONTABO_VPS_IP_ADDRESS	VPS address
CONTABO_VPS_DEFAULT_USER, CONTABO_VPS_PASSWORD	SSH deployment credentials
PRDLIVE_DATABASE_URL, PRDLIVE_DB_PASSWORD	Dedicated MariaDB connection
PRDLIVE_API_HOST, PRDLIVE_API_ORIGIN	Public API hostname and HTTPS origin
PRDLIVE_ENVIRONMENT, PRDLIVE_ALLOW_DEV_AUTH	API environment and development login guard
PRDLIVE_CORS_ORIGINS	JSON array of allowed browser origins
PRDLIVE_OWNER_EMAIL, PRDLIVE_OWNER_TOKEN	Bootstrap account and private human session
PRDLIVE_OWNER_TOKEN_EXPIRES_AT	Session expiry in UTC
NEXT_PUBLIC_SITE_URL	Canonical web URL
NEXT_PUBLIC_DATA_MODE	Legacy setting; the client selects the sample workspace only when the token is dev
NEXT_PUBLIC_API_URL	Empty for the same-origin API proxy
NEXT_PUBLIC_WS_URL	Direct HTTPS API origin used for WebSocket events
NEXT_PUBLIC_ALLOW_DEV_AUTH	Show development sign-in only when explicitly true

Only the four API runtime settings are copied to /opt/prdlive/.env on the VPS. That file is readable by root and the dedicated service group. The local .env also holds the deployment credentials and the owner token.

Local development

Requires Node.js 20.9+, npm, Python 3.11+, uv, SSH and sshpass.

Start the frontend and API together:

.ops/run.sh

The script opens an SSH tunnel to Contabo's existing MariaDB, then starts FastAPI at http://127.0.0.1:8000 and Next.js at http://127.0.0.1:3000. Occupied ports cause startup to fail without stopping existing processes.

There is one database: the remote prdlive database. Edits made with a real token affect the same data as production. No local database is created. The dev sample workspace stores example changes only in the browser. Startup does not seed data or run migrations. Development authentication stays disabled; use the same workspace token from .env for shared data.

Check only the SSH tunnel and database with read-only queries:

.ops/run.sh --check

Optional root .env settings are PRDLIVE_LOCAL_WEB_PORT (default 3000), PRDLIVE_LOCAL_API_PORT (default 8000), and PRDLIVE_LOCAL_DB_PORT (default 13306). The DB port is an SSH forwarding socket; MariaDB still runs on the VPS at 127.0.0.1:3306. Local URL overrides apply only to child processes and do not change the deployment settings in .env.

To develop only the frontend against the deployed API, run from client/:

PRDLIVE_API_ORIGIN=https://prdlive.5.104.87.93.sslip.io npm run dev

Redeploy

The scripts require uv, Node.js and npm. SSH and sshpass are needed for the VPS. Deployment also requires the Vercel CLI. Credentials come from the root .env.

.ops/deploy.sh

This checks the code, deploys FastAPI to Contabo, verifies its database connection, then deploys the frontend to Vercel. Finally it checks the frontend API proxy. Any failure stops the pipeline with a nonzero exit code. Owner tokens are not rotated.

The backend installs locked dependencies and applies Alembic migrations to the existing shared database. Only prdlive-api.service is restarted. The frontend deploys only client/ to the prdlive Vercel project. There is no alternate deployment database.

After changing Python dependencies, refresh the deployment requirements:

cd server
uv lock
uv export --extra server --no-dev --no-hashes --no-emit-project --format requirements-txt --output-file deploy/requirements.txt

On the VPS, inspect the service with systemctl status prdlive-api and journalctl -u prdlive-api. TLS renewal uses the existing Certbot timer and a deploy hook that reloads Nginx. A single API worker provides immediate events; use a shared event broker before scaling to multiple workers. A separate application backup schedule has not been configured.

Switch to prd.live

prd.live is the intended future domain. The current canonical URL remains prdlive.vercel.app until domain ownership and DNS are ready.

1. Add prd.live to the existing Vercel project and configure the DNS records Vercel provides.
2. Point api.prd.live to the VPS address.
3. Change NEXT_PUBLIC_SITE_URL to https://prd.live and PRDLIVE_API_HOST to api.prd.live in .env.
4. Run .ops/deploy.sh again. The helper updates the API origin and WebSocket URL and issues a certificate for the new API hostname.

Install the CLI

Install prdlive in a project, globally, or run it once without installing:

npm install prdlive
npm install --global prdlive
npx prdlive@latest --help

The standalone installer does not require Node.js. It selects the binary for the current operating system and CPU architecture, then verifies its SHA-256 checksum before installing it.

curl -fsSL https://prdlive.vercel.app/install.sh | sh

On Windows PowerShell:

irm https://prdlive.vercel.app/install.ps1 | iex

After installation:

prdlive login --api-url https://prdlive.vercel.app
cd YOUR_PROJECT
prdlive link --public-key YOUR_WORKSPACE_PUBLIC_KEY
prdlive docs list
prdlive docs read DOCUMENT_ID
prdlive docs update DOCUMENT_ID --file requirements.md --expected-version 1
prdlive work list
prdlive work status TASK_ID 'In progress'
prdlive discuss send DOCUMENT_ID 'Please verify this edge case' --relay-agents
prdlive discuss list DOCUMENT_ID --relay-agents
prdlive progress 'Implementing the requirements'

Create a space-scoped agent token through Connect an agent. prdlive login prompts without displaying the token. On macOS and Linux it stores credentials under the XDG configuration directory. On Windows it uses %APPDATA%. Credential files are keyed by API URL and kept outside the repository.

prdlive link writes a credential-free prd-live.toml at the repository root. It contains the API URL, workspace public key, and agent display name. The CLI discovers that file from child directories. Agent tokens expire after 90 days and inherit the owner's current membership.

Account commands such as whoami, spaces, and invitations accept work before linking. A single saved API is selected automatically. Pass --api-url when several APIs are saved. Project commands still require a repository link.

The Node CLI is the primary agent interface. The Python MCP adapter remains an optional server-side compatibility layer.

Current collaboration limits

Document changes are explicitly saved with optimistic version checks. Connected clients receive refresh events, but concurrent keystrokes are not merged like Google Docs. Conflicting drafts require review before saving again.

Humanized currently extracts prose and checklists. It does not generate a semantic explanation, and omits code and tables. Preview and Raw retain the full document.

The agent relay flag marks discussion messages for CLI readers. It does not push messages into running agents or automatically start an agent. Agents must fetch flagged messages and decide whether to respond. Phase and task status changes currently use last-write-wins semantics.

Release the CLI

The cli-release.yml workflow publishes the prdlive npm package through npm Trusted Publishing. GitHub Actions receives a short-lived OIDC credential for each release, so no npm access token is stored in GitHub.

Tags matching cli-v<package version> run the CLI, server, and web regression checks. The workflow then builds standalone executables for Linux x64 and ARM64, macOS Intel and Apple Silicon, and Windows x64 and ARM64. It publishes npm and attaches every executable plus SHA-256 checksums to the GitHub release.

Validation

cd cli
npm test
npm run build:standalone
cd ../client
npm test
npm run typecheck
npm run lint
npm run build
cd ../server
uv run ruff check prdlive tests migrations deploy
uv run pytest -q

Active tests check CLI behavior and database configuration without creating a database. Legacy database-writing tests are skipped because they assume a disposable schema. Their schema-reset fixture has been removed. Use .ops/run.sh --check for a read-only check of the shared remote database.

Design references and the upstream Base UI license are in client/docs.