FIRST DEPLOYMENT

Deploy your first app with an agent.

Start inside any app repository. Small installs a portable skill for your coding agent, keeps production credentials outside the prompt, and deploys to a private URL by default.

About 5 minutes Private by default Harness agnostic

RECOMMENDEDRun inside your app repository

One prompt. Your agent handles setup.

Paste this into Codex, Claude Code, Cursor, or OpenCode from your app repository. It inspects the project, installs the official tools, and drives the deployment to a healthy URL.

Deploy this app with Small. Follow https://smallcloud.sh/start.md.
Keep it private, and add managed Postgres if the app needs data.

You keep control of browser sign-in, secrets, and authority changes.

1
Give the agent one prompt
It reads Small's canonical deployment guide.
2
Approve browser sign-in
No cloud key or workspace admin token enters chat.
3
Receive the private URL
The agent plans, deploys, verifies, and reports back.

QUICKSTART

One prompt to a private URL.

You do not need to choose a cloud, create registry credentials, or give the agent SSH access. Small Cloud is the default when target.server is empty.

An app repositoryWith a Dockerfile, or let your agent create one.

Node.js 22+ and DockerThe image is built on your machine.

A Small accountVerify email; no card for the two-hour preview.

01
PROMPT
Give the deployment to the agent already in your repo.
The canonical guide tells it how to inspect the app, install the checksum-verified CLI and project skill, create small.yaml, and use safe defaults.
```
Deploy this app with Small. Follow https://smallcloud.sh/start.md.
Keep it private, and add managed Postgres if the app needs data.
```
02
HUMAN CHECKPOINT
Approve one scoped browser sign-in.
The agent shows the exact Small activation URL and device code, then waits. Existing users sign in and approve; new users verify their email. Passwords, magic links, and API tokens stay out of the conversation.
03
PLAN
Small evaluates authority before building.
The plan returns allow, approval required, or denywith reasons. A routine private deployment normally stays inside policy and proceeds without a human checkpoint.
decisionALLOWaccessprivate · workspace membersruntimeSmall Cloud · automatic placement
04
LIVE
Open the stable application URL.
Small uploads the immutable image, starts it in an isolated runtime, verifies health and routing, then prints the URL. The previous release stays active until its replacement is healthy.
HEALTHYhttps://hello-small.apps.smallcloud.sh

RUNTIME

Choose where it runs.

Runtime placement is separate from the deployment contract. Start on managed Small Cloud, then move the same manifest to a company-owned VPS when policy or workload requirements change.

DEFAULT

Small Cloud

Leave target empty. Small selects healthy managed capacity, provisions ingress, and returns the application URL.

Fastest first deployment
gVisor-isolated pooled runtime
No VPS or registry setup

OPTIONAL

Your VPS

Enroll a supported host from Cloud & runtimes, then set target.server or pass --server.

Company-owned capacity
Outbound-only managed relay
No public Docker socket or SSH handoff

DEPLOYMENT CONTRACT

Keep deployment intent in small.yaml.

The manifest is the portable boundary between any coding agent and Small. It declares how to build, health-check, expose, size, and place the app—without containing credentials.

small.yamlmanaged local source

version: 2
name: hello-small
source:
  type: local
  dockerfile: Dockerfile
  context: .
service:
  port: 3000
  healthcheck:
    path: /health
resources:
  memoryMb: 256
  cpus: 0.25
storage: []
access:
  mode: private
env: {}
secrets: []
lifecycle:
  expiresAfter: 30d
target: {}

Source

Local source builds an immutable image on your machine. Source code is not uploaded to Small.

Resources

CPU and memory are explicit, so policy and placement can be evaluated before deployment.

Access

Private is the safe default. Access changes travel with the release and activate only after health succeeds.

small.yamladd only when relational data is needed

version: 2
addons:
  postgres:
    version: 17

Small provisions a dedicated private database and injects DATABASE_URL. The credential is never shown in the dashboard, logs, CLI, MCP output, or agent conversation.

AGENT INTEGRATION

Use the skill first. Add MCP when useful.

The repository skill is enough for Codex, Claude Code, and compatible agents to operate the CLI. MCP adds structured tools for manifests, policy plans, deployments, logs, audit, and rollback; it is useful, but not required for activation.

INSTALLED BY START.SH

Project skill

