[In development at AIVC · Check out the GitHub](#github)

# paas is AIVC's agent-first PaaS: one binary, any provider, and every project live on aivc.dev.

Coding agents drive it over MCP, the CLI or HTTP, all generated from one tool registry. Humans review what they did.

[Check out the GitHub](#github) · [Read the spec](#spec)

Built for: Claude Code, Cursor, Codex, MCP

Agent prompt:

> Run `paas describe_capabilities` to learn the spec schema and the tools, then write a spec.yaml for this repo and run `paas plan -f spec.yaml`. Show me the plan before applying anything.

## The spec

One YAML document describes the whole project across all its environments. `paas plan` accepts this one as written; its `web` service in production is served at `web-production-clearlinks.aivc.dev`.

```yaml
version: 1
project: clearlinks
lifecycle: persistent          # or: scratch
budget: { monthly_usd: 400, alert_at: 0.8 }

environments:
  production:
    placement: { region: us-east, providers: [hetzner, aws] }
  staging:
    from: production             # fork: inherits services and variables
    overrides:
      web: { replicas: 1 }

services:
  web:
    kind: app
    source: { repo: github.com/zach/clearlinks, branch: main, path: apps/web }
    build: railpack               # default; also: dockerfile, image
    port: 3000
    replicas: 2
    env: { DATABASE_URL: ${{ db.connection_url }} }

  db:
    kind: database
    engine: postgres@16
    branching: true               # copy-on-write forks for scratch envs
```

## Mission

paas is the control plane Railway would build if it started today, with agents as the first user and any provider as the compute. It is one open-source Go binary; the compute is any mix of Hetzner, AWS, bare metal or a laptop, joined into one pool, and every service gets its own subdomain of aivc.dev.

**Self-hosted PaaS tools reproduce Railway's surface, not its architecture.**

Railway's product model is right, but it is locked to Railway's own hardware. The experience is not portable; the builder is, so paas builds with Railpack by default.

So the data model changes. Projects are persistent by default, with a first-class scratch mode, budgets on every principal, and the primitives agents actually need built into the core rather than added later.

Every capability ships first as a tool: declarative **apply**, calls that block until something meaningful has happened, compact outputs, dry-run by default and scoped per-agent credentials. The dashboard is where humans review what the agents did.

Figure 1. Agents call one tool registry over MCP, the CLI or HTTP. paas server plans, applies, places and meters against the spec, bumps its version, and schedules onto a node pool that spans providers, where each service is served at its own aivc.dev subdomain. Every response carries status, a diff and cost.

References:

1. **The agent shift.** Railway's MCP server (August 2025) and Coolify's MCP docs are wrappers over existing APIs. Neither changes what a project is, how credentials are scoped, what a tool returns, or what happens to the hundreds of throwaway projects an agent creates in a week.
2. **Coolify and Dokploy.** Coolify (~57k GitHub stars) and Dokploy (~35k) are dashboards over Docker on servers you SSH into. Neither has a scheduler over a mixed fleet, a mesh across providers, environment forking as a first-class object, or per-service cost attribution. Star counts as of October 2026.
3. **Railway.** Project, environment and service; variable references; environment forks and PR environments. Railway runs all of it on its own bare-metal data centers. Railpack, its zero-config builder, is open source and offered to other platforms.
4. **Seven service kinds.** app, database, cron and bucket match Railway. sandbox, queue and webhook exist because agent-built products need them and no PaaS offers them as primitives. All seven expand today; `create_sandbox` and `fork_database` are next.

## How it works

1. **The spec is the product.** A project is one declarative document across all its environments. The HTTP API, the MCP server and the CLI are generated from the same tool registry, so nothing exists in one transport and not the others.
2. **Tools close the loop.** A deploy returns when the new deployment is healthy, has failed, or runs out of time, and says which. Errors carry what was observed and a suggestion, and outputs stay small enough to fit in an agent's context.
3. **Agents are principals, not tokens.** Every agent run gets its own short-lived, scoped grant with a spend ceiling. Destructive operations need a confirmation token, and every mutation lands in an append-only audit log with the task it was for.

Deliberately not in v1: GPU scheduling beyond label-based placement, managed vector databases (Postgres with pgvector covers it), serverless functions and a template marketplace.

## Status

v1 is done when our agents deploy **without a human in the loop** for a **month**.

| v1 target (scratch mode, cached framework) | Target |
| --- | --- |
| Healthy URL after `create_project` | < 60 s |
| First `sandbox_exec` result after `create_sandbox` | < 5 s |
| Node joined after install | < 10 min |

On main today:

- **25 tools** over MCP, the CLI and HTTP: describe_capabilities, request_confirmation, create_agent_grant, activity, list_approvals, decide_approval, create_join_token, list_nodes, update_node, get_cost, create_llm_key, logs, list_projects, get_project, plan, apply, create_project, fork_environment, delete_environment, delete_project, deploy, rollback, status, set_variables, set_lifecycle
- **7 service kinds**: app, database, cron, bucket, queue, webhook, sandbox
- **33 packages**, **111 test files**, **1 binary** (`CGO_ENABLED=0`)

**Why the control plane moves out.** Panels that SSH into the host leave the control plane holding root on every box. Coolify's January 2026 disclosure listed 11 vulnerabilities, three at CVSS 10.0. [Source](https://www.virtua.cloud/learn/en/concepts/coolify-vs-dokploy-self-hosted-paas)

**Where v1 engineering goes.** The PRD estimates the scheduler at 60% of the v1 build; everything else is 40%.

> “Railway's experience, your providers' prices, built for your agents.” The positioning, in one line · PRD v1

## Run it anywhere. Every project lands on aivc.dev.

One Go binary runs the control plane. Nodes from Hetzner, AWS, bare metal or a laptop join one pool over a WireGuard mesh, and each service is served at `service-env-project.aivc.dev`.

1. On bare metal
2. In any cloud
3. On your laptop

### Outbound-only by design.

Each node runs `paas node`, which dials out over mTLS with a short-lived certificate from the control plane's own CA. The control plane never holds SSH keys or root on a node, so compromising it yields the ability to schedule workloads, not root on the fleet.

- Outbound-only mTLS
- Scoped, expiring grants
- Append-only audit log

## Try it on your laptop.

`paas dev` starts a control plane and a local node in one process, with services on `*.localhost`. Point your agent at it with `paas mcp`.

## Progress

Built in waves by agents working in parallel on separate branches, each merged once its packages pass their tests. Oldest first.

Merged on main:

1. Network: mesh, ingress, DNS, network policy
2. Scheduler: placement, rollouts, reconcile, cost
3. LLM gateway: Anthropic and OpenAI-compatible, metered
4. Cloud APIs: SigV4, S3, provider adapters
5. Spec: parse, validate, fork, diff, etag
6. Foundation: store, auth, tools, HTTP API
7. Kinds: all seven v1 service kinds
8. Builds: Railpack, Dockerfile, embedded OCI registry
9. Transports: MCP server and generated CLI
10. Metering, logs, lifecycle and GC
11. Fleet: node agent, PKI, runtimes, paas dev
12. Engine: plan, apply, deploy, rollback

Next:

13. Agent tools: exec, migrations, sandboxes, database forks, webhooks
14. Dashboard and GitHub: review feed, push-to-deploy, PR environments
15. Our agents in production: 30 days, > 70% of mutations

## Contribute

Start with `docs/PRD.md` for the product, `docs/ARCHITECTURE.md` for packages and contracts, and `docs/DECISIONS.md` for what's settled. Agents work in parallel on separate branches, each inside the packages its brief assigns.

```sh
go build ./...
go test -race ./internal/<pkg>/...
go build -o paas ./cmd/paas
./paas dev   # control plane + local node, services on *.localhost
```

[Check out the GitHub](#github)

© 2026 AIVC · Internal tool