---
title: Run modes
summary: Three ways to run FastYoke — the light npx runtime, the full self-hosted engine (Docker or On-Prem), and Managed Cloud — and how to pick.
order: 3
---

# Run modes

FastYoke runs in three modes. They share one FSM engine, one schema format, and one REST + WebSocket wire contract, so an app built on the shared primitives moves between them by changing a base URL — not code. They differ in the heavier engine features and the deployment topology.

## The three modes

### 1. npx runtime (light)

A zero-install Node sidecar — no Docker, no account. It covers the FSM / forms / entities core against a SQLite file on disk.

```bash
# Node 18+
npx fastyoke init    # scaffold .fastyoke/ (config, seed.json, auth key, token)
npx fastyoke dev     # serve on http://127.0.0.1:8787
```

`fastyoke` is the sidecar itself — the local server, not a client library. Best for evaluating the engine, building a workflow app, or a demo, in seconds. It is a **subset**: no PDF, scripting, extensions, e-signature, or marketplace apps (see the matrix below).

### 2. Self-hosted full engine (Docker · On-Prem)

The complete engine as a single container — everything the light runtime has, plus PDF rendering, the WASM scripting tier, extensions, e-signature, and marketplace apps.

```bash
docker run -p 8080:8080 -e DEPLOY_ENV=sandbox \
  ghcr.io/fastyoke/backend:sandbox
```

`DEPLOY_ENV=sandbox` runs against a plain SQLite database with third-party integrations (payments, email, external SSO) pointed at local stubs — nothing leaves the machine. This is the right dev and CI target for ISVs, and the same container [On-Prem](/on-prem) deploys for production self-hosting (multi-tenant, replication, managed backups).

### 3. Managed Cloud

The full engine, fully hosted and multi-tenant — migrations, managed backups, and multi-node WebSocket fanout included. [Sign up](/getting-started) and install marketplace apps.

## Capability matrix

| Capability | npx runtime | Self-hosted full engine | Managed Cloud |
| --- | :---: | :---: | :---: |
| Runs with | Node (`npx`) | Docker / your servers | a FastYoke account |
| Default endpoint | `:8787` | `:8080` | `api.fastyoke.com` |
| FSM engine (guards, self-loops, admin cancel) | ✓ | ✓ | ✓ |
| Entities + append-only event log | ✓ | ✓ | ✓ |
| Public forms | ✓ | ✓ | ✓ |
| Realtime (WebSocket) | ✓ single-node | ✓ single-node | ✓ multi-node fanout |
| PDF rendering (typst) | — | ✓ | ✓ |
| WASM scripting tier (QuickJS · wasmtime) | — | ✓ | ✓ |
| Extensions | — | ✓ | ✓ |
| E-signature (21 CFR Part 11) | — | ✓ | ✓ |
| Marketplace apps | — | ✓ | ✓ |
| Payments / billing | — | vendor-gated in sandbox | ✓ |
| Tenancy | single tenant / sidecar | multi-tenant (On-Prem) | multi-tenant |
| Replication · HA · backups | — | On-Prem | ✓ managed |

## Pointing the SDK at a mode

The `@fastyoke/sdk-core` client (and the `@fastyoke/sdk` React hooks) target whichever mode you're running — swap the base URL:

```ts
import { createFastYokeClient } from '@fastyoke/sdk-core'

const client = createFastYokeClient({
  tenantId: 'local',
  fetcher: fetch,
  baseUrl: process.env.FASTYOKE_API_BASE,
  // npx runtime:             http://127.0.0.1:8787
  // self-hosted full engine: http://127.0.0.1:8080
  // Managed Cloud:           https://api.fastyoke.com
})
```

Server-side, `@fastyoke/next` resolves credentials from the environment the same way.

## Choosing

- **Building a workflow app fast, or a demo?** Start with the npx runtime. If you later need a full-engine feature, move the base URL to the Docker container — the schema and app code are unchanged.
- **Shipping inside a customer's firewall (ISV)?** Develop against the self-hosted full engine; it's the same container On-Prem deploys.
- **Running hosted production?** Managed Cloud.

One caveat on portability: an app that uses PDF, scripting, extensions, e-signature, or marketplace apps requires the full engine — those primitives aren't in the light runtime. Apps built on the shared FSM / forms / entities core port across all three unchanged.

See the [Runtime overview](/runtime) for the marketing-level comparison, or [On-Prem](/on-prem) for production self-hosting.