Workers and SDK

In Orchesty, a worker is any service or microservice with the SDK installed. It's the container for your components — Applications, Connectors, Custom Nodes, and Batch nodes — and exposes them to the platform.

From the platform's point of view a worker is just an addressable HTTP service that responds to manifest and process requests.

Connecting a worker to the platform #

For connecting, you register a worker in the Admin UI, the platform generates the env vars, and you paste them into the worker. There are two registration types:

  • HTTP — the platform calls the worker on a hostname you provide. Used for production deployments and any setup where the worker has a routable address.
  • Tunnel — the worker dials the platform and keeps an outbound connection open; the platform routes work through that connection. No public hostname or open port needed; ideal for local development.

After the worker starts and the connection is established, the platform queries the worker for its manifest — the list of registered Applications, Connectors, Custom Nodes, and Batch nodes — and they appear in the topology editor.

See Getting Started — Connect to an instance for the step-by-step UI flow.

Multiple workers, multiple replicas #

A topology can use nodes from many different workers. The Admin UI's editor shows you which worker provides each node. You can also run multiple replicas of the same worker for throughput; the platform load-balances messages across replicas.

This is the unit of horizontal scale: throughput grows by adding worker replicas. If a worker becomes unreachable, the platform retries per the connector's retry policy and ultimately moves unprocessable messages to Trash (see Processes and Messages).

What the SDK does for you #

The SDK is the only thing that makes a service a worker. It does two jobs:

1. Talks to the platform on your behalf #

  • Exposes the manifest endpoint the platform queries for the worker's components.
  • Receives process requests, dispatches them to the right node, and returns the response in the platform's wire format.
  • Maps thrown exceptions and explicit result codes to the platform's standard error codes.
  • Streams structured logs into the platform's log view.
  • Threads the Application install (credentials + settings) into every connector call.

2. Gives you a framework for components #

  • Base classes for Applications, Connectors, Custom Nodes, and Batch nodes.
  • Declarative settings forms surfaced in the Admin UI.
  • An HTTP client with retries, timeouts, and rate-limit awareness for outbound calls.
  • Helpers for OAuth1 / OAuth2 flows.
  • Unit-test scaffolding for nodes.

Two SDKs today #

Orchesty currently ships SDKs for Node.js and PHP, and the list is expected to grow. The contracts are identical across languages; only the class names differ. See the Reference overview for the per-language class for each concept (Application base, Connector base, Custom Node base, Batch node, ResultCode, ...).

A worker uses one SDK; you can have several workers in the same topology, in different languages.

See also #

© 2025 Orchesty Solutions. All rights reserved.