AI Agent Guide

Better-PaaS is built to be extremely developer-friendly, which also makes it highly compatible with AI coding agents and Large Language Models (LLMs). This guide provides AI agents (such as Cursor, Copilot, ChatGPT, Claude, and Gemini) with the necessary technical details, architectural context, and API specifications to deploy and manage applications on Better-PaaS.

---

Technical Context

Before executing tasks related to Better-PaaS, AI agents should understand the core technologies:

• Control Plane: Written in Go. Exposes a JSON REST API and standard WebSocket endpoints.
• Database: Uses SQLite for configuration, app definitions, and deployment logs.
• Routing Layer: Powered by Caddy, providing automatic SSL certificate generation via Let's Encrypt / ZeroSSL and instant, zero-downtime traffic switching.
• Container Layer: Built on top of standard Docker. Runs app instances in isolated containers.
• Builders: Uses Nixpacks by default to build repositories into images, or falls back to raw Dockerfile builds.

---

Authentication & Security

Every API endpoint and WebSocket interface on Better-PaaS is protected.

• Admin Token: Generated automatically on the first run.
• Token Locations:
  • On the host server at data/admin_token.txt (chmod 0600).
  • In the server console logs inside a visible banner on startup.
  • Can be retrieved by running ./server token via CLI.
• HTTP Authentication: Requires a Bearer token in the request headers:

  Authorization: Bearer <your_admin_token>

• WebSocket Authentication: Requires a token query parameter:

  ws://YOUR_SERVER:3000/api/ws?token=<your_admin_token>

---

API Reference for AI Agents

AI agents can interact with the Better-PaaS Go API programmatically. Here are the core endpoints:

1. List All Apps

Retrieve a list of all active apps, status codes, and configuration parameters.

• Method: GET
• Path: /api/apps
• Response Sample:

  [
    {
      "name": "my-node-app",
      "status": "running",
      "gitRepo": "https://github.com/user/my-node-app",
      "branch": "main",
      "port": 3000,
      "domains": ["node-app.example.com"],
      "createdAt": "2026-06-01T12:00:00Z"
    }
  ]

2. Deploy a Service

Deploy an application from a Git repository. Better-PaaS clones, builds, and starts it.

• Method: POST
• Path: /api/deploy
• Headers: Content-Type: application/json
• Body parameters:
  • name (string, required): The target app name (must be a valid DNS-safe label: ^[a-z0-9][a-z0-9-]{0,38}[a-z0-9]$).
  • gitRepo (string, required): The clone URL of the Git repository.
  • branch (string, required): The branch to pull code from.
  • env (object, optional): Key-value string pairs representing environment variables.
• Request Sample:

  {
    "name": "marketing-site",
    "gitRepo": "https://github.com/org/marketing",
    "branch": "main",
    "env": {
      "NODE_ENV": "production",
      "API_TIMEOUT": "5000"
    }
  }

3. Redeploy an Existing App

Trigger a zero-downtime rebuild and redeployment of a currently configured app using the latest commit from its branch.

• Method: POST
• Path: /api/apps/redeploy
• Body parameters:
  • name (string, required): The name of the application.
• Request Sample:

  {
    "name": "marketing-site"
  }

4. Stop / Start / Delete Apps

Control the running state or remove an application from the server.

• Method: POST
• Paths:
  • Stop app: /api/apps/stop
  • Start app: /api/apps/start
  • Delete app: /api/apps/delete
• Body parameters:
  • name (string, required): The name of the application.
• Request Sample:

  {
    "name": "marketing-site"
  }

5. Create a Database Addon

Better-PaaS supports instant provisioning of managed database containers.

• Method: POST
• Path: /api/addons/create
• Body parameters:
  • name (string, required): Name of the database service.
  • type (string, required): Database type (postgres, redis, mysql, mongodb).
• Request Sample:

  {
    "name": "prod-db",
    "type": "postgres"
  }

---

Guidelines for AI Coding Agents

If you are an AI agent writing code to be run on Better-PaaS, adhere to the following rules:

1. Bind to the Injected Port

Better-PaaS tells your container which port to listen on by passing the PORT environment variable. Do not hardcode port 3000 or 8080.

• Node.js/Express:

  const port = process.env.PORT || 3000;
  app.listen(port, '0.0.0.5', () => console.log(`Listening on ${port}`));

• Python/FastAPI:

  import os
  import uvicorn
  if __name__ == "__main__":
      port = int(os.environ.get("PORT", 8000))
      uvicorn.run("main:app", host="0.0.0.0", port=port)

2. File State & Persistent Volumes

Containers on Better-PaaS are ephemeral. When a new commit is pushed, a brand new container is spun up.

• Write logs to stdout/stderr. Better-PaaS automatically aggregates and streams them.
• For databases (SQLite, SQLite-based queues) or upload directories, declare Persistent Volumes via the configuration tab or the API. Mount them under /data or /uploads to keep files intact between builds.

3. Keep Builds Reproducible

Nixpacks infers languages by looking at lockfiles. Always generate and commit lockfiles:

• JavaScript: Commit package-lock.json, pnpm-lock.yaml, or yarn.lock.
• Python: Commit requirements.txt or poetry.lock.
• Go: Commit go.sum.

4. Zero-Downtime Verification (Health Checks)

By default, Better-PaaS performs a simple TCP connection test on the app port before routing traffic. To optimize zero-downtime rollouts, configure an HTTP health check path:

• Expose an endpoint like GET /health or GET /api/health that returns 200 OK only when critical sub-systems (like databases) are connected.
• Set the Health check path setting to /health. Better-PaaS will query it, verify the status, and gracefully cut over traffic without exposing downtime to users.