Skip to main content
Version: 2.0 prerelease

Cloud Managed Runtime

Durable Workflow Cloud is a managed orchestration service. Cloud operates both the hosted control plane and the orchestration runtime, including workflow state, history, schedules, task queues, leases, and durable visibility. Customers run SDK clients and workers against a provisioned Cloud namespace.

This is separate from self-hosting. A self-hosted Durable Workflow Server runs independently and is never attached to Cloud. The guidance on this page belongs to the explicit 2.0 prerelease docs line.

Managed Service Boundary​

The customer-visible boundary is one Cloud namespace:

Cloud organization
  project
    environment
      namespace
        stable runtime URL
        client runtime credential  ---> workflow starts and commands
        worker runtime credential  ---> registration, polling, and completion

Cloud-operated runtime
  workflow state and history
  schedules and task queues
  leases, matching, and visibility
  Managed Waterline

Cloud owns namespace provisioning, runtime operation, persistence, placement, runtime health, recovery, and the Managed Waterline surface for the namespace. Customers own application code, workflow and activity implementations, and the processes that run their workers. Cloud customers do not deploy a separate Waterline service.

Cloud administration and runtime traffic use different credentials:

  • A Cloud API key (dwc_...) manages projects, environments, namespaces, billing, and runtime-credential lifecycle.
  • A client runtime credential (dwr_...) starts and controls workflows in one managed namespace.
  • A worker runtime credential (dwr_...) registers workers, long-polls for tasks, sends heartbeats, and settles work in that namespace.

A Cloud API key is not accepted by the namespace runtime URL. Runtime credentials are scoped to one namespace and role, returned only when created, and omitted from later list and audit responses.

If Cloud onboarding uses the CLI, install it from the CLI guide and update an existing standalone installation explicitly with dw upgrade. The CLI never updates in the background. After installing or upgrading, run command -v dw and dw --version; resolve any installer PATH remediation before using Cloud credentials so the selected release is the active binary.

Provision And Connect A Namespace​

1. Create and provision the namespace​

Create the namespace without supplying a Server URL, deployment identifier, or placement record:

curl -X POST \
  https://cloud.durable-workflow.com/api/v1/projects/PROJECT/environments/ENVIRONMENT/namespaces \
  -H "Authorization: Bearer dwc_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"orders","retention_days":30}'

curl -X POST \
  https://cloud.durable-workflow.com/api/v1/projects/PROJECT/environments/ENVIRONMENT/namespaces/orders/provision \
  -H "Authorization: Bearer dwc_..."

After provisioning completes, the namespace response provides its stable runtime_url, its runtime_namespace, managed status, and customer-visible region information. Treat the returned URL and namespace value as configuration owned by Cloud; do not derive an endpoint or replace it with a self-hosted Server address.

2. Issue separate client and worker credentials​

Issue the two runtime roles independently:

curl -X POST \
  https://cloud.durable-workflow.com/api/v1/projects/PROJECT/environments/ENVIRONMENT/namespaces/orders/runtime-credentials \
  -H "Authorization: Bearer dwc_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"orders-client","role":"client"}'

curl -X POST \
  https://cloud.durable-workflow.com/api/v1/projects/PROJECT/environments/ENVIRONMENT/namespaces/orders/runtime-credentials \
  -H "Authorization: Bearer dwc_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"orders-worker","role":"worker"}'

Each token is displayed once in its create response. Store it in the secret store used by only the corresponding role. A deliberately combined client and worker process receives both values as two distinct secrets. Rotate and revoke the roles independently, and never substitute a Cloud API key for either runtime credential.

3. Complete a first Cloud workflow​

Use the Cloud-provided runtime URL as the SDK's Server base URL and the Cloud-provided runtime namespace as its namespace. Application clients use the client credential; worker processes use the worker credential.

Choose one complete client-and-worker program:

For Cloud, replace the local example URL and namespace with the values issued for the namespace, then configure both role credentials through distinct authentication inputs. A combined client-and-worker process may hold both credentials, but it must not put one credential into both role inputs.

For the Rust same-process example, the replacements map directly to ClientBuilder:

  • pass Cloud's runtime_url to Client::builder(runtime_url);
  • pass Cloud's runtime_namespace to .namespace(runtime_namespace);
  • pass the client credential's token to .control_token(Some(client_token)); and
  • pass the worker credential's token to .worker_token(Some(worker_token)).

Rust's .token(...) method is a generic single-token fallback for self-hosted Server configurations. Do not use it in place of either role-specific Cloud method.

Run the selected program. Success is a worker registration followed by a workflow whose result call returns and whose durable status is completed. That is the same first-success outcome as the local Server quickstart, reached without installing or running Server.

4. Continue with managed operation​

The SDK client starts workflows and sends follow-up commands through the namespace runtime URL. Customer-run workers register and long-poll through the same URL using the worker role. Cloud authenticates and scopes each request, executes the orchestration protocol in the managed runtime, and persists the workflow state and history.

The customer application does not select a runtime deployment for an operation. Workflow IDs, run IDs, task queues, compatibility markers, and payload codecs remain durable application contracts within the Cloud namespace.

Customer-Run Worker Connectivity​

