Studio Cloud Onboarding

Studio Cloud takes the same verified app you run locally and publishes it to a hosted runtime cell. The management plane handles WorkOS identity, projects, deployments, Cell Control receipts, and scoped runtime tokens. The runtime cell keeps the observation history, active evaluator, facts, intents, effects, provenance, and exports.

Use this flow when you want a secured public endpoint for a JacqOS agent while preserving the local proof model: every accepted result still traces back to observations under a named evaluator and package digest.

Public Endpoints

Surface	URL
Docs and installer	https://www.jacqos.io
Shell installer	https://www.jacqos.io/install.sh
Windows installer	https://www.jacqos.io/install.ps1
Cloud management API	https://cloud.jacqos.io
Management health	https://cloud.jacqos.io/api/v0/health
Runtime API	https://runtime.cloud.jacqos.io
Runtime health	https://runtime.cloud.jacqos.io/healthz
App observe endpoint	https://runtime.cloud.jacqos.io/v0/apps/<app-id>/envs/<environment-id>/observe

You do not need Rust, Cargo, Node.js, WorkOS API keys, database passwords, Railway tokens, Hetzner tokens, or operator ingress tokens.

1. Install Studio

On macOS or Linux:

curl -fsSL https://www.jacqos.io/install.sh | sh

On Windows PowerShell:

iwr https://www.jacqos.io/install.ps1 -UseBasicParsing | iex

Then launch Studio:

jacqos studio

On first run, Studio opens the workspace picker. Open one of the bundled demos to confirm the install, then create your own app.

2. Build And Verify Your First App

Scaffold an appointment-booking app and run the local proof loop:

jacqos scaffold appointment-booking
cd appointment-booking
jacqos replay fixtures/happy-path.jsonl
jacqos verify

jacqos verify must pass before Cloud publish. A failed fixture, invariant, or redaction check blocks deployment locally; Cloud never receives an unverified package.

3. Sign In To Cloud

The Studio path is:

1. Open the app directory with jacqos studio.
2. Use the Cloud panel.
3. Click Sign in and complete the WorkOS device approval in the browser.

The CLI path is:

jacqos cloud login \
  --management-url https://cloud.jacqos.io \
  --runtime-cell-url https://runtime.cloud.jacqos.io \
  --wait

If your account was issued an invite code, keep it in a JACQOS_ variable and pass it explicitly:

export JACQOS_CLOUD_INVITE_CODE="<invite-code>"

jacqos cloud login \
  --management-url https://cloud.jacqos.io \
  --runtime-cell-url https://runtime.cloud.jacqos.io \
  --invite-code "$JACQOS_CLOUD_INVITE_CODE" \
  --wait

The CLI stores session metadata under .jacqos/cloud/. It stores digests and scope metadata, not WorkOS provider secrets or runtime token plaintext.

Check account readiness:

jacqos cloud readiness --json

4. Select A Cloud Scope

Select or create the project, app, and environment you want to publish into:

jacqos cloud select \
  --project appointment-booking \
  --project-name "Appointment Booking" \
  --app appointment-booking \
  --app-name "Appointment Booking" \
  --environment prod \
  --environment-name "Production" \
  --json

The selected scope is organization-bound. If your WorkOS session belongs to a different organization, management writes fail before any runtime command is dispatched.

5. Publish And Promote

Studio path:

1. Confirm the Cloud panel shows the intended organization, project, app, and environment.
2. Click Publish.
3. Wait for the Verify, Deploy, Token, and Inspect steps to complete.

CLI path:

jacqos verify
jacqos cloud deploy --json
jacqos cloud promote --json
jacqos cloud status --json

cloud deploy creates the verified package handoff. cloud promote makes that package the live evaluator for the selected app and environment. Shadow or failed packages cannot execute effects.

6. Issue A Scoped Runtime Token

Issue a token that can send observations and fetch hosted evidence:

jacqos cloud token issue \
  --scope observe \
  --scope export \
  --expires-in-seconds 2592000 \
  --json > runtime-token.json

export JACQOS_RUNTIME_TOKEN="$(jq -r .token runtime-token.json)"
export JACQOS_CLOUD_ENDPOINT="https://runtime.cloud.jacqos.io/v0/apps/appointment-booking/envs/prod"

The token value is returned once. Store it in your own secret store for your application. JacqOS persists token digests, scopes, expiry, and Cell Control receipts, not plaintext token material.

Smoke-test the endpoint:

jacqos cloud endpoint-smoke \
  --token-env JACQOS_RUNTIME_TOKEN \
  --json

7. Send An Observation

Use the CLI:

jacqos cloud observe \
  --lineage lineage_first_user \
  --class appointment.requested \
  --payload-json '{"customer_id":"cust_123","requested_time":"2026-05-01T10:00:00Z"}' \
  --token-env JACQOS_RUNTIME_TOKEN \
  --json

Or call the public endpoint directly from your product:

curl --fail \
  -H "Authorization: Bearer $JACQOS_RUNTIME_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "lineage_id": "lineage_first_user",
    "class": "appointment.requested",
    "payload": {
      "customer_id": "cust_123",
      "requested_time": "2026-05-01T10:00:00Z"
    }
  }' \
  "$JACQOS_CLOUD_ENDPOINT/observe"

Runtime tokens are checked against the app id, environment id, operation scope, expiry, and revocation state. Missing, invalid, revoked, or wrong-scope tokens are rejected before observations are appended.

8. Inspect Hosted Provenance In Studio

Open Studio from the app directory:

jacqos studio

