SDKs

Weldall publishes the npm CLI plus TypeScript and Python SDKs. The CLI runs on an employee’s device. An SDK runs inside a connected service.

@weldall/cli

@weldall/cli installs the weldall command. Node.js 22.15 or newer is required.

npm (recommended)

npm install --global @weldall/cli@latest
weldall --version

Experimental standalone binaries

Standalone binaries require no Node.js, npm, or Bun. Initial targets are Linux x64, Windows x64, and macOS ARM64/x64. The macOS binaries are signed with a Developer ID certificate and notarized by Apple, so Gatekeeper runs them without a warning. Linux and Windows binaries are not signed yet; that work is in progress. Download the appropriate asset from GitHub Releases.

# macOS and Linux
chmod +x ./weldall

Windows PowerShell: Unblock-File .\weldall.exe.

@weldall/sdk

@weldall/sdk validates requests before a service reads data or makes changes. It provides a Fetch API and adapters for Hono, Next.js, and Astro.

pnpm add @weldall/sdk

Create one Weldall instance when the service starts:

import { initWeldall } from "@weldall/sdk";

const weldall = initWeldall("https://weldall.example.com", {
  resource: "https://contracts.example.com/api",
  publicOrigin: "https://contracts.example.com",
  clientId: "weldall-cli-at-contracts",
  supportedScopes: ["contracts:read", "contracts:update"],
  signingKey,
  replayStore,
});

In a Fetch handler, weldall.verify(request, { scopes: [...] }) checks the request before business logic runs. Framework adapters provide middleware or handler wrappers:

• @weldall/sdk/hono
• @weldall/sdk/next
• @weldall/sdk/astro

The SDK requires Node.js 22.15 or newer. Next.js routes must use the Node.js runtime.

Protect a Python service

Use weldall-sdk when the receiving service runs on Python 3.11 or newer. The SDK checks user and machine requests before application code runs. It also serves the protocol routes that Weldall needs.

Install the core package on its own, or add the extra for your framework:

pip install weldall-sdk
pip install 'weldall-sdk[fastapi]'
pip install 'weldall-sdk[django]'

from weldall import in_memory
from weldall.adapters.fastapi import init_weldall

weldall = init_weldall(
    "https://weldall.example.com",
    {
        "resource": "https://contracts.example.com/api",
        "public_origin": "https://contracts.example.com",
        "client_id": "weldall-cli-at-contracts",
        "supported_scopes": ["contracts:read"],
        "signing_key": signing_key,
        "replay_store": in_memory(),
    },
)
weldall.register_routes(app)

register_routes() adds the Weldall protocol routes to this FastAPI application. Protect application routes with require_auth() and read the verified identity from the request state. Django projects use the supplied middleware, views, and URL patterns instead.

The Python SDK reference covers machine calls, published skills, signing keys, replay protection, and the production checklist.

Publish skills from a service

A resource can publish its own agent instructions. Add a skills provider to the same SDK configuration:

const weldall = initWeldall("https://weldall.example.com", {
  resource: "https://contracts.example.com/api",
  publicOrigin: "https://contracts.example.com",
  clientId: "weldall-cli-at-contracts",
  supportedScopes: ["contracts:read"],
  signingKey,
  replayStore,
  skills: {
    items: [
      {
        id: "list",
        title: "List contracts",
        requiredScopes: ["contracts:read"],
        visibility: "HIDDEN_IF_UNALLOWED",
        content:
          "# List contracts\n\nRun `weldall request --scope contracts:read https://contracts.example.com/api/contracts`.",
      },
    ],
  },
});

Skill IDs are local to the resource. If the registered resource key is contracts, Weldall exposes this skill as contracts.list.

Use skills.load instead of skills.items when the catalog comes from a database or another local source:

skills: {
  load: async () => loadPublishedSkills(),
}

The provider receives no employee identity. It must return the same catalog for every caller.

DEFAULT keeps a skill visible and reports missing scopes. HIDDEN_IF_UNALLOWED hides it unless the employee has every required scope. Visibility controls discovery, not authorization: the API route still needs its own protection policy, and skill instructions never grant access. Required scopes, including protected system scopes, must already exist in Weldall; unknown scopes are withheld from users and shown as warnings to administrators.

The Hono adapter mounts the catalog route through weldall.registerRoutes(app). Fetch, Next.js, and Astro integrations must expose weldall.handlers.skills at /.well-known/weldall-skills alongside the OAuth metadata, token, and JWKS handlers.

Follow the TypeScript guide for a complete Hono setup or the Python guide for FastAPI and the Django example. Both link to the SDK source and example directories on GitHub. Security covers keys, replay protection, and the protocol boundary.