# Orchesty Node.js Worker - Blueprint (/docs/blueprints/orchesty-nodejs-bootstrap)



Starter for [Orchesty](https://orchesty.io) integration workers built with **Node.js**, **TypeScript**, and **`@orchesty/nodejs-sdk`**. Register your Applications, Connectors, Batches, and custom Nodes, then connect the worker to your Orchesty instance.

**Tech stack:**

| Layer    | Technology             |
| -------- | ---------------------- |
| Runtime  | Node.js LTS, pnpm      |
| SDK      | `@orchesty/nodejs-sdk` |
| AI rules | `@orchesty/nodejs-ai`  |
| Tests    | Jest + ESLint          |

The worker listens on port **8080**. `GET /applications` returns `{"items":[...]}` once it is running.

<a href="https://github.com/rock8-cloud/orchesty-nodejs-bootstrap" target="_blank" rel="noopener noreferrer">
  View on GitHub →
</a>

***

## Connect to Orchesty [#connect-to-orchesty]

The deploy dialog asks how the worker should reach Orchesty. Fill it in and the first deploy starts connected.

* **Orchesty Cloud:** enter your **Tenant ID**. **Cloud region** is prefilled with `eu2`.
* **Self-hosted:** enter **Backend URL**, **Starting point URL**, and **Worker API host**.
* **Orchesty API key** in both cases.

All fields are optional. If you skip them, the worker stops right after start until you set them:

1. Open the worker service and go to **Deployments** → **Env Vars**.
2. Set `ORCHESTY_API_KEY` and either `TENANT_ID` (plus `CLOUD_REGION` if not `eu2`) or `BACKEND_URL`, `STARTING_POINT_URL`, and `WORKER_API_HOST`.
3. Redeploy the service.

Once it runs, register the service's public URL as a worker in Orchesty.

<Callout type="warn">
  `CRYPT_SECRET` is generated during the blueprint deploy and encrypts stored application credentials. Keep it stable. Changing it makes existing credentials unreadable.
</Callout>

***

## Project Structure [#project-structure]

```
├── src/
│   └── index.ts          # Worker entry point: register Applications and Nodes here
├── .jest/                # Jest setup helpers
├── Dockerfile            # Multi-stage production image
├── Makefile              # install, start, test, lint, build
├── AGENTS.md             # Setup workflow for AI coding assistants
└── .mcp.json             # Rock8Cloud MCP endpoint for agent-driven deploys
```

**Key design decisions:**

* The platform sets `PORT` and the image maps it onto the SDK's `APP_PORT`. Do not set `PORT` yourself.
* `AGENTS.md` tells AI coding assistants how to copy the Orchesty rules from `@orchesty/nodejs-ai` into their own rule directory, so generated code follows Orchesty conventions.
* Every push to your fork's `main` branch redeploys the worker.

***

## Environment Variables [#environment-variables]

| Variable             | Required       | Description                                                          |
| -------------------- | -------------- | -------------------------------------------------------------------- |
| `CRYPT_SECRET`       | yes            | Encrypts stored application credentials. Generated by the blueprint. |
| `ORCHESTY_API_KEY`   | yes            | API key the worker uses to talk to Orchesty.                         |
| `TENANT_ID`          | Orchesty Cloud | Your Orchesty Cloud tenant.                                          |
| `CLOUD_REGION`       | no             | Orchesty Cloud region, default `eu2`.                                |
| `BACKEND_URL`        | self-hosted    | Orchesty backend URL.                                                |
| `STARTING_POINT_URL` | self-hosted    | Orchesty starting-point URL.                                         |
| `WORKER_API_HOST`    | self-hosted    | Orchesty worker-api URL.                                             |
| `LOGGER_TYPE`        | no             | Logger output format.                                                |

***

## Running Locally [#running-locally]

```bash
make init-dev          # installs deps, generates .env, starts the dev server
make init-dev-docker   # same, inside a dev container (no local Node.js needed)
make test              # lint + unit tests
```

See the [Orchesty docs](https://docs.orchesty.io/) for building Applications and Connectors.