OpenCloud

Appearance

Quickstart ​

This path produces a real deployable app and exercises the exact JavaScript SDK served by its OpenCloud origin.

1. Install the CLI ​

The installer downloads and checksum-verifies the pinned public CLI release:

bash
curl -fsSL https://docs.opencloud.ai/install.sh | bash
opencloud --cli-version

If it prints a PATH instruction, apply that once before the version check. See the CLI reference for installation details.

Do not start live work until this command works.

2. Sign in to the OpenCloud account ​

bash
opencloud auth status
opencloud login

opencloud login prints and opens a short-lived HTTPS approval page. The user signs in with a one-time email link or configured password, reviews the request, and explicitly approves the CLI. The command polls until approval; it does not run a localhost callback or ask anyone to paste a code, link, cookie, or token. Use opencloud login --no-browser to print the URL without opening it.

The CLI stores its 15-minute account access token and rotating 30-day refresh token in the OS keyring under ai.opencloud.cli. On a headless host without a usable keyring it uses a mode-0600 per-user credential file. The login is reused by later terminal sessions for the same OS user.

3. Select and connect the app ​

bash
opencloud app list
opencloud app get "$APP_ID"

# Only when the requested app does not already exist:
opencloud app create --name "$PROJECT_NAME" --visibility private
opencloud operation get "$OPERATION_ID" --follow

# Run from the app's source directory:
opencloud app connect "$APP_ID"
opencloud auth status

The account token can list, read, and create apps and connect a workspace, but cannot build or deploy. app connect writes a non-secret, ignored .opencloud/app.json binding and stores a separate 24-hour app-scoped credential in the protected per-user credential backend. The CLI renews the workspace credential from the account login when necessary.

Preserve the returned appUrl; it is the canonical public origin.

4. Create the bundle ​

bash
opencloud init .

CLI 3.10.3 creates a versionless schema-3 manifest by default. Pass --version only when intentionally creating a legacy schema-2 source tree, and keep an existing schema-2 value stable across updates. OpenCloud assigns the actual release name during promotion and stores it on the deployment record.

Add a non-empty frontend/index.html immediately, then validate:

bash
opencloud artifact-check . \
  --expect-app-id "$APP_ID" \
  --max-files 4

opencloud validate .

5. Import the stable SDK ​

Every deployment records an exact SDK version in opencloud.yaml:

yaml
runtime:
  sdk:
    version: 2.2.0

Every app exposes that exact artifact through the same stable import:

js
import { opencloud } from "/_opencloud/sdk.js";

const app = await opencloud.app.info();
const user = await opencloud.auth.currentUser();

Do not fetch runtime config, construct a client, or guess an immutable module URL. OpenCloud maps /_opencloud/sdk.js and /_opencloud/sdk.d.ts to the deployment's pin, so publishing a newer SDK cannot move an existing app.

6. Make a first data request ​

Create an RLS-protected table in an ordered migration, then:

js
const items = await opencloud.data.table("items").list({
  select: ["id", "title", "created_at"],
  orderBy: { column: "created_at", direction: "desc" },
});

The SDK owns auth, same-origin routing, response parsing, and typed errors.

7. Develop, promote, and verify ​

bash
opencloud app dev start "$APP_DIR"
# make and sync further changes as needed
opencloud app dev sync "$APP_DIR"
opencloud app dev verify "$APP_DIR"

opencloud app dev promote "$APP_DIR" \
  --idempotency-key "$UNIQUE_KEY"

The development capability URL uses an isolated schema and cannot access production data or secrets. Functions remain dormant until the CLI or a deliberate preview action invokes them. Promotion deploys only the exact revision covered by the verification receipt, follows the durable operation, runs production verification, prints the live URL, and stops dev. Read the development guide.

The dev-session API also returns browserPreviewUrl for an owner or builder who wants to inspect the current revision before promotion. That browser entry opens a clearly marked Development preview — Not live window with Full size, Tablet, Mobile, and Reload tools. It uses isolated synthetic state and does not require a deployment.

Do not call a deployment successful until app dev promote reports the live production URL. Verification runs durably on OpenCloud and covers the active release, exact runtime metadata, deployment-pinned SDK, HTTPS health, Chromium, and the immutable external E2E specification.

Next ​

Self-hosted infrastructure for agent-built applications.

OpenCloud