Start here

Modes

SDK reference

Shared reference

Docs navigation

Start here

Modes

SDK reference

Shared reference

DocsSDK ModeQuickstart

Get Weev running in your application

Install the SDK, register jobs, expose the execution endpoint, and create the first deployment. Your code stays in your service throughout.

Note

This guide covers SDK Mode — the path that's live today.

The Weev agent and Link Mode are upcoming — design previews live at those links, and each gets its own guide when it ships. Everything below works now.

Setup flow

SDK → CLI → Deploy

Time to first run

About 4 minutes

Assumes

A service to host jobs

Overview

How the integration works

Weev is a control plane for background workflows. You define jobs locally, use the CLI to generate a manifest from that code, and push the resulting workflow into Weev for orchestration.

1 · SDK

Keep workflow intent versioned with the rest of your application.

2 · CLI

Generate a manifest

Convert your registered jobs into a deployable workflow definition.

3 · Weev

Run with visibility

Trigger, manage and inspect background work from one operational layer.

Before you begin

What this guide assumes

You need an existing service where your jobs will execute. The examples use Express because it is the smallest common case, but the goal is the same in any framework: keep your job handlers inside your app and expose one endpoint for Weev to call.

Note

This is the shortest path to a working integration. It does not attempt to document every API surface or deployment option.

Step 1

Install the SDK

Add the SDK to the service that will host your job handlers. If your app already uses Express, only the SDK package is required.

Install dependencies

$ pnpm add @weev/sdk # the Weev runtime
$ pnpm add express # only if your service uses Express

Step 2

Register jobs

Jobs are defined directly in code. Each job belongs to a batch, and the batch is the workflow Weev manages. Dependencies are expressed with predecessors so Weev can enforce execution order.

Example job

import { weev } from "@weev/sdk";

// define a job inside a batch so Weev can build the workflow
weev.job(
  {
    name: "generateInvoices",
    batch: "monthlyBillingRun",
    description: "Generate invoices for the current billing cycle",
    predecessors: ["loadActiveSubscriptions"]
  },
  async (ctx) => {
    ctx.log("info", "Generating invoices");
    return { ok: true };
  }
);

name

Stable job identifier inside the batch.

batch

Groups related jobs into one workflow.

predecessors

Declares upstream jobs that must finish first.

Step 3

Mount the endpoint

Weev needs a stable execution endpoint in your service. Mount the middleware once so the platform can call into your app and run the registered handlers.

Mount the execution endpoint

import express from "express";
import { createWeevMiddleware } from "@weev/sdk/express";

// receives execution requests from Weev
const app = express();
app.use(createWeevMiddleware());
app.listen(4100);

Note

Weev calls your app. Your app still executes the job.

Weev does not move your business logic into a separate runtime. It calls your application, and your application executes the job with its existing code and data access.

Runtime behavior

Dedupe limits

Weev identifies each dispatched execution with a stable jobRunId. If the platform redelivers the same run request to your /.weev/run endpoint, the SDK dedupes active and recently completed run IDs inside the running service process.

Scope

Per process

The dedupe set lives in memory. A duplicate reaching the same Node process is accepted without invoking your handler again.

Limit

Multi-replica services

If replica A receives the first dispatch and replica B a retry, B has no record of A's in-memory run set and may execute the job again.

Future

Stronger coordination

A later version should use durable dispatch leases or attempt tokens so suppression works across replicas and restarts.

Caution

Treat handlers as idempotent in production

The SDK guard reduces accidental duplicate execution from retry and redelivery, but it is not distributed exactly-once execution. With more than one replica, make external side effects idempotent with your own stable keys, unique constraints or application-level locks.

Step 4

Deploy your workflow

Once jobs are registered and the endpoint exists, use the CLI to connect the repo and create the first deployment.

Initialize the project

Creates local Weev configuration in your repository.

weev init

Authenticate

Connects your machine to your Weev workspace.

weev login

Link the codebase

Associates this repo with the correct organization, project and environment.

weev link

Generate the manifest

Scans your codebase for registered jobs and builds the workflow definition.

weev generate

Create a deployment

Uploads the workflow to Weev so it can be triggered and monitored.

weev push

After setup

What you get

After the first deployment, Weev has enough context to manage the workflow as an operational system rather than a loose set of background scripts.

Versioned workflow definitions

Changes to orchestration are pushed intentionally instead of drifting in place.

Manual and recurring runs

Trigger runs directly or configure recurring execution after deployment.

Execution visibility

Inspect active work, failures and run state in one place.

Cleaner ownership

Developers own job behaviour while Weev handles orchestration discipline.

Ready for your first run?

Join the waitlist Why teams switch