Documentation.

Quickstart

From signup to a running workflow in under ten minutes.

Your first workflow

This guide walks through a Webhook → MCP → Slack pipeline. The whole thing takes five minutes.

1 · Choose a trigger

Workflows start with a trigger node. Drop a Webhook trigger onto the canvas. Click it and copy the generated URL — that's where you'll send events from your upstream system.

2 · Call an MCP tool

Drag an MCP node and connect it to the webhook output. Pick the tool you want to call from the dropdown — input fields are auto-generated from the tool's JSON Schema. Reference webhook fields with {{ trigger.body.email }}.

3 · Send a Slack message

Drop a Slack Action node downstream. Configure the channel and message body. You can interpolate output from any upstream node: {{ steps.enrich.output.company }}.

4 · Test, then publish

Hit Run with a sample payload. The right pane shows every step's input and output. Once green, press Publish — your webhook URL is now live.

Your first agent

An agent is a workflow whose LLM has access to a curated tool set and a persona. Here we'll build a research agent that queries Confluence and Salesforce.

1 · Define the persona

Open Agents → New. Give it a name and a system prompt. Be specific about scope — agents are most reliable when their job is narrow.

// system prompt
You are a sales-research agent. Given a company name, return:
- the latest opportunity stage from Salesforce
- any related internal docs from Confluence
Cite your sources. If you can't find data, say so.

2 · Attach tools

From the tool picker, select tools from any MCP server connected to your workspace. For this agent: sf.opp.search, sf.account.get, confluence.search.

3 · Set guardrails

Toggle on Require approval for writes if you want a human checkpoint before any tool that mutates state runs. Set a max-iteration budget (default: 8).

4 · Run, evaluate, publish

Test with a few real questions. Inspect the agent's tool-call trace. When happy, publish — the agent is now callable from any workflow as agent.research.run.

Nodes & edges

A workflow is a directed graph. Nodes do work; edges carry typed data between them. Nexus has 16 node types across 4 categories.

Triggers

• Webhook — public HTTPS URL, verifies signatures.
• Schedule — cron syntax, timezone-aware.
• Event — subscribe to internal or third-party events.
• Manual — runs on demand, useful for testing.

Actions

• MCP — call any tool exposed by a connected server.
• HTTP — raw request, when MCP isn't available.
• Email / Slack / SMS — first-class messaging.
• Code — TypeScript or Python sandbox for glue logic.

Flow control

• Branch — conditional routing on JSONPath expressions.
• Fork / Join — parallel execution and synchronization.
• Loop — iterate over an array, with concurrency control.
• Wait — pause until a webhook resumes the run.

Humans & AI

• Form — generate a typed form, route by email or assignment.
• Approval — single-decision human checkpoint.
• LLM — model call with prompt templating.
• Agent — embed a tool-using agent inline.

Publishing & versioning

Publishing freezes a workflow's topology (which nodes exist, how they're wired) but leaves configuration (rule values, prompts, thresholds) editable in production.

What's immutable after publish

• Node graph and edges
• Input and output schemas
• The published version's MCP signature

What you can change without redeploying

• Branch thresholds, retry budgets, timeouts
• LLM prompts and model selection
• Approval routing rules
• Any value marked @editable in node config

Versioning

Every publish creates a new version. In-flight runs continue on their starting version. New triggers route to the latest. Roll back via the version dropdown — instant, no redeploy.

A2A composition

Agent-to-Agent. A workflow can call another workflow as a single step — typed input, typed output, full observability.

Why A2A matters

Decompose. The "customer onboarding" workflow doesn't need to know how KYC verification works — it just calls the KYC workflow and gets a result. Each piece evolves independently.

How to call another workflow

Drop a Workflow node. The picker shows every published workflow in your workspace. Pick one — its input form is auto-generated from its schema.

Recursion safety

Nexus tracks the call stack. A workflow that calls itself (directly or transitively) past a configurable depth (default: 16) errors at publish time, not runtime.

Knowledge ingestion

Knowledge is how you ground LLM nodes and agents in your own data. Nexus indexes content from connected sources and exposes it as a retrieval tool.

Sources

• Confluence, Notion, Google Drive, SharePoint, GitHub wikis
• S3 / GCS / Azure Blob (PDFs, MD, DOCX)
• Any MCP resource server

Pipeline

1. Crawl — list documents from the source.
2. Extract — text + structure, preserving headings.
3. Chunk — semantic chunking (default 512 tokens, 50-token overlap).
4. Embed — your chosen embedding model.
5. Store — pgvector, with original ACLs preserved.

ACL preservation

Every chunk inherits the source document's ACL. When an LLM node retrieves chunks, the lookup is filtered by the calling user's identity — so a workflow run by Alice never sees Bob's private docs.

