Syndroo docs
Version 0.2.0-rc.1 unpublished release candidate Website GitHub

Run Syndroo locally

The local path builds the Worker from source and runs it on your machine against a local database. You need Node.js and npm, not a Cloudflare account, and none of these steps deploys anything.

Prerequisites

  • Node.js 22 or newer and npm. The repository declares "node": ">=22" and uses npm workspaces.
  • git, if you clone the repository rather than using an existing checkout.
  • Platform credentials, only for the platforms you will publish to. Local development reads them from .dev.vars.

Steps

  1. Install the source

    git clone https://github.com/Syndroo/syndroo.git
cd syndroo
npm install

  2. Create your local secrets file

    Copy the example file and fill in only what you need. It is never committed, and it never reaches a deployment.

    cp .dev.vars.example .dev.vars

    The example file lists all five platforms with placeholder values. Delete or comment out the platforms you are not publishing to: a placeholder that looks like a credential still counts as a configured-but-wrong one, and you want a missing platform to fail loudly with PLATFORM_NOT_CONFIGURED rather than silently attempting a call with a fake value.

    SYNDROO_API_KEY=choose-a-long-random-secret
BLUESKY_IDENTIFIER=your-handle.bsky.social
BLUESKY_PASSWORD=your-bluesky-app-password
BLUESKY_HOST=bsky.social

    SYNDROO_API_KEY is the Bearer token your client sends. BLUESKY_PASSWORD must be an app password, not the account password. Credentials for other platforms are optional and independent.

  3. Create the local database

    npm run db:migrate:local

    This applies the migrations to the local Miniflare database. It has no effect on anything in Cloudflare.

  4. Start the Worker

    Build the workspace first. A clean checkout has no compiled output for the workspace packages yet, and Wrangler needs those built adapter dependencies; npm run dev itself serves the Worker source entry (packages/cloudflare-worker/src/index.ts from wrangler.jsonc) rather than compiling the workspace.

    npm run build

    Then start it:

    npm run dev

    The local Worker listens on http://localhost:8787 and loads the optional platform secrets from .dev.vars. Warnings about unused platform secrets are expected.

  5. Check it answers

    export SYNDROO_URL="http://localhost:8787"
export SYNDROO_API_KEY="the-same-secret-from-dev-vars"
curl "$SYNDROO_URL/health"

    Expected: {"status":"ok"}. Publishing from here works exactly as in Publish your first post, and it posts to the real platform when credentials are configured.

  6. Run the local test gates

    npm test        # workspace unit tests
npm run check   # builds and type-checks the workspaces
npm run test:e2e  # Mock SNS end-to-end gate
    The end-to-end gate needs no credentials.

    It injects fake bindings, replaces the network boundary with a loopback Mock SNS server, and fails closed on any outbound attempt outside its allowlist. It exercises wiring, persistence, idempotency, ambiguity handling and scheduling. It cannot prove provider permissions, API compatibility or rate limits.

What the local path does not do

  • It does not deploy. A local run is an isolated process with its own database.
  • It does not validate a platform. A mock-tested adapter is still mock-tested: no live-account acceptance record exists for this candidate.
  • It does not prove the platform's current rules. Text limits are enforced locally, but permissions, rate limits and API access are decided by the platform. Check the platform's own documentation through its guide.
  • It does not include a dashboard, SDK or MCP server. The interface is the HTTP API.

Applies to

Syndroo 0.2.0-rc.1 (unpublished release candidate). For the production path instead, see Deploy the Worker to Cloudflare.