# Cloud

Run a flow on hosted infrastructure instead of your own machine — the same verification, the same journal.

Rendered page: https://agentrelay.com/docs/relayflows/cloud
Markdown endpoint: https://agentrelay.com/docs/relayflows/markdown/cloud.md

---

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

```bash
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

```ts
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](https://cloud.agentrelay.com/dashboard/settings), 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:

```bash
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

- [Multi-agent flows](https://agentrelay.com/docs/relayflows/multi-agent): Named agents, different CLIs, one spec.
  - [Reliability](https://agentrelay.com/docs/relayflows/reliability): What a completion reason actually guarantees.