Lives with the repository, tells the agent what Small can do, and keeps the deployment process reproducible across harnesses.

.agents/skills/deploy-with-small

OPTIONAL

MCP server

Exposes typed planning and operations over stdio using the already authenticated CLI credential.

small mcp

ALWAYS AVAILABLE

CLI

The narrow, scriptable contract underneath every harness and the escape hatch for manual operation or CI.

small --help

terminaloptional MCP registration

# Codex
codex mcp add small -- small mcp

# Claude Code
claude mcp add --transport stdio --scope user small -- small mcp

Restart the coding-agent session after installing a skill or MCP server so the harness discovers it cleanly.

APPLICATION ACCESS

Put the audience beside the app.

Private apps allow workspace members by default. Maker can invite an exact verified email as an app guest or allow a verified email domain without adding workspace members.

PrivateRecommended default

access:
  mode: private
  allow:
    workspaceMembers: true
    emailDomains:
      - company.com

PublicPolicy-controlled expansion

access:
  mode: public

APPROVAL POLICY

Review changes in authority—not every release.

Routine releases can continue automatically. Owners and admins decide whether authority-expanding changes are allowed, require approval, or are denied. Hard boundaries cannot be approved around.

Private → public

Expands the reachable audience

Custom domain

Claims or changes a public name

New email domain

Expands private-app membership

More resources

Increases CPU or memory authority

01Agent proposes

Small stores the requested manifest and authority diff.

02Human decides

The active private release remains untouched while waiting.

03Small rechecks

Policy, health, quota, and capacity are evaluated again.

OWNERSHIP AND EVIDENCE

Know who asked, who decided, and what changed.

Every app has an owner. The audit log records human users, service accounts, agents, runtimes, approval decisions, access changes, deployment results, and the target they affected.

Ownership

One accountable owner per app, transferable by an admin.

Readable timeline

Filter by deployment, access, identity, or infrastructure.

Raw evidence

Expand identifiers and metadata, or export CSV and JSON.

Open approvals and access

OPERATIONS

Observe, replace, and recover.

A replacement becomes active only after container health and routing succeed. Rollback resolves the historical immutable image rather than pulling a mutable tag again.

terminalcommon operations

small plan
small deploy
small status
small logs hello-small
small rollback <deployment-id>
small stop hello-small --yes
small archive hello-small --yes

Health before activation Previous release preserved on failure Bounded deployment event timeline

SECRETS

Declare names. Supply values out of band.

Personal agent credentials cannot read or change workspace secrets. An administrator or reviewed administrative service account supplies values from its environment; list operations never return plaintext.

terminaladministrative credential

export DATABASE_URL='postgres://…'
small secrets set --app hello-small --from-env DATABASE_URL DATABASE_URL
unset DATABASE_URL
small secrets list --app hello-small

REQUEST PATH

Understand where traffic and trust live.

The control plane authorizes deployment intent. Application traffic flows through the TLS edge and application gateway—not through the dashboard process—and then to the assigned runtime.

TLS edgeHostname and certificate

App gatewayAccess policy and identity

Managed relayAuthorized route

RuntimeIsolated application container

Small does not receive SSH access or a remote Docker socket. A customer node leases only commands assigned to its runtime identity.

TROUBLESHOOTING

Start with evidence, then repair.

Use the deployment timeline and app logs first. For a customer-owned VPS, the node installer provides bounded health, repair, update, rollback, and uninstall operations.

customer VPSnode health

sudo small-node-installer check
sudo systemctl status small-node --no-pager
sudo journalctl -u small-node -n 200 --no-pager
sudo small-node-installer repair

CREDENTIAL

Re-enroll

Issue a replacement enrollment, then rotate the node safely.

small-node-installer reenroll

RELEASE

Update or rollback

A failed readiness check restores the prior node release.

small-node-installer rollback

BOUNDARY

Current limits

Persistent volumes are single-node data. Managed relay is the supported customer-VPS ingress mode today.

private alpha

READY TO SHIP?

Deploy privately first.

Expand access only when the app earns it.

Open Small Get help

Give the deployment to the agent already in your repo.

Approve one scoped browser sign-in.

Small evaluates authority before building.

Open the stable application URL.

Small Cloud

Your VPS

Project skill

MCP server

CLI

Re-enroll

Update or rollback

Current limits

Deploy privately first.