# Install Go 1.21 or later
# https://go.dev/dl/

go mod download   # from the repo root containing go.mod

If you are wrapping this from a Node.js process (e.g., via the pulumi-node plugin domain), the native Go binary must be compiled and placed on PATH:

cd source
go build -o pulumi-engine ./cmd/pulumi

No npm packages, no pod install, no Android linking required. The integration surface from Node.js is the Pulumi Automation API gRPC interface or subprocess invocation of the compiled binary.

Project setup

1. Clone or copy the source/ directory alongside your project root.
2. Ensure go.mod at source/ root lists module github.com/pulumi/pulumi/sdk/v3 or the appropriate module path — do not rename it.
3. If embedding in a Go project, add a replace directive in your own go.mod:

   replace github.com/pulumi/pulumi/pkg/v3 => ./source
   

4. For a Node.js/TypeScript wrapper project, compile the Go binary first:

   cd source && go build -o ../bin/pulumi-engine ./cmd/pulumi
   

5. Set required environment variables before invoking:

   export PULUMI_HOME=~/.pulumi          # plugin and credential storage
   export PULUMI_BACKEND_URL=file://./state   # DIY file-based backend
   export PULUMI_CONFIG_PASSPHRASE=secret    # passphrase secrets provider
   

6. For TypeScript projects using the Automation API (which calls this engine), install:

   npm install @pulumi/pulumi
   

   The @pulumi/pulumi npm package communicates with the engine binary built from this source.

Public API

No TypeScript-level exports exist in this source (it is Go). The following documents the Go package APIs visible from the file layout, which a tooling author would call directly in Go or access indirectly via gRPC/subprocess from TypeScript.

backend.Backend

// pkg/backend/backend.go
type Backend interface {
    Name() string
    URL() string
    GetStack(ctx context.Context, stackRef StackReference) (Stack, error)
    CreateStack(ctx context.Context, stackRef StackReference, root string, opts *CreateStackOptions) (Stack, error)
    RemoveStack(ctx context.Context, stack Stack, force bool) (bool, error)
    ListStacks(ctx context.Context, filter ListStacksFilter, inContToken ContinuationToken) ([]StackSummary, ContinuationToken, error)
    UpdateStack(ctx context.Context, stack Stack, op UpdateOperation) (history.UpdateInfo, error)
}

The Backend interface is the primary abstraction for all state storage operations. Implement it to create a custom state backend, or use the provided diy or httpstate implementations.

workspace.Project

// pkg/workspace/
type Project struct {
    Name        tokens.PackageName
    Runtime     ProjectRuntimeInfo
    Description *string
    Backend     *ProjectBackend
    Options     *ProjectOptions
}

func LoadProject(path string) (*Project, error)

LoadProject reads and validates a Pulumi.yaml file from the given path. Use this when building CLI tooling that needs to resolve project configuration before initializing a backend or engine context.

secrets.Manager

// pkg/secrets/
type Manager interface {
    Type() string
    State() json.RawMessage
    Encrypter() (config.Encrypter, error)
    Decrypter() (config.Decrypter, error)
}

Manager abstracts secrets providers (passphrase, AWS KMS, Azure KeyVault, GCP KMS, HashiCorp Vault). Use it when you need to encrypt stack configuration values or state secrets independently of the backend.

Working examples

Scenario - Load a project and resolve its backend

A build tool reads Pulumi.yaml, resolves the configured backend URL, and prints the stack list.

// In a Node.js wrapper — invokes the compiled Go binary via Automation API
import { LocalWorkspace } from "@pulumi/pulumi/automation";

async function listStacks() {
    const ws = await LocalWorkspace.create({
        workDir: "./infra",         // directory containing Pulumi.yaml
        envVars: {
            PULUMI_BACKEND_URL: "file://./state",
            PULUMI_CONFIG_PASSPHRASE: "dev-passphrase",
        },
    });
    const stacks = await ws.listStacks();
    for (const s of stacks) {
        console.log(s.name, s.current ? "(current)" : "");
    }
}

listStacks().catch(console.error);

Scenario - Run an update programmatically

Use the Automation API (backed by the engine in source/engine/) to deploy a Pulumi program without the interactive CLI.

import { LocalWorkspace, UpResult } from "@pulumi/pulumi/automation";
import * as pulumi from "@pulumi/pulumi";

async function deploy(): Promise<UpResult> {
    const program = async () => {
        // Inline Pulumi program — engine from source/engine/ evaluates this
        const cfg = new pulumi.Config();
        return {
            region: cfg.get("region") ?? "us-east-1",
        };
    };

    const stack = await LocalWorkspace.createOrSelectStack({
        stackName: "dev",
        projectName: "example",
        program,
    }, {
        envVars: {
            PULUMI_BACKEND_URL: "file://./state",
            PULUMI_CONFIG_PASSPHRASE: "dev-passphrase",
        },
    });

    return stack.up({ onOutput: console.log });
}

deploy().then(r => console.log("outputs:", r.outputs)).catch(console.error);

Scenario - Destroy a stack and clean up state

