# AGENTS.md — Build guide for Replit ## Project scope Run a private code-server on a user-owned VPS behind HTTPS and authentication. Add a small CLI that creates projects from reviewed templates, stores secrets outside source and prepares an explicit deployment preview. Catalogue verdict: kinda. A dev container plus code-server plus deployment can replace some value, but Replit's beginner-friendly cloud IDE, agents, secrets, hosting, and zero-setup environment are a platform. Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope. ## Working agreement - Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture. - Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled. - After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran. - Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply. - Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization. ## Prerequisites - A user-owned Linux server, domain/DNS control, sufficient disk and memory, and the selected upstream release documentation. Record actual image names and required variables rather than guessing. - Implementation components: Docker Compose around the selected upstream application, pinned release/image digest and persistent volumes. Caddy for HTTPS, environment templates without secrets, and operator scripts for backups, upgrades and restore. - Scope boundary: Multi-tenant sandboxing, managed agents and automatic hosting infrastructure are excluded. ## Stack and architecture - Docker Compose around the selected upstream application, pinned release/image digest and persistent volumes. - Caddy for HTTPS, environment templates without secrets, and operator scripts for backups, upgrades and restore. - Operating records: code-server configuration, user project roots, template revisions, environment references and backup/deploy receipts ## Security and data integrity - Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. - Correctness boundary: The browser IDE is a powerful shell and must not be public; project creation cannot overwrite existing paths or expose secrets in templates. - Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration. - Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. ## Agent implementation rules - Project rule — operating records: code-server configuration, user project roots, template revisions, environment references and backup/deploy receipts - Project rule — preserve this invariant: The browser IDE is a powerful shell and must not be public; project creation cannot overwrite existing paths or expose secrets in templates. - Project rule — acceptance evidence: Create two projects with the same requested name and reject the second safely; restore a backed-up project into a new directory with its Git history intact. ## Optional agent skills and references - Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission. - Optional external skill: [agent-browser](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md) — Automate browser interaction using accessibility snapshots, element references and reproducible navigation workflows. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission. Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism. ## Distribution ideas These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone. - Demonstrate the actual Replit-inspired workflow with owned or clearly labeled sample data: Run a private code-server on a user-owned VPS behind HTTPS and authentication. Add a small CLI that creates projects from reviewed templates, stores secrets outside source and prepares an explicit deployment preview. - Publish a reproducible walkthrough with this observable result: Create two projects with the same requested name and reject the second safely; restore a backed-up project into a new directory with its Git history intact. - Explain who can operate this scoped tool, its setup and ongoing costs, and these remaining product gaps: Multi-tenant sandboxing, managed agents and automatic hosting infrastructure are excluded. Avoid guaranteed savings, performance scores or implied endorsement. ## Engineering roadmap 1. Phase 1 — Select and document the upstream release. Run a private code-server on a user-owned VPS behind HTTPS and authentication. Add a small CLI that creates projects from reviewed templates, stores secrets outside source and prepares an explicit deployment preview. Record the release, documented host requirements and upstream deployment reference. Start in an isolated staging directory. Keep these exclusions explicit: Multi-tenant sandboxing, managed agents and automatic hosting infrastructure are excluded. 2. Phase 2 — Configure the maintained application. Record code-server configuration, user project roots, template revisions, environment references and backup/deploy receipts Configure supported environment variables, credentials, volumes and database connections. Use upstream installation and migration procedures; do not create a replacement application schema, authentication service or dashboard. Preserve this rule: The browser IDE is a powerful shell and must not be public; project creation cannot overwrite existing paths or expose secrets in templates. 3. Phase 3 — Use the upstream workflow. Perform the stated workflow through the upstream interface or its documented CLI. Add an operator helper script only when the working slice explicitly calls for it; do not build a new input/review/output frontend. Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration. 4. Phase 4 — Review access and failure states. Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. Document health checks, reconnect/restart steps and how missing configuration is surfaced by the upstream service. Keep public and administrative endpoints separate. 5. Phase 5 — Recovery and upgrades. Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. Document upstream migration compatibility before an upgrade, the retained rollback point and the sequence for restoring configuration, data and files. 6. Phase 6 — Operator handoff and acceptance. Create two projects with the same requested name and reject the second safely; restore a backed-up project into a new directory with its Git history intact. Record actual staging observations separately from these proposed checks. Deliver the pinned configuration, secret-free environment template, backup/restore runbook and any explicitly scoped helper scripts; do not claim equivalence to managed hosting. ## Paid-product capabilities outside this build - zero-setup browser IDE - hosted agents - multiplayer - templates - deployments - education/community workflows ## Implementation prompt WORKING SLICE Run a private code-server on a user-owned VPS behind HTTPS and authentication. Add a small CLI that creates projects from reviewed templates, stores secrets outside source and prepares an explicit deployment preview. Operate this scoped Replit-inspired deployment through the maintained upstream application. Record its configuration and failure states; do not rebuild its schema, interface or services. Architecture - Docker Compose around the selected upstream application, pinned release/image digest and persistent volumes. - Caddy for HTTPS, environment templates without secrets, and operator scripts for backups, upgrades and restore. Prerequisites and limits A user-owned Linux server, domain/DNS control, sufficient disk and memory, and the selected upstream release documentation. Record actual image names and required variables rather than guessing. Outside this release: Multi-tenant sandboxing, managed agents and automatic hosting infrastructure are excluded. Configuration and correctness code-server configuration, user project roots, template revisions, environment references and backup/deploy receipts Invariant: The browser IDE is a powerful shell and must not be public; project creation cannot overwrite existing paths or expose secrets in templates. Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration. Security and privacy Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. Recovery and export Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. Implementation order 1. Phase 1 — Select and document the upstream release. Run a private code-server on a user-owned VPS behind HTTPS and authentication. Add a small CLI that creates projects from reviewed templates, stores secrets outside source and prepares an explicit deployment preview. Record the release, documented host requirements and upstream deployment reference. Start in an isolated staging directory. Keep these exclusions explicit: Multi-tenant sandboxing, managed agents and automatic hosting infrastructure are excluded. 2. Phase 2 — Configure the maintained application. Record code-server configuration, user project roots, template revisions, environment references and backup/deploy receipts Configure supported environment variables, credentials, volumes and database connections. Use upstream installation and migration procedures; do not create a replacement application schema, authentication service or dashboard. Preserve this rule: The browser IDE is a powerful shell and must not be public; project creation cannot overwrite existing paths or expose secrets in templates. 3. Phase 3 — Use the upstream workflow. Perform the stated workflow through the upstream interface or its documented CLI. Add an operator helper script only when the working slice explicitly calls for it; do not build a new input/review/output frontend. Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration. 4. Phase 4 — Review access and failure states. Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. Document health checks, reconnect/restart steps and how missing configuration is surfaced by the upstream service. Keep public and administrative endpoints separate. 5. Phase 5 — Recovery and upgrades. Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. Document upstream migration compatibility before an upgrade, the retained rollback point and the sequence for restoring configuration, data and files. 6. Phase 6 — Operator handoff and acceptance. Create two projects with the same requested name and reject the second safely; restore a backed-up project into a new directory with its Git history intact. Record actual staging observations separately from these proposed checks. Deliver the pinned configuration, secret-free environment template, backup/restore runbook and any explicitly scoped helper scripts; do not claim equivalence to managed hosting. Acceptance Create two projects with the same requested name and reject the second safely; restore a backed-up project into a new directory with its Git history intact. Use real source data or clearly labeled fixtures. Explain unsupported input and provider failures; do not fabricate analytics, delivery receipts, accuracy claims or security guarantees. Optional agent guidance Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission. Optional external skill: [agent-browser](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md) — Automate browser interaction using accessibility snapshots, element references and reproducible navigation workflows. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission. Project rule — operating records: code-server configuration, user project roots, template revisions, environment references and backup/deploy receipts Project rule — preserve this invariant: The browser IDE is a powerful shell and must not be public; project creation cannot overwrite existing paths or expose secrets in templates. Project rule — acceptance evidence: Create two projects with the same requested name and reject the second safely; restore a backed-up project into a new directory with its Git history intact. ## Completion evidence Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.