# APCO Cloud

> APCO Cloud is a mini-PaaS: `apco deploy` puts static/SSR source or an existing OCI image on https://<slug>.apco.space, with managed Postgres or MariaDB, realtime (SSE), logs, analytics, and a CLI/MCP built to be driven by AI agents.

Full corpus for ingestion: https://docs.apco.space/llms-full.txt

## Guides

- [Analytics](https://docs.apco.space/guides/analytics): Every project gets built-in traffic, web, and resource analytics — no snippet to install, no third-party service. Open your project in the dashboard to see them.
- [Custom domains <Badge type="tip" text="Pro" />](https://docs.apco.space/guides/custom-domains): Serve a project on your own domain instead of (or alongside) your-slug.apco.space. Certificates are issued and renewed automatically — you only create two DNS records.
- [Database Studio](https://docs.apco.space/guides/database-studio): Every project with a managed database gets a Database Studio in the dashboard: connection details, a table browser with inline row editing, a SQL console, migrations history, a usage panel, and backups. Open your project, switch to the database section, then choose Production, Preview, or Dev. The selector is stored in the URL and every read or mutation is scoped to that channel.
- [Managed databases](https://docs.apco.space/guides/database): Pro-plan projects choose Postgres 17 or MariaDB 12.3 LTS and provision isolated databases for Production, Preview, and Dev. The engine choice becomes immutable when the first branch is created. The platform injects the current channel's DATABASEURL into your app automatically, SQL migrations ship with your deploys, and the dashboard includes a channel-aware Database Studio for browsing, querying, usage, migrations, and backups.
- [Deploying apps](https://docs.apco.space/guides/deploy): apco deploy puts source code or an existing OCI image live at the authoritative project URL—with zero downtime on redeploys. Source manifests are packed/uploaded/built; dockerimage manifests send JSON, pull from a registry, and pin the immutable digest without uploading source.
- [Hybrid dev](https://docs.apco.space/guides/dev): apco dev blends local development with the cloud: by default it runs your framework's own HMR dev server locally; add flags to pull in the cloud database or live-deploy every change to a shareable dev URL — without touching production.
- [Environment variables](https://docs.apco.space/guides/environment-variables): Every project has its own set of environment variables. They are encrypted at rest, injected into your app at build time and runtime, and synced with a local dotenv file via the CLI.
- [Deploy from GitHub Actions (v0)](https://docs.apco.space/guides/github-actions): GitHub Actions v0 is APCO's workflow-based alternative to the recommended GitHub App integration. It can deploy an existing project without giving the workflow access to your other projects, environment-variable API, database tools, lifecycle controls, rollback, or promotion. Existing workflows and ci:deploy credentials remain supported.
- [Deploy with the APCO GitHub App](https://docs.apco.space/guides/github-app): The APCO GitHub App connects one project to one installed repository. It can deploy an exact Production-branch push, keep an isolated Preview for every open pull request, and report each build through a GitHub Check and one sticky APCO comment.
- [Logs](https://docs.apco.space/guides/logs): Two kinds of logs are available for every project: the build log of a deployment, and the runtime logs of the running container. Both come from the same command.
- [Observability alerts](https://docs.apco.space/guides/observability-alerts): APCO Cloud can email (and optionally webhook) the project owner when operational incidents occur. Alerts are disabled by default — enable them per project under Settings → Observability alerts.
- [Deploying OCI images](https://docs.apco.space/guides/oci-images): Use app.type: dockerimage when you already have a runnable Linux OCI image and do not want APCO to receive source or perform a build. APCO validates the registry, pulls the image, resolves a tag to an immutable repository digest, and starts it with the same gVisor, network, resource, health, and Caddy boundaries as a source-built SSR app.
- [Password protection](https://docs.apco.space/guides/password-protection): Put a password in front of any deployed project — handy for staging sites, client previews, or anything that shouldn't be public yet. Visitors get a branded APCO password page — there's no username, just the password.
- [Plans & quotas](https://docs.apco.space/guides/plans-and-quotas): Every account is on a plan — Free by default, Pro for more resources and extra features (managed databases, dev sync). Plans define every limit the platform enforces.
- [Quickstart](https://docs.apco.space/guides/quickstart): Deploy your first app to APCO Cloud in about five minutes. You'll install the CLI, log in, create a manifest, and ship a live app to https://<slug.apco.space.
- [Scaling realtime beyond one instance](https://docs.apco.space/guides/realtime-scaling): By default @apco/realtime is in-process: the SSE hub lives inside your app's process, so a client only receives events published by the same instance it connected to. That's exactly right for a single app instance — zero infrastructure, zero external dependency.
- [Realtime (SSE)](https://docs.apco.space/guides/realtime): The @apco/realtime SDK adds live updates to your app with Server-Sent Events — a server-side broker that runs inside your SSR app (no platform service, no external dependency), plus a browser client with automatic reconnection and an optional React hook.
- [Scheduled jobs](https://docs.apco.space/guides/scheduled-jobs): APCO can run durable, project-scoped commands from the same immutable artifact as an SSR or OCI-image deployment. Definitions live in apco.yml; the dashboard, CLI, HTTP API, and MCP control scheduling and inspect logical runs without exposing commands or environment values.

## Reference

- [@apco/db](https://docs.apco.space/reference/apco-db): Lightweight Postgres client for apps deployed on APCO Cloud: a thin postgres.js wrapper plus Zod row parsing and file-based migrations. Requires Node.js ≥ 22 (ESM only). Pairs with the managed Postgres feature — on APCO, DATABASEURL is injected into your container automatically once the database is ready.
- [@apco/realtime](https://docs.apco.space/reference/apco-realtime): Server-Sent Events (SSE) realtime for APCO apps. There is no platform broker — the realtime hub runs inside your SSR app's process, so it works anywhere the app runs. Requires Node.js ≥ 22 (ESM only); React ≥ 18 is an optional peer dependency (only for the hook). See the realtime guide for a walkthrough.
- [CLI commands](https://docs.apco.space/reference/cli): Complete reference for the apco CLI. The public npm package is apco-cli, and its installed executable is apco. Every command supports --json for machine-readable output: stdout is exactly one JSON envelope, and all human diagnostics and progress go to stderr. AI agents should always parse the --json envelope — see the agent contract.
- [Error codes](https://docs.apco.space/reference/error-codes): Two catalogs: CLI error codes (in the --json envelope's error.code, with a process exit code) and web API error codes (in the HTTP response's error.code, with an HTTP status). The CLI maps HTTP failures onto its own codes — the original server message is preserved in error.message.
- [HTTP API](https://docs.apco.space/reference/http-api): The control plane exposes a JSON API at https://apco.space/api/v1 in the hosted installation. The CLI, MCP server, and dashboard all use these routes — anything they can do, you can do directly over HTTP. Self-hosters can configure a distinct control-plane origin.
- [apco.yml manifest](https://docs.apco.space/reference/manifest): apco.yml is the project manifest (schema version 2). It is validated by apco manifest validate, and a normalized snapshot—including source or OCI provenance—is stored with every deploy. Create one with apco init.
- [Token scopes](https://docs.apco.space/reference/scopes): API keys carry an optional list of scopes that limits what they can do. The model is deliberately simple:

## For AI Agents

- [Agent contract](https://docs.apco.space/ai-agents/agent-contract): The machine contract for agents and automation driving APCO Cloud — via the apco CLI, the MCP server, or raw HTTP. This page is the normative summary; the exhaustive command/payload listing lives in the repository's agents.md and in the reference section.
- [MCP server](https://docs.apco.space/ai-agents/mcp): apco mcp runs an MCP (Model Context Protocol) server on stdio, exposing APCO Cloud as typed tools for Claude Code, Cursor, and any other MCP client. It speaks the MCP protocol on stdout (no JSON envelope); diagnostics go to stderr.
- [APCO for AI agents](https://docs.apco.space/ai-agents/overview): APCO Cloud is built to be driven by agents as much as by humans. Every surface — CLI, MCP, HTTP — is designed around the same principles: machine-parseable output, stable error codes, and no secrets in output.