Workers

A worker combines code, a trigger, output tables, configuration, secrets, and resource hints. One dispatch invokes one bounded run. The same portable specification can register on a local server or in Verglas Cloud.

Worker invariants

Design every worker around the following rules:

Treat the trigger and committed table data as the complete input to a run.
Keep no durable process state between runs.
Use the cron event’s half-open interval [intervalStart, intervalEnd) for incremental pulls.
Read output table names from deployment configuration instead of hard-coding them.
Make every commit idempotent so a replay does not duplicate data.
Read secrets from the runtime environment and never write them to logs.

Worker lifecycle

Current trigger surfaces

The SDK contract defines the following trigger events:

Trigger	Dispatch payload	Typical use
`cron`	Logical date and interval bounds	Scheduled ingestion and backfill
`webhook`	An inbound `Request`	HTTP ingestion
`websocket`	One data frame	Event-driven socket workloads
`data_change`	A table commit notification	Incremental transformations
`kafka`	Topic, partition, offset, key, and value	Stream ingestion

The portable CLI manifest currently registers cron and manual cloud workers. It also registers local-only follow workers. The SDK types the broader trigger contract used by the platform runtime.

Create a portable worker

The current manifest supports JSON and TOML. This filled TOML example packages a Python entrypoint and a referenced secret:

metrics-worker.toml

spec_version = 1
name = "metrics-collector"
exec = ["python3", "collector.py"]
cwd = "/app"
target_tables = ["observability.host_metrics"]

[files]
"collector.py" = "# packaged worker entrypoint\n"

[env]
METRICS_URL = "https://metrics.example.com/v1/samples"
METRICS_TOKEN = "@secret:METRICS_TOKEN"

[trigger]
type = "cron"
cron = "*/10 * * * *"

[resources]
vcpus = 0.5
mem_mib = 512

Create the secret and worker in the cloud:

printf '%s' "$METRICS_TOKEN" | verglas secrets set METRICS_TOKEN
verglas workers create --file ./metrics-worker.toml

verglas workers create --file ./metrics-worker.toml --local
verglas workers push metrics-collector

Inspect and operate workers

verglas workers list
verglas workers get metrics-collector
verglas workers run metrics-collector
verglas workers logs metrics-collector
verglas workers update metrics-collector --schedule '0 * * * *'
verglas workers update metrics-collector --status paused
verglas workers delete metrics-collector

Pass --json before workers when a script needs a stable machine-readable response.

Backfill with logical time

The TypeScript worker contract supports startDate and catchup on cron trigger definitions:

triggers: [
  {
    type: "cron",
    schedule: "0 * * * *",
    startDate: "2026-08-01T00:00:00Z",
    catchup: "sequential",
  },
]

Each replayed run receives its own logical interval. Range the upstream request over that interval. Do not store a cross-run watermark in the worker.

Use idempotency keys

Use a stable input identifier as the commit idempotency key. A data_change worker can use the input snapshot ID:

const result = await ctx.client.table(ctx.output).append(rows, {
  idempotencyKey: `analytics.orders@${ctx.trigger.change.snapshotId}`,
});

If the platform replays the trigger, the duplicate commit becomes a no-op instead of appending the same rows twice.

Get started

Build

SDKs

Reference

Worker invariants

Worker lifecycle

Current trigger surfaces

Create a portable worker

Inspect and operate workers

Backfill with logical time

Use idempotency keys

​Worker invariants

​Worker lifecycle

​Current trigger surfaces

​Create a portable worker

​Inspect and operate workers

​Backfill with logical time

​Use idempotency keys

Worker invariants

Worker lifecycle

Current trigger surfaces

Create a portable worker

Inspect and operate workers

Backfill with logical time

Use idempotency keys