pushleft
Deploy your first app
Manual contents
Handbook
HandbookPushleftArchitecture
Operate
Install the control planeYour own serversFleetOperations and alertsAuthenticationDomains and DNSUsage and budgetsScheduled jobsAbuse controlsAI provider proxyCustomer mailErrors and performanceLogs and metricsRetentionObject storageContainer registryGit server
Develop
The .pl.yaml manifestOnboard with an AI agentThe pl up demoBuild executorSource ingestionAgent gatewayManaged databasesSecurity findingsTunnels and shellsDev workspacesPrivate hostnamesMesh coordinatorsDesign baseline
Runbooks
Control-plane host failoverControl-plane PostgreSQL failoverControl-plane PostgreSQL restoreCustom domains and certificatesGateway key compromiseIngress host failureNode busyNode disk fullNode drain and replacementNode lostRegistry outageHetzner Robot hostsSecret rotationSecurity incidentStaging fleet on ProxmoxStaging build cacheStuck deploymentVault/OpenBao backup and recovery
Manual · docs/onboarding-skill.md

Onboard with an AI agent

This page shows you how to let an AI coding agent set up a Pushleft deployment. The Pushleft skill installs pl, reads your checkout, writes .pl.yaml, makes your Dockerfile run as a non-root user, sets secrets and deploys a preview. It asks you before production.

Install the skill

The skill is one file: https://pushleft.dev/skill.md. The skill page shows it with a copy button. For Claude Code, save it in the repository, so your team gets it too:

mkdir -p .claude/skills/pushleft
curl -fsSL https://pushleft.dev/skill.md -o .claude/skills/pushleft/SKILL.md

For every project on your machine, save it at ~/.claude/skills/pushleft/SKILL.md instead. Other agents can read the same file as instructions.

Use it

  1. Open the agent in the root of your checkout.
  2. Ask it to deploy the project to Pushleft, or run /pushleft in Claude Code.
  3. Read what it found: roles, ports, databases, secrets and paths the app writes.
  4. Answer its question when a role seems to need root. It recommends a non-root fix first.
  5. Give it each secret value through a file or run pl secrets set yourself. It never prints a value.
  6. It runs pl plan and pl up for a preview, and asks before pl up --production, pl down or pl db delete.

Changes to your repository

  • .pl.yaml: the roles, their ports (1024 or higher), health paths, databases, secret names, volumes and tmpfs mounts (manifest).
  • Dockerfile: a non-root USER in the final stage, files owned by that user and a port of 1024 or higher.
  • run_as: root: only on a role you confirm must run as root, with the reason you give (run as a non-root user).

Production builds fail with runs_as_root when a role would run as root without run_as (effective user). The skill checks the image before you deploy, so this does not happen at pl up.

Rendered from the repository at build time. Edit docs/onboarding-skill.md to change it.