Skip to content
Swytchcode logo Swytchcode logo Swytchcode Docs docs

JavaScript SDK

The Swytchcode JavaScript Runtime SDK lets you execute trusted tools directly from JavaScript and TypeScript applications.

Instead of integrating with individual provider SDKs or building your own execution layer, the runtime provides a single interface for calling APIs defined in your Swytchcode project.

Because the runtime uses the same execution engine as the Swytchcode CLI and MCP Server, your application automatically benefits from the same authentication, policy enforcement, retries, and execution behavior across every environment.

The JavaScript Runtime SDK is open source. View the source code on GitHub: runtime-js.

Before you begin

Before using the Runtime SDK, make sure you have:

  • Installed the Swytchcode CLI
  • Authenticated your Swytchcode account (swy login)
  • Initialized a Swytchcode project (swy init)
  • Fetched at least one integration bundle (swy get <project>)
  • Enabled the tools you want your application to execute (swy add <canonical_id>, or swy add method <canonical_id> explicitly)

The SDK only executes tools that already exist in your project’s tooling.json - it doesn’t discover or install integrations on your behalf. If you haven’t completed those steps yet, start with the CLI Quickstart.

Installation

Install the runtime using your preferred package manager.

Terminal window
npm install @swytchcode/runtime
Terminal window
pnpm add @swytchcode/runtime
Terminal window
yarn add @swytchcode/runtime

Creating a Runtime

Create a runtime instance once during application startup.

import { SwytchcodeRuntime } from "@swytchcode/runtime";


const runtime = new SwytchcodeRuntime();

When initialized, the runtime automatically discovers your Swytchcode project and loads its configuration.

This includes:

  • enabled tools
  • installed integrations
  • execution policies
  • authentication settings
  • project configuration

No additional setup is required.

Executing a Tool

Every trusted method or workflow can be executed using its canonical ID.

const response = await runtime.execute({
  tool: "github.issue.create",
  input: {
    owner: "swytchcodehq",
    repo: "docs",
    title: "Update JavaScript SDK guide"
  }
});

The runtime returns the provider response after completing the execution pipeline.

You don’t need to manually build HTTP requests or initialize provider SDKs.

Executing Workflows

Methods and workflows are executed using the same API.

await runtime.execute({
  tool: "github.release.workflow",
  input: {
    version: "v2.0.0"
  }
});

The runtime automatically executes every workflow step in order while maintaining execution context between steps.

What happens during execution?

Calling runtime.execute() starts the complete Swytchcode execution pipeline.

Application


      │
      ▼


Runtime SDK


      │
      ▼


Validate Input


      │
      ▼


Resolve Authentication


      │
      ▼


Evaluate Policies


      │
      ▼


Apply Execution Policy


      │
      ▼


Execute API Request


      │
      ▼


Return Response

Every request follows this lifecycle regardless of which provider is being called.

Run this example

Use the full Anthropic agent example from the Anthropic Quickstart to exercise the runtime end-to-end. The quickstart includes one-time setup (swy init, swy get github, swy add method github.user.starred.update, swy auth connect github) plus the complete JavaScript/TypeScript example that loops on tool_use calls.

Save the example as main.js or main.ts, make sure your .env contains ANTHROPIC_API_KEY, then run it:

Terminal window
node main.js

Policy Enforcement

Before any network request is sent, the runtime evaluates your project’s policies.

If a request violates a configured policy, execution stops immediately and the provider is never contacted.

This allows applications to enforce organization-specific rules without changing application code.

Typical examples include:

  • blocking destructive operations
  • preventing large payment requests
  • restricting production deployments
  • enforcing required request fields

Reliable Execution

The runtime automatically handles temporary failures that commonly occur when communicating with external APIs.

This includes:

  • retrying transient HTTP failures
  • exponential backoff
  • honoring Retry-After headers
  • request timeouts
  • OAuth token refresh
  • configurable concurrency limits

Retry behavior is configured per integration through manifest.json.

Idempotency

For supported providers, the runtime automatically attaches idempotency keys to mutating API requests (see Idempotency).

If a request must be retried because of a temporary failure, the provider recognizes the same idempotency key and safely returns the original result instead of executing the operation twice.

This makes retries safe for operations such as payments, deployments, or resource creation.

Error Handling

Execution failures are returned as standard JavaScript errors.

try {
  await runtime.execute({
    tool: "github.issue.create",
    input: {
      owner: "swytchcodehq",
      repo: "docs",
      title: "Bug report"
    }
  });
} catch (error) {
  console.error(error);
}

Errors may represent:

  • validation failures
  • policy violations
  • authentication failures
  • provider errors
  • timeout errors
  • network failures

Because responses are normalized by the runtime, your application receives a consistent error model across providers.

TypeScript Support

The Runtime SDK is fully typed and designed for TypeScript applications, with types and interfaces shipped directly in the package.

Editors provide autocomplete, inline documentation, and type checking, making it easier to discover available APIs while reducing runtime errors.

Supported Environments

The JavaScript Runtime SDK can be used anywhere modern JavaScript runs.

Supported environments include:

  • Node.js
  • Bun
  • Serverless Functions
  • Docker
  • AI agent runtimes

Best Practices

For production applications, we recommend:

  • creating a single runtime instance during application startup
  • keeping provider credentials outside your source code
  • executing trusted tools instead of making raw HTTP requests
  • testing integrations in sandbox mode before production
  • storing project configuration and policies in version control

After this guide, try:

Next Steps

Python SDK

Compare the same runtime model in Python.

CLI overview

Understand the command-line runtime and how it integrates with SDK usage.

Managed Authentication

Learn how provider credentials are resolved securely.

Execution Pipeline

See the full lifecycle of tool execution.