Deploy your first app

This walkthrough runs entirely from your own machine against a server you already installed. Nothing executes locally.

1. Bootstrap an organization

org create saves the returned human session in the default profile. The one-time API token it prints is for automation — store it somewhere a script can read, or discard it and keep using the profile.

pnpm tiny org create \
  --api https://control.example.com \
  --slug acme \
  --owner you@example.com

Organization bootstrap is one of the few unauthenticated routes. It returns the organization, the runtime target, a once-visible apiToken, and a human sessionToken.

Confirm the profile and see what the target supports:

pnpm tiny whoami

2. Look at the manifest

examples/hello-private is the smallest app that proves identity, routing, and lifecycle work. It needs nothing beyond a minimally configured target.

examples/hello-private/tiny.yaml

apiVersion: tinycloud.dev/v1alpha1
kind: App

metadata:
  name: hello-private
  displayName: Hello Private
  description: The smallest app that proves identity, routing, and lifecycle work.
  owner: you@example.com

runtime:
  type: worker
  language: typescript
  entrypoint: src/index.ts

access:
  visibility: private
  requireLogin: true

lifecycle:
  sleepAfter: 60m
  archiveAfterUnused: 30d

examples/hello-private/src/index.ts

import { tiny } from '@tinycloud/runtime-sdk';

export default tiny.app(async (request, context) => {
  const url = new URL(request.url);
  context.log('info', 'handling request', { path: url.pathname });

  return Response.json({
    message: `Hello ${context.user?.email ?? 'anonymous'}`,
    app: context.appSlug,
    environment: context.environment,
    requestId: context.requestId,
  });
});

A worker entrypoint must default-export tiny.app(handler). The handler receives standard Web Request and Response objects plus a verified Tinycloud context.

Starting from scratch instead? pnpm tiny init my-app writes this shape.

3. Validate, check, plan, deploy

Each step is separately useful, and the first three are all non-mutating.

validate — parse and check tiny.yaml locally

pnpm tiny validate --cwd examples/hello-private

Parses the strict YAML subset, validates against the JSON Schema, normalizes defaults, and applies semantic rules. No network call.

doctor — check credentials, files, and reachability

pnpm tiny doctor --cwd examples/hello-private

Verifies your profile, the manifest, the entrypoint, migrations, and that the target is reachable and compatible.

plan — upload an artifact and compute the diff

pnpm tiny plan --cwd examples/hello-private

Uploads an immutable content-addressed artifact, then returns a resource diff, migration plan, capability status, required approvals, and a cost estimate. Planning never mutates provider or application state.

deploy — enqueue the rollout and watch it finish

pnpm tiny deploy --cwd examples/hello-private

The API answers 202 and a worker rolls out afterwards. The command waits for a terminal state and exits non-zero if the deployment failed, repeating the deployer’s own reason and remediation.

4. Open it

pnpm tiny status
pnpm tiny open hello-private

visibility: private means only subjects named in access.subjects plus organization admins can reach it — and your owner email was added as an app admin during normalization. Everyone else gets a login redirect and then a denial. Grant someone else access without redeploying:

pnpm tiny access grant teammate@example.com --role user --app hello-private
pnpm tiny access list --app hello-private

5. Watch it work

pnpm tiny logs hello-private --since 15m

Logs come from context.log, plus context.audit events and the runtime host’s own structured output.

When something goes wrong

The deploy failed

tiny deploy exits non-zero and repeats the deployer’s reason and remediation. GET /v1/deployments/:deploymentId carries the same detail. Traffic never moved — the previous deployment is still serving.

APPROVAL_REQUIRED

The change widened blast radius in production. Pass --yes to send approval intent with the request, or approve the pending deployment afterwards. --yes does not bypass role or policy checks. See Approvals.

The plan refused before uploading anything

The manifest asked for something this target does not have — Postgres without a configured cluster, build.command without a build image, or egress without the operator setting. That is the platform reporting honestly rather than failing halfway through a deploy.

You want the previous version back

pnpm tiny rollback <deployment-id>

Traffic repoints to the exact bytes that deployment served, and the URL never changes. See Lifecycle.

Add a database

SQLite needs no infrastructure, and the app never holds a credential.

Choose who can open it

Private, organization-wide, or genuinely public.

Call a vendor API safely

Named broker operations instead of secrets inside the app.

Browse the examples

Seven manifests, from trivial to a full build-and-Postgres app.

Get started

Build apps

Operate

Deploy your first app

1. Bootstrap an organization

2. Look at the manifest

3. Validate, check, plan, deploy

4. Open it

5. Watch it work

When something goes wrong

Next

Add a database

Choose who can open it

Call a vendor API safely

Browse the examples

​1. Bootstrap an organization

​2. Look at the manifest

​3. Validate, check, plan, deploy

​4. Open it

​5. Watch it work

​When something goes wrong

​Next

Add a database

Choose who can open it

Call a vendor API safely

Browse the examples

1. Bootstrap an organization

2. Look at the manifest

3. Validate, check, plan, deploy

4. Open it

5. Watch it work

When something goes wrong

Next