Node

Node.js 22 and 24 are supported for the npm CLI launcher and the Pulse Node adapter. Pulse runs TypeScript programs. There is no Python or Rust Pulse adapter.

The published host is Pulse v1.0.0, image ghcr.io/trigora-dev/pulse:1.0.0. A normal deployment pulls that image. Building trigora-pulse from source is for a change to the host, not for running a Program. Deploy is the two-container layout.

Install

npm install @trigora/sdk trigora

The npm trigora package launches the Rust CLI. trigora pulse start and trigora pulse connect are the Pulse commands. trigora dev is the local SQLite runtime. trigora deploy and trigora start talk to local development or Trigora Cloud. They do not start a Pulse execution.

Create a Program

This is the Program the recovery proof runs. Effect a commits, the execution waits, then effect b runs. The first effect is not repeated after a crash if its result is already in the journal.

import { appendFileSync } from "node:fs";

import { effect, waitForEvent } from "@trigora/sdk";

export default async function program() {
  const first = await effect("a", () => {
    appendFileSync(process.env.PULSE_EFFECT_LOG ?? "", "a 1\n");
    return 1;
  });
  await waitForEvent("continue");
  const second = await effect("b", () => {
    appendFileSync(process.env.PULSE_EFFECT_LOG ?? "", "b 2\n");
    return 2;
  });
  return { first, second };
}

Point trigora.toml at the file:

[project]
name = "pulse-demo"
programs = ["src/**/*.ts"]

Set TRIGORA_TOKEN

export TRIGORA_TOKEN=...

The token belongs on the host. It selects the workspace at https://api.trigora.dev. Do not combine it with TRIGORA_PULSE_AUTHORITY_URL, TRIGORA_PULSE_WORKSPACE_ID, or TRIGORA_PULSE_WORKSPACE_TOKEN. Those three are only for a local direct client.

Without a token, the host prints Durability is not configured. and exits 2. --ephemeral is the only start that skips the token. It keeps the checkpoint in memory and does not recover after the host exits.

Start the host and adapter

trigora pulse start

The command compiles the project, starts trigora-pulse, and starts the Node adapter beside it. The adapter registers the handlers. When that registration finishes it prints:

ready

trigora pulse start does not create an execution. trigora start is not a substitute. It targets trigora dev or, with --remote, Trigora Cloud.

Start an execution

The application starts an execution by sending { type: "start", executionId } on the adapter session after registration. The Compose reference does that when PULSE_EXECUTION_ID is set. Deploy shows the two containers and that variable.

For this Program, set PULSE_EFFECT_LOG to a file both you and the effect can write. After the start is accepted, that file contains:

a 1

Effect b has not run. The execution is waiting for continue.

Inspect

Read the effect log and the host log. a 1 with no b 2 means the first effect committed and the wait has not been released.

The dashboard situation is a projection (terminal, owned, dormant, or recoverable). It can lag the checkpoint. See Limits.

Restart and recover

1. Stop the host and the application. The lease expires. The execution stays on the pinned artifact.
2. Start a new host and application with the same artifact. Do not set PULSE_EXECUTION_ID or PULSE_RESUME_EXECUTION_ID.
3. The replacement discovers the execution. Effect a is not written again.
4. When continue is delivered, effect b writes b 2 once. The log is a 1 followed by b 2.

The steps, including how the reference entrypoint delivers continue, are in Recovery. Trigora does not replace the container for you.

Connect to a host that is already running

trigora pulse connect does not start a host. Container deployment uses it in the application container. --dir is the socket directory the host already bound. Both processes must run as the same user. The host rejects a different uid.

trigora pulse connect --dir /pulse

--prepare writes the handler manifest, prints its path, and exits without registering:

trigora pulse connect --dir /pulse --prepare

Troubleshooting

What you see	What it means
Durability is not configured. and exit 2	TRIGORA_TOKEN is missing or empty, and the host is not --ephemeral.
TRIGORA_TOKEN cannot be combined with TRIGORA_PULSE_AUTHORITY_URL...	The customer token and the three direct-client variables are set together. Use one mode.
Incompatible Pulse host and exit 1	The host version or protocol does not match the CLI. Pulse 1.0.0 is host 1.0.0 and protocol 1.
socket peer was rejected	The adapter uid is not the host uid. Use the same user on both containers.
Host log event waiting-for-version	This process can see the execution, but its artifact hash is not the pinned one. Keep a host that still runs the pinned artifact. See Versions.