Workers can run in your network, VM fleet, container platform, or application environment. They need outbound HTTPS reachability to the namespace runtime URL and must allow the worker protocol's long-lived poll requests.

  • No inbound connection from Cloud to a worker is required.
  • Proxies and egress gateways must not shorten long polls into a busy retry loop.
  • Workers should retry transient connection failures and service-unavailable responses with bounded backoff.
  • Moving a worker process does not move workflow state; Cloud retains the namespace's durable state and history.
  • Credential rotation does not require changing the runtime URL, namespace, or task queue.

Region Placement And Recovery Boundary​

The current 2.0 launch cohort provisions each namespace in one managed region. The namespace response exposes that region and its service status for residency, latency, and incident decisions; infrastructure deployment identities, private addresses, upstream credentials, and provider topology remain internal.

Multi-region replication, automatic regional failover or failback, and customer-facing RTO or replication-lag targets are not part of the current Cloud contract. Applications should retry transient connection failures using their normal bounded policy, but must not treat a stable namespace URL as a guarantee of automatic cross-region recovery.

Private Connectivity And Support Boundary​

The 2.0 self-serve Cloud contract assumes outbound access from clients and workers to the public namespace runtime URL. Private-only ingress, bespoke VPN or peering arrangements, and provider-specific private routing are support-led connectivity designs, not hidden defaults. Customers are never given internal runtime addresses or asked to route around the namespace URL.

Cloud Or Self-Hosted Server​

Choose Cloud when Durable Workflow should operate the orchestration runtime, persistence, single-region placement, recovery, and Managed Waterline while your team operates the SDK clients and workers.

Choose self-hosted Server when your team needs to operate the Server image, database, cache, networking, authentication, backups, and failover independently. A self-hosted Server cannot be registered with, attached to, or used as the backing runtime for a Cloud namespace. Embedded Laravel, self-hosted Server, and Cloud are separate deployment choices.

Billing Usage API​

Cloud exposes organization-scoped billing usage for finance, operations, and chargeback automation. The endpoint is authenticated by a Cloud API key and does not accept a customer or organization id in the request; the caller's organization is resolved from the dwc_ bearer token so one customer cannot query another customer's usage.

GET /api/v1/billing/usage?period_start=2026-05-01&period_end=2026-05-31
Authorization: Bearer dwc_...
Accept: application/json

period_start and period_end are optional ISO-8601 dates. When omitted, Cloud returns the current calendar month. Billing usage reads and exports stay available even if billing restrictions pause namespace provisioning or workflow operations, so finance teams can still recover account standing.

The response schema is durable_workflow.cloud.billing_usage.v1. The abbreviated zero-valued response below illustrates the API shape only; it does not represent a plan rate or pricing quote. estimated_cost_cents comes from the caller's plan-backed usage rollup. Every usage and cost value is zero, so the example does not imply an action-count-to-cost rate.

{
  "schema": "durable_workflow.cloud.billing_usage.v1",
  "access_control": {
    "scope": "organization_billing_usage",
    "api": {"authentication": "organization_api_key"}
  },
  "current_period": {
    "starts_at": "2026-05-01T00:00:00+00:00",
    "ends_at": "2026-05-31T23:59:59+00:00"
  },
  "totals": {
    "workflow_execution_count": 0,
    "activity_execution_count": 0,
    "timer_fire_count": 0,
    "signal_delivery_count": 0,
    "update_delivery_count": 0,
    "query_task_count": 0,
    "storage_byte_hours": 0,
    "billable_action_count": 0,
    "estimated_cost_cents": 0
  },
  "by_action_type": [
    {
      "action_type": "workflow_start",
      "raw_count": 0,
      "billing_unit": "billable_action",
      "billing_units": 0,
      "estimated_cost_cents": 0
    }
  ],
  "by_namespace": [
    {
      "namespace": "example",
      "project": "example",
      "environment": "test",
      "usage": {
        "billable_action_count": 0,
        "estimated_cost_cents": 0
      },
      "action_types": [
        {
          "action_type": "workflow_start",
          "raw_count": 0,
          "billing_units": 0,
          "estimated_cost_cents": 0
        }
      ]
    }
  ]
}

The standard action types are workflow_start, activity_execution, timer_fire, signal, update, and query. raw_count is the source meter count. billing_units is the derived billable_action quantity used for chargeback. The plan-backed estimated_cost_cents rollup is allocated proportionally across action types so totals reconcile with the namespace and report totals.

Export the same evidence as CSV or a JSON report when a downstream finance system needs a file handoff:

curl -OJ "https://cloud.durable-workflow.com/api/v1/billing/usage/export?period_start=2026-05-01&period_end=2026-05-31" \
  -H "Authorization: Bearer dwc_..."

curl -OJ "https://cloud.durable-workflow.com/api/v1/billing/usage/report?period_start=2026-05-01&period_end=2026-05-31" \
  -H "Authorization: Bearer dwc_..."

For a JSON-backed dashboard panel, request the same API with the panel's time range:

GET https://cloud.durable-workflow.com/api/v1/billing/usage?period_start=${__from:date:YYYY-MM-DD}&period_end=${__to:date:YYYY-MM-DD}
Authorization: Bearer dwc_...

Then flatten namespace/action rows with:

.by_namespace[]
| . as $namespace
| .action_types[]
| {
    project: $namespace.project,
    environment: $namespace.environment,
    namespace: $namespace.namespace,
    action_type,
    raw_count,
    billing_units,
    estimated_cost_cents
  }

Group the dashboard by namespace and action_type, sum billing_units, and plot estimated_cost_cents / 100 as the cost series.