Skip to content
Sapiom Docs
Go To Dashboard

Build Your First Workflow

A workflow (orchestration) is a small TypeScript project you author with your coding agent: defineOrchestration({ entry, steps }), where each step’s run(input, ctx) does work and can call any paid Sapiom capability on ctx.sapiom. You write it as code, test it locally for free, then deploy it to run on Sapiom’s cloud.

This guide goes from nothing to a workflow running in the cloud — all from your terminal or IDE, no dashboard required.

  1. Add the Sapiom MCP

    Section titled “Add the Sapiom MCP”

    Add the @sapiom/mcp server to your coding agent’s MCP config:

    {
      "mcpServers": {
        "sapiom": { "command": "npx", "args": ["-y", "@sapiom/mcp"] }
      }
    }

    In Claude Code you can also add it from the terminal:

    Terminal window
    claude mcp add sapiom -- npx -y @sapiom/mcp

    Restart your client so it loads the Sapiom tools — sapiom_authenticate, sapiom_status, and the sapiom_dev_orchestrations_* lifecycle.

  2. Authenticate

    Section titled “Authenticate”

    Run sapiom_authenticate. It opens a browser login — sign up or log in, then approve. That one step provisions and caches an API key for you (in ~/.sapiom/credentials.json); there’s nothing to copy or paste.

    Confirm with sapiom_status:

    Authenticated as Your Organization (tenant: 37c9…)

  3. Scaffold a project

    Section titled “Scaffold a project”

    Ask your agent to scaffold a workflow, or call sapiom_dev_orchestrations_scaffold with a target directory. (It also takes a template: "default" — the minimal starter used here — or "coding-pause" for the non-blocking coding-agent pattern; see the authoring guide.) It writes a ready-to-run TypeScript project:

    my-workflow/                 # git-initialized for you
    ├── index.ts                 # your orchestration
    ├── package.json
    ├── tsconfig.json
    ├── AGENTS.md                # authoring guide — your agent should read this first
    ├── CLAUDE.md                # points your coding agent at AGENTS.md
    ├── README.md
    ├── .gitignore
    └── .sapiom-dev/stubs.json   # capability stubs for run_local

    Install dependencies:

    Terminal window
    npm install

  4. Write a step

    Section titled “Write a step”

    Your scaffold’s index.ts is already a runnable two-step starter (start → finish). Open it and edit: a step is defineStep({ name, next, run }), its run(input, ctx) is ordinary code, and every Sapiom capability is on ctx.sapiom — pre-authed and tenant-scoped. Here’s the shape of a step that calls a capability:

    import { defineOrchestration, defineStep, terminate } from "@sapiom/orchestration";
    

    const main = defineStep({
      name: "main",
      next: [],
      terminal: true,
      async run(input, ctx) {
        ctx.logger.info("starting", { input });
        // Capabilities live on ctx.sapiom — e.g. sandboxes, repositories, the coding agent, file storage.
        const sandbox = await ctx.sapiom.sandboxes.create({ name: "demo" });
        ctx.logger.info("created sandbox", { sandbox });
        return terminate({ done: true });
      },
    });
    

    export const orchestration = defineOrchestration({
      name: "my-workflow",
      entry: "main",
      steps: { main },
    });

  5. Test locally — free

    Section titled “Test locally — free”

    Validate the step graph, then run the whole workflow on your machine with every capability stubbed — no cloud calls, no cost:

    • npm run typecheck — confirms the code compiles and every ctx.sapiom.* capability/method you used actually exists.
    • sapiom_dev_orchestrations_check — bundles index.ts and validates the step graph. Offline and instant.
    • sapiom_dev_orchestrations_run_local — runs your real step code against stub capabilities and returns a per-step trace:
    {
      "outcome": "completed",
      "steps": [
        { "step": "main", "status": "succeeded", "output": { "done": true } }
      ]
    }

  6. Deploy and run

    Section titled “Deploy and run”

    When local runs look right, ship it:

    • sapiom_dev_orchestrations_link — registers the workflow under your tenant.
    • sapiom_dev_orchestrations_deploy — builds and deploys it to the cloud.
    • sapiom_dev_orchestrations_run — starts a real execution.
    • sapiom_dev_orchestrations_inspect — watch status, steps, and spend.

    This is a real cloud run, so it bills your tenant for the capabilities the workflow actually uses.

What you just did

Section titled “What you just did”

You authored a workflow as code, tested it for free, and ran it in the cloud — entirely from your coding agent, with no setup beyond installing the MCP. From here:

Browse capabilities Everything your steps can call on ctx.sapiom — scraping, compute, data, search, AI, media, and more.

Next in this track: a deeper authoring guide (the same material your scaffold’s AGENTS.md covers — failure handling, pause/resume for long-running steps, sub-workflows) and operating your workflows (watching runs, spend, and failures across your fleet).