# Superzero — full reference for agents

Status: P0 prototype. Not open for sign-up. No public pricing.
Index: https://www.superzero.dev/llms.txt

## What it provisions

| Resource | Provider in P0 | Notes |
|---|---|---|
| database | Neon Postgres | extensions: pgvector, postgis, pg_cron, uuid-ossp |
| compute  | self-hosted containers | Nixpacks build, scale-to-zero, custom domain |
| auth     | built in | email, google, apple, SMS OTP |
| push     | built in | APNs and FCM |

Compute is self-hosted rather than resold. Every PaaS reseller term reviewed forbids
reselling; database and SMS vendors have partner programmes that permit it. The general
rule found: a provider allows it when you bring them customers, and forbids it when you
take their customers.

## Declarative config

One file, `superzero.config.ts` (or `.mjs` on Node older than 24). The schema is strict:
unknown keys are rejected. Secrets are never written in the file; use `$SECRET` references
and set the values with `superzero secrets set`.

import { defineConfig } from '@superzero/config'

export default defineConfig({
  name: 'shopping-app',
  region: 'ap-northeast-1',

  database: { extensions: ['pgvector'] },

  compute: {
    framework: 'auto',        // detected by Nixpacks
    envFrom: ['database', 'auth'],
    idleTimeout: '15m',       // scale to zero
  },

  auth: {
    providers: ['email', 'google'],
    sms: { enabled: true, allowedCountries: ['JP'] },
  },

  push: {
    ios: { bundleId: 'com.example.shop', keyId: '$SECRET', teamId: '$SECRET' },
    android: { packageName: 'com.example.shop' },
  },
})

### Fields

- `name` (required): lowercase letters, digits, hyphens. Max 63 characters.
- `region`: `ap-northeast-1` only in P0.
- `database.engine`: `postgres`. `database.extensions`: array of the four above.
- `compute.framework`: `auto` | `nextjs` | `node` | `python` | `docker`. Default `auto`.
- `compute.buildCommand`, `compute.startCommand`: override detection.
- `compute.envFrom`: which resources inject connection details as environment variables.
  This is the input to the dependency graph, so ordering is derived, not declared.
- `compute.idleTimeout`: duration like `15m`. Time without traffic before scaling to zero.
- `compute.memoryMb`: 256 to 4096. Default 512.
- `auth.providers`: subset of `email`, `google`, `apple`. At least one.
- `auth.sms`: `{ enabled: true, allowedCountries: ['JP'] }`. `allowedCountries` is
  required and may not be empty — an omitted list would otherwise mean "every country",
  which is how SMS pumping fraud starts.
- `auth.jwt.expiresIn`: duration like `1h`.
- `push.ios`: `bundleId`, `keyId`, `teamId`. `push.android`: `packageName`.
  At least one of the two is required. Web Push is not supported in P0.
- `email` is not accepted in P0. The schema rejects it rather than accepting a key that
  would fail later at plan time.

## Commands

    superzero plan      Show what would change. No side effects, ever.
    superzero apply     Make it so. Idempotent: re-running changes nothing.
    superzero verify    Check that what was built actually works.
    superzero status    Current state of every resource.
    superzero secrets   Set and list secret names (never values).
    superzero logs      Container logs.

Destructive changes (deleting a database, for example) are refused unless
`--allow-destructive` is passed. This is enforced in the planner, not the CLI, so it
holds for MCP callers too.

## MCP tools

    superzero_plan            same as the plan command
    superzero_apply           same as the apply command
    superzero_verify          same as the verify command
    superzero_status          same as the status command
    superzero_config_schema   JSON Schema for the declarative config

The JSON Schema is generated from the same definition that validates the config, so
tool definitions and validation cannot drift apart.

## Errors

Every failure is returned in one shape. HTTP status is not the signal to branch on —
read `ok` and `suggestedFix`.

{
  "code": "COMPUTE_CONTAINER_EXITED",
  "message": "The container started but exited immediately (id: c2a4f9b2e1de).",
  "suggestedFix": {
    "command": "superzero logs",
    "description": "Read the container logs to see why the process exited.
                    Set compute.startCommand in superzero.config.ts if the
                    framework was detected incorrectly."
  }
}

- `code`: stable identifier, safe to branch on.
- `message`: what happened, with the specific identifier involved.
- `suggestedFix.command`: the command to run next.
- `suggestedFix.description`: what to change, naming the field to change it in.

An apply that fails still returns HTTP 200 with `ok: false`. This is deliberate: an agent
should read the failure and act on it, not treat a transport-level status as the outcome.

## Guarantees the engine holds

- plan produces no side effects.
- apply is idempotent; the second run reports no changes.
- Resources are created in dependency order derived from `compute.envFrom`.
- A partially failed apply can be re-run and will resume, not duplicate.
- Destructive changes require an explicit flag.
- Drift between declared and actual state is detected on read.

## Console

There is a read-only web console at https://www.superzero.dev/admin, gated by an admin token. It has no
mutating operations by design: if changes were possible from a dashboard, the question this
project exists to answer — whether an agent can complete the whole setup alone — would stop
being measurable.