Dev Overlay

When a service is deployed and used in production, starting a second instance with the same credentials would normally enter the round-robin pool — meaning your local development instance could receive production messages. Dev overlay solves this problem.

How It Works

If a service is started with the same credentials plus a personal access token (the devToken), Requence registers it as a dev service instead of adding it to the production pool. When the same user — identified by that personal access token — starts a task via the UI or via a package, Requence will always route messages to the dev service first. This lets you test changes to your service implementation without risking production.

Setup

TypeScript

import { createService } from '@requence/service'

createService(
  {
    version: '1.0.0',
    devToken: process.env.REQUENCE_DEV_TOKEN,
  },
  (ctx) => {
    // This instance only receives messages from your own tasks
    return ctx.input
  },
)

Python

import os
from requence.service import Service

def handler(ctx):
    # This instance only receives messages from your own tasks
    return ctx.input

Service(
    {"version": "1.0.0"},
    handler,
    dev_token=os.getenv("REQUENCE_DEV_TOKEN"),
)

The dev token is resolved in the same order as the access token — config option, environment variable (REQUENCE_SERVICE_DEV_TOKEN / REQUENCE_DEV_TOKEN), or config file.

Component Reload

If your service renders surfaces, a dev instance also watches the built file behind every component you registered. Rebuild it and the frame swaps to the new bundle in place — same props, same handlers, same node, no re-render and no new task run.

It reaches every surface your dev session ever drew, and nothing else: a live panel, a form on a node that is still waiting, and a surface on a task that finished last week all swap alike, while a production surface of the same component is untouched. Restarting your service does not strand the surfaces it drew a moment before.

Two limits worth knowing:

• What swaps is the code, never the props. A component that only shows what the last render sent it will show exactly that until your service renders again.
• Handler edits need a restart. The handler runs in your service process, not in the bundle.

While your dev process is stopped, the surfaces it drew report their controls as unreachable and say so in those terms — the dev process that drew this surface is not running — not as a missing deployment. Start it again and they come back.

Combining with Branching

Dev overlay only affects the service implementation — the code that runs. If you also need to change the service definition (input schema, configuration schema, or outputs), combine dev overlay with branching. This way you can iterate on both the service logic and its contract without touching the published version.