import { LocalWorkspace } from "@pulumi/pulumi/automation";

async function teardown() {
    const stack = await LocalWorkspace.selectStack({
        stackName: "dev",
        workDir: "./infra",
    }, {
        envVars: {
            PULUMI_BACKEND_URL: "file://./state",
            PULUMI_CONFIG_PASSPHRASE: "dev-passphrase",
        },
    });

    await stack.destroy({ onOutput: console.log });
    await stack.workspace.removeStack("dev");
    console.log("Stack removed.");
}

teardown().catch(console.error);

File walkthrough

• asset/ - Defines Asset and Archive types used as resource property values; handles blob, file, and URI variants.
• authhelpers/ - Resolves GCP Application Default Credentials for backends that authenticate to Google Cloud.
• backend/ - Core Backend interface plus diy (file-system) and httpstate (Pulumi Cloud) implementations; also contains snapshot persistence and journal logic.
• backend/display/ - Renders update events to terminal (tree, progress bar, JSON output modes).
• channel/ - Internal helper for broadcasting engine events over Go channels.
• cmd/ - CLI command implementations (pulumi up, pulumi destroy, etc.) wired into Cobra.
• codegen/ - Generates typed SDKs in Go, Python, TypeScript, and .NET from Pulumi schema.
• display/ - Lower-level display primitives shared between CLI and backend display packages.
• engine/ - Plan, update, refresh, and destroy orchestration; calls resource providers via gRPC.
• graph/ - Builds and traverses the resource dependency DAG for ordering operations.
• importer/ - Generates resource code from live cloud state for pulumi import.
• logging/ - Log-level filtering and structured log forwarding to the Pulumi engine event stream.
• operations/ - Queries runtime logs from supported providers (AWS CloudWatch, etc.).
• pluginstorage/ - Manages download, caching, and installation of provider plugin binaries.
• resource/ - URN construction, resource state structs, property value types, provider plugin protocol.
• secrets/ - Manager interface and built-in implementations (passphrase, cloud KMS providers).
• testing/ - Shared test fixtures, integration test harness, and mock backends.
• util/ - Cross-cutting utilities: retry, RPC helpers, filesystem, command execution, contract assertions.
• workspace/ - Loads Pulumi.yaml and per-stack config files; resolves plugin requirements.

Common pitfalls and fixes

• PULUMI_CONFIG_PASSPHRASE not set: The passphrase secrets provider panics at startup if this env var is absent; always set it or switch to a cloud KMS provider URL via PULUMI_SECRETS_PROVIDER.
• Backend URL scheme mismatch: file:// URLs must use three slashes for absolute paths (file:///abs/path); a two-slash URL silently resolves relative to CWD and creates duplicate state directories.
• Go module replace directive not applied: If you copy source/ and edit it, your go.mod replace directive must exactly match the module path declared inside source/go.mod; a mismatch causes the compiler to fetch the upstream version instead.
• Plugin binary not on PATH: The engine resolves provider plugins by name (pulumi-resource-<provider>) from PULUMI_HOME/plugins or PATH; missing binaries produce a cryptic "no resource plugin" error rather than a download prompt in embedded mode.
• workspace.LoadProject path must point to the directory, not the file; passing Pulumi.yaml directly returns a path error.
• ESM/CJS interop with @pulumi/pulumi Automation API: The npm package ships CJS; if your TypeScript project uses "type": "module", import via createRequire or set "moduleResolution": "node16" in tsconfig.json to avoid ERR_REQUIRE_ESM.

Vibe-coding prompt template

I have a copy of the Pulumi Core Engine & SDK Libraries (Go source) in the `source/` directory of my project.
I also have USAGE.md which documents the layout, Go package APIs, and environment setup.

My project is a [TypeScript / Go / Node.js] application that needs to [describe your goal, e.g., "programmatically deploy infrastructure stacks and read their outputs"].

Please help me integrate `source/` into my project step by step:

1. Read USAGE.md fully before writing any code.
2. Check `source/backend/`, `source/engine/`, `source/workspace/` for the relevant Go packages.
3. If I am using TypeScript, use the `@pulumi/pulumi` Automation API (which shells out to the engine binary built from source/) — show me how to compile the binary and wire it up.
4. If I am using Go directly, add the correct `replace` directive to my `go.mod` and import the packages by their real module paths from `source/go.mod`.
5. Set up the required environment variables (PULUMI_BACKEND_URL, PULUMI_CONFIG_PASSPHRASE, PULUMI_HOME).
6. Write a working example that [describe specific scenario, e.g., "creates a stack, runs an update, and prints the stack outputs"].
7. Do not invent package names or function signatures — only use what is present in `source/` and documented in USAGE.md.

License and credit

This source is licensed under the Apache License 2.0. See source/LICENSE if present, or refer to the upstream repository at https://github.com/pulumi/pulumi. The upstream package is the canonical Pulumi open-source monorepo maintained by Pulumi Corporation.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

ElectricSQL Real-Time Postgres Sync Engine

Automation, Utilities & Developer Tools

Free