Use the Cloud panel to open the hosted endpoint, then inspect the Provenance surface. Studio reads the runtime export surfaces and builds the same views you use locally:

• facts and intents from the hosted evaluator,
• effect receipts from the runtime cell,
• provenance edges back to the observations that produced them,
• package and evaluator digests for replay identity.

There is no separate debug database to trust. If Studio shows it, it came from hosted observations, evaluator digests, package digests, and runtime receipts.

9. Export And Replay Hosted Evidence

Fetch hosted evidence and validate the local round trip:

jacqos cloud replay-export \
  --lineage lineage_first_user \
  --token-env JACQOS_RUNTIME_TOKEN \
  --output hosted-export.json \
  --json

The export includes evaluator identity, package identity, mapper-output digests, redacted observations, hosted facts, intents, effects, and provenance. Replay must recompute the same semantic identities. If package, evaluator, or mapper-output digests drift, treat the export as failed evidence rather than a successful proof.

Failure States

Every first-user failure has a stable id, a user-facing next action, and a retryability hint.

Error	What It Means	Fix
cloud_invite_required	The cloud is invite-gated.	Sign in with the invite code issued to your organization.
cloud_invite_invalid	The invite code was not accepted.	Check the exact code or ask support for a replacement.
cloud_signups_disabled	New self-service signups are paused.	Wait for support to reopen signups or use an approved organization.
cloud_device_auth_denied	The browser denied the WorkOS device authorization.	Run jacqos cloud login --wait again and approve the device authorization.
cloud_device_auth_expired	The WorkOS device authorization expired before approval.	Run jacqos cloud login --wait again to get a fresh code.
unauthenticated_management_request	The management API did not receive an authenticated session.	Run jacqos cloud login --wait again.
missing_management_route_scope	The session is authenticated but lacks the required cloud role.	Ask an organization admin or support for the needed role.
wrong_org_or_project_scope	The session organization does not match the requested scope.	Switch WorkOS organization or select the matching project.
duplicate_app_name	An app with that name already exists in the project.	Choose a distinct app name or select the existing app.
billing_handoff_not_configured	Billing handoff is not configured for the account.	Continue with runtime setup or ask support to enable billing handoff.
inline_package_too_large	The deployment package exceeds the first-user handoff limit.	Remove unused assets or use a package blob handoff.
unverified_package_publish	Local verification failed before publish.	Run jacqos verify, fix fixtures or invariants, then deploy again.
missing_package_blob	The deployment did not include a package blob handoff.	Re-run jacqos cloud deploy.
package_digest_mismatch	The package digest does not match the verified evidence.	Regenerate the verification bundle and publish the matching package.
too_many_effect_capabilities	The deployment declares more effect capabilities than the plan allows.	Remove unused capabilities or split the app.
deployment_quota_exceeded	The organization hit the deployment quota for the current period.	Wait for reset or ask support for a plan change.
runtime_token_issue_quota_exceeded	The organization issued too many runtime tokens in the current period.	Reuse or rotate existing tokens, or ask support for a plan change.
runtime_token_ttl_exceeds_limit	The requested token expiry is too long.	Request a shorter expiry.
runtime_token_scope_limit_exceeded	The token request includes too many scopes.	Issue separate tokens for separate clients or operations.
management_writes_disabled	Support paused new management writes.	Existing runtime activations keep serving; retry after the support window.
management_plane_unavailable	The management API is unavailable.	Retry after the status page clears; already promoted runtime endpoints keep serving.
runtime_cell_unavailable	The runtime cell is unavailable.	Retry when https://runtime.cloud.jacqos.io/healthz is ready.
no_active_evaluator	The runtime has no promoted evaluator for that app and environment.	Publish and promote a verified deployment.
missing_runtime_token	The runtime request had no bearer token.	Include Authorization: Bearer $JACQOS_RUNTIME_TOKEN.
invalid_runtime_token	The token shape or signature is invalid.	Issue a new scoped runtime token.
revoked_runtime_token	The token was revoked.	Rotate to a new token and update the client.
wrong_runtime_scope	The token does not cover the endpoint or operation.	Issue a token for the correct app, environment, and scope.
runtime_observation_quota_exceeded	The observation body is larger than the runtime limit.	Reduce the body or move large raw content into blob storage.
runtime_export_quota_exceeded	The export would exceed the runtime limit.	Export a narrower lineage slice or ask support for a plan change.
empty_lineage_not_found	No hosted observations exist for that lineage.	Send an observation to the scoped runtime endpoint first.
export_digest_drift	Local replay did not match hosted evidence.	Treat the export as failed evidence and inspect identity drift.
idempotency_conflict	A retry reused an idempotency key with a different body.	Reuse the original body or choose a new idempotency key.

Security Model

• WorkOS authenticates users and organization membership.
• Management mutations require bearer authorization. Cookie-only mutation requests are rejected before provider calls.
• The management API stores projects, deployments, token metadata, support-safe audit records, account readiness, billing summaries, and Cell Control receipts.
• Runtime tokens are returned once, stored as digests, scoped by app and environment, and revocable.
• Runtime cells keep observations, facts, intents, effects, provenance, and exports cell-local.
• Support surfaces redact payloads, observations, atoms, facts, intents, effects, bearer values, runtime tokens, sealed device codes, passwords, private keys, and secret-like fields.
• Billing and offboarding records are support-visible metadata only. Runtime token revocation and activation rollback remain explicit actions.
• Provider API keys, database passwords, Railway tokens, Hetzner tokens, and operator ingress tokens are never part of the first-user flow.