Re-ingest

Schedule per-source. Default: daily incremental, weekly full. Per-document hashes mean unchanged docs cost nothing.

Adding a server

To use an MCP server in a workflow, register it once at the workspace level.

Writing a server

If your service doesn't have an MCP server yet, write one. The TypeScript starter takes about 20 lines for a basic tool.

import { Server } from "@modelcontextprotocol/sdk";

const srv = new Server({ name: "my-svc", version: "1.0.0" });

srv.tool(
  "createTicket",
  { title: "string", body: "string", priority: "low|med|high" },
  async ({ title, body, priority }) => {
    const id = await db.tickets.insert({ title, body, priority });
    return { id, status: "open" };
  }
);

srv.listen({ transport: "http", port: 8421 });

Schema patterns and a full Python starter are in the cookbook.

Cookbook

Twelve recipes for common MCP server patterns.

• Pagination — cursor field on output, transparent to the workflow.
• Streaming — for long-running tools, emit progress events.
• Rate limits — return a typed RateLimitedError; the engine retries with backoff.
• Multipart — file uploads via signed URLs.
• Hot reload — bump version + signal SIGHUP; the engine refetches tools/list.
• Idempotency — accept and respect an Idempotency-Key header.
• Auth scopes — return per-tool scopes; the engine surfaces scope errors at config time.
• Resources vs. tools — when to use which.
• Long-running jobs — return a job id, expose a status tool.
• Multi-tenant servers — tenant scoping via headers.
• Versioning — semver in the server name; engine pins per workflow.
• Local dev — stdio transport, no network needed.

REST API

Trigger workflows, query runs, manage workspaces. Stable, versioned at /v1. Full reference at developers/sdk.

Auth

API keys via Authorization: Bearer …. Scoped (workflow, run, admin). Rotate from the dashboard or CLI.

Trigger a workflow

POST /v1/workflows/{slug}/runs
Authorization: Bearer nx_...
Content-Type: application/json

{ "email": "a@example.com", "plan": "enterprise" }

// Response
{ "runId": "run_01h…", "status": "queued" }

Stream run events

GET /v1/runs/{id}/events?stream=sse
Authorization: Bearer nx_...

// SSE: StepStarted, StepCompleted, StepFailed, RunDone

CLI

The nexus CLI mirrors the REST API and adds local dev affordances.

# install
brew install santeon/tap/nexus

# auth
nexus login

# run a graph locally
nexus run ./graph.json --input='{"email":"a@example.com"}'

# tail a live run
nexus runs tail run_01h...

# trigger a deployed workflow
nexus trigger customer-onboarding --json='{"email":"a@example.com"}'

@nexus/engine

The portable TypeScript executor. Same engine that powers the cloud. Run it embedded, in CI, or self-hosted.

import { runWorkflow } from "@nexus/engine";
import graph from "./onboarding.json";

const events = runWorkflow(graph, {
  trigger: { kind: "webhook", payload: { email: "a@example.com" } },
  state:   postgresStore(pool),
  bus:     sqsBus(queueUrl),
  mcp:     mcpClient({ servers }),
});

for await (const ev of events) console.log(ev);

Full surface area on the engine page.

Self-hosted deploy

Three deployment shapes — managed, BYOC (your AWS), or air-gapped on-prem. Full requirements matrix on the self-host page.

BYOC quick path

1. Create a cross-account IAM role with our published trust policy.
2. Deploy the CloudFormation template (or Terraform module).
3. Point your DNS at the ALB.
4. Configure SSO via OIDC or SAML.
5. Add MCP servers from your VPC.

On-prem (Helm)

helm repo add nexus https://charts.santeon.com
helm install nexus nexus/nexus \
  --set postgres.host=... \
  --set redis.host=... \
  --set llm.provider=bedrock-vpc \
  --set sso.issuer=https://idp.example.com

Runbook

The operational playbook for self-hosted deployments.

Health checks

• /healthz — process liveness.
• /readyz — checks DB, queue, KMS reachability.
• /metrics — Prometheus scrape endpoint.

Backups

Postgres holds the entire state graph — runs, events, configs, secrets-references. Snapshot it on whatever cadence your RPO requires. Object storage holds large payloads (set a lifecycle policy).

Upgrades

Pull the new image. Run migrations (nexus migrate). Roll deployments. Engine versions are N-1 compatible — in-flight runs survive a rolling upgrade.

Incidents

• Stuck runs — nexus runs unstick <id> resumes from the last checkpoint.
• MCP server flapping — circuit breaker engages after 5 consecutive failures; check connector health page.
• Queue backlog — scale workers via the deployment's HPA or helm upgrade --set workers.replicas=N.