Get Started

Build your first worker — pick an SDK, scaffold the project, then connect

How to create a new Orchesty worker from scratch: pick the SDK (Node.js or PHP), scaffold the project (AI bootstrap or manual), configure the env, and only then register it against an Orchesty instance.

A worker is a small project with the Orchesty SDK installed — it hosts your Application classes and your Connector / Batch / Custom Node code, and talks to an Orchesty instance over HTTP or a tunnel. Both the Node.js SDK and the PHP SDK work standalone, so the order is always the same:

  1. Pick an SDK (Node.js or PHP).
  2. Scaffold the project (AI bootstrap or manual).
  3. Configure the env file.
  4. Verify the build compiles.
  5. Register and connect the worker to your Orchesty instance.

Steps 1–4 happen entirely on your machine. Step 5 is a separate flow in the Admin UI — see Connect to an instance when you're ready.

Step 1: Pick an SDK #

Node.js SDKPHP SDK
Package@orchesty/nodejs-sdkorchesty/php-sdk
RuntimeNode.js 20+PHP 8.1+ + Composer
AI BootstrapYes — orchesty-nodejs-bootstrap ships with @orchesty/nodejs-ai rulesManual scaffold today
Tunnel modeYes (built-in)HTTP mode only for now
Best forGreenfield workers, AI-assisted projectsPHP shops with existing Symfony/Laravel infrastructure

If you have no strong preference, pick Node.js — it has the AI bootstrap path and the tunnel helper, which makes local development easiest. Both SDKs expose the same conceptual building blocks (Application, Connector, Batch, Custom Node).

Step 2A: Scaffold with AI (Node.js, recommended) #

Open an empty folder in an AI editor (Cursor, Claude Code, Windsurf or similar) and paste the bootstrap prompt from the AI Bootstrap page. The agent does the rest on its own:

  • Clones https://github.com/Orchesty/orchesty-nodejs-bootstrap.git into the current directory and reinitialises git.
  • Runs make init-dev — auto-generates .env from .env.dist, installs dependencies (auto-detects pnpm/npm), and starts the dev server.
  • Reads AGENTS.md and materialises the rule pack from node_modules/@orchesty/nodejs-ai/rules/*.mdc into your editor's native rule format using the per-tool snippets in node_modules/@orchesty/nodejs-ai/AI-INSTRUCTIONS.md.
  • Verifies the build with make test (lint + unit tests).

You only review the diff, then continue. See Building Integrations with AI for the bigger picture and the Onboarding wizard's scaffold step for the same flow guided turn-by-turn.

Step 2B: Scaffold manually #

Node.js (manual) # 

git clone https://github.com/Orchesty/orchesty-nodejs-bootstrap.git my-orchesty-worker
cd my-orchesty-worker
rm -rf .git && git init
make init-dev          # installs deps, generates .env, starts the dev server

This pulls @orchesty/nodejs-sdk and the dev tooling (TypeScript, Jest, ESLint, nodemon, plus @orchesty/nodejs-ai for AI editors). The resulting structure is intentionally tiny:

src/
  index.ts                              # entry point: register applications, connectors, batches
.env.dist                               # template; make auto-generates `.env` from this
Makefile                                # canonical entry point — `make init-dev`, `make test`, ...
AGENTS.md                               # setup workflow for AI editors
package.json                            # depends on @orchesty/nodejs-sdk
node_modules/@orchesty/nodejs-ai/rules/ # AI rules (used in the AI bootstrap path)

PHP (manual) # 

mkdir my-orchesty-worker && cd my-orchesty-worker
composer init --name="acme/my-orchesty-worker" --no-interaction
composer require orchesty/php-sdk symfony/dotenv

Then create an index.php (or your framework's entry script) that boots the SDK container and registers your components, mirroring the Node.js src/index.ts pattern. The same .env variables apply.

PHP SDK tunnel support is on the roadmap. Until it ships, expose your worker via ngrok or a LAN IP when running against a remote instance.

Step 3: Configure the env file #

make init-dev already generated .env from .env.dist for you. It ships placeholder values for the keys the worker reads at startup (BACKEND_URL, WORKER_ID, WORKER_SECRET, the encryption key). You don't fill them in here — the next step registers the worker in the Admin UI and the UI hands you the exact env block to paste in. Skip ahead to step 5 when you're ready.

Step 4: Verify the build compiles # 

# Node.js
make test              # lint + unit tests

The empty test suite passes immediately. If TypeScript errors appear, check the Node.js version (20+) and the install output. For PHP, run the equivalent linter / static analysis if you wired it up.

Step 5: Register and connect #

Now — and only now — you take the worker to the Admin UI:

  1. Go to Settings → Workers → Add Worker.
  2. Pick Tunnel for local development, or HTTP if you're running behind a stable public hostname.
  3. Save the worker. The dialog hands you the exact .env block to paste in.
  4. Start the worker (make start for Node.js, php index.php or your usual command for PHP).

The worker connects back to the platform and shows as connected in the Admin UI — its registered Applications, Connectors and Custom Nodes immediately become available in the topology editor.

The full registration walkthrough lives in Connect to an instance.

What's next #