[slinkydeveloper]

Summary

restate.connect({ services, name }) is the counterpart of serve() for Restate Cloud: the services are served over an outbound connection to the environment, with no inbound listener, no tunnel container and no extra package. serve() is unchanged; there is no mode detection and nothing in the environment flips one into the other.

import * as restate from "@restatedev/restate-sdk";

restate.connect({ services: [greeter], name: "greeter-v1" });

Configuration is two environment variables (or the matching options):

• RESTATE_CONNECT_KEY — one URL-shaped string from the Cloud UI (Development → Configure SDK): restate://<api key>@<environment id>.env.<region domain>/?signing-key=…, carrying the credential, the environment, the region and the request-identity key. Optional tunnel-srv / tunnel-servers parameters override discovery; unknown parameters are ignored with one warning.
• RESTATE_CONNECT_NAME — the deployment identity (connect({ name }) in code). No inference: an unnamed deployment is an error that says what to set.

On the first successful handshake the SDK logs how to register, once:

Connecting to Restate Cloud environment env_… (<region domain>)
Connected as "greeter-v1"
Register it once:
  restate deployments register connect://greeter-v1
  or open https://cloud.restate.dev/to/overview?register-deployment=connect://greeter-v1

Errors link the Cloud UI page they refer to (/to/developers/integration#configure-sdk and #configure-client). A non-retryable stop is explained through the SDK logger at error level, in plain words with the fix, e.g. for a rejected key:

Restate Cloud rejected the connect key for environment env_…: it is invalid, revoked, or for another environment.
Create a new key at https://cloud.restate.dev/to/developers/integration#configure-sdk and set RESTATE_CONNECT_KEY.
Not retrying. Fix the configuration and restart.

API

• ConnectOptions = EndpointOptions & { name?, key?, connection?: ConnectionOptions }. ConnectionOptions holds server discovery (servers, serversSrv), workerId and the tuning (reconnect, drain, HTTP/2 limits, tls: ConnectTlsOptions).
• ReconnectRetryPolicy has the shape of the invocation and client retry policies (initialInterval, maxInterval, exponentiationFactor, maxAttempts, maxDuration); the bounds default to false since a deployment should keep reconnecting, and reaching one is a fatal stop like any other.
• Connection: ready, name, close(), shutdown(). close()/shutdown() reject with the fatal error if the connection had already stopped on a non-retryable failure. Registration is by name; the deployment URL stays internal (logged at debug, always on port 9080).
• @restatedev/restate-sdk-clients: connect() without a url reads RESTATE_INGRESS_KEY (same grammar, from Development → Configure Client) and uses https://<host>:8080 with the key as bearer. Nothing set still fails fast, since a URL was always required.
• parseCloudKey in restate-sdk-core is the shared key parser.

Compatibility

• @restatedev/restate-sdk-tunnel is untouched: identical to main, its own copy of the engine, its own tests. restate.connect() has its own copy of the engine inside restate-sdk; nothing is shared or adapted between the two, so existing connectTunnel() users see no change at all.
• The older variable spellings keep resolving behind the two new ones, undocumented: RESTATE_INPROC_* (restate-operator), RESTATE_TUNNEL_NAME, and the expanded RESTATE_* set (environment id, token or token file, region or SRV / servers, signing key). An operator-configured pod (RESTATE_INPROC_* plus a token file) works with connect({ services }) unchanged; there is an end-to-end test for it.

Build fix

packages/tests/restate-e2e-services built with tsc -b and referenced the SDK's composite project, so it emitted raw declaration files into restate-sdk/dist, overwriting tsdown's flattened node.d.ts whenever an entry source had changed and breaking api-extractor on the node entry. It now builds with tsc --project and without the references (turbo already builds the dependencies first, and the package resolves them through node_modules).

Verification

Full pipeline green (76/76 tasks): format, lint, types, build, exports, API report, tests. The fake-cloud engine tests run through connect() with a key (and, for their legacy spelling, through a small test-only shim); new tests cover key parsing, name/key resolution order, error messages, the banner, the operator setup, and the clients defaults.

Release note

Connect to Restate Cloud with connect(). restate.connect({ services, name: "greeter-v1" }) serves your services over an outbound connection to a Restate Cloud environment — no inbound listener, no tunnel container, no extra package. It is configured by RESTATE_CONNECT_KEY, one string from the Cloud UI (Development → Configure SDK), and RESTATE_CONNECT_NAME (or the name option), the deployment identity you register with restate deployments register connect://<name> or from the Cloud UI link the SDK prints on startup. serve() is unchanged. @restatedev/restate-sdk-tunnel is unchanged. @restatedev/restate-sdk-clients: connect() without a url reads RESTATE_INGRESS_KEY (Development → Configure Client).

🤖 Generated with Claude Code

[github-actions]

Test Results

  8 files  ± 0    8 suites  ±0   5m 41s ⏱️ + 2m 20s
 72 tests +12   72 ✅ +12  0 💤 ±0  0 ❌ ±0 
323 runs  +56  323 ✅ +56  0 💤 ±0  0 ❌ ±0 

Results for commit 2b766d1. ± Comparison against base commit 27a6c96.

♻️ This comment has been updated with latest results.