Cloud

A flow doesn't need your laptop up to run. flows run --cloud submits the exact same spec to hosted infrastructure. The Rust runtime still executes and verifies every step; only where it runs is different.

Run it

flows run --cloud examples/ship-feature.flow.yaml
flows run --cloud --wait --json examples/ship-feature.flow.yaml

Without --wait, exit 0 means the run was accepted. You get a run ID back and the run continues on its own; it hasn't completed yet. With --wait, exit 0 means Cloud reported the run completed with a validated success reason. A failed or cancelled run, or an observation failure, exits 1.

From the SDK

import { runInCloud, waitForCloudFlowRun } from '@relayflows/sdk';

const accepted = await runInCloud(
  { path: './flow.yaml' },
  { token: process.env.FLOWS_CLOUD_TOKEN }
);
console.log(accepted.runId); // accepted, not completed

const finished = await waitForCloudFlowRun(accepted.runId);
console.log(finished.status, finished.completionReason);

FLOWS_CLOUD_TOKEN needs a Cloud API token; the flows CLI never logs in for you. Provision one from the Cloud dashboard, the same place you'd create a deployment token or a Relayfile agent key:

1. Open Settings → Workspace API tokens.
2. Under Purpose, pick Relayflows Cloud token.
3. Name it, set an expiry, and create it.
4. Copy the one-time cld_at_... value — it's shown once — and export it, replacing the placeholder below with what you copied:

export FLOWS_CLOUD_TOKEN="cld_at_paste-your-copied-token-here"

This mints a token scoped to exactly workflow:invoke:read, workflow:invoke:write, workflow:runs:read, and workflow:logs:read — nothing else — which covers both submitting and polling a run on this page. It's a workspace-level credential: anyone with dashboard access to the workspace can create or revoke one, no CLI or special access needed.

Prefer a CLI instead (headless/SSH host, no browser to click through)? agent-relay cloud login (--device for headless) plus agent-relay cloud session --json --reveal-token gets you a token too, though that one carries a broader cli:auth scope rather than the four scopes above — Cloud's workflow-run endpoints accept either.

FLOWS_CLOUD_URL points at a different Cloud deployment if you're not using the default.

What's different about a cloud run

• Only declarative flows. --cloud accepts flow.yaml / spec.json, not an authored .flow.ts file — the SDK refuses those before making an HTTP call rather than uploading code that can't run there.
• Accepted isn't completed. An interruption after submission but before the acceptance receipt reports admission_unknown — the server may already have started a non-idempotent run. Don't resubmit blindly; check the run ID you already have first.
• One-hour execution ceiling. Cloud's current executor has a one-hour deadline per run, independent of any local timeout you'd otherwise configure.
• You get the completion reason, not the step-by-step journal. It's validated against the same closed vocabulary as a local run, but this API doesn't expose per-step detail yet.

Next