Skip to main content

Architecture overview

Culvii is a cloud product with a developer-facing SDK and CLI. Your code expresses what a workflow should do; Culvii's cloud runs it. There is no local engine and no Docker container to manage.

This page explains what each part is doing, what's hosted where, and how the pieces talk to each other.

The four surfaces​

(Brief recap from How the pieces fit — fuller picture here.)

Culvii Kit (@culvii/kit) is a TypeScript SDK. You import primitives and write code that describes an agent or a workflow. Crucially, the SDK does not execute your workflow when your Node process runs. It builds an in-memory representation that the CLI can serialize and push.

Culvii CLI (culvii) is the bridge between your editor and the cloud. It does two distinct jobs:

  • During development, culvii dev watches your files, compiles your code into a workflow definition (JSON), and streams it to your dev environment in real time. As you save, your dev environment in the Console updates.
  • For higher environments, culvii deploy does the same compilation but pushes a versioned, immutable snapshot to sandbox or production.

Platform APIs are the HTTP surface that Kit and CLI both talk to. They handle authentication, definition storage, run scheduling, log streaming, and the WebSocket channel that powers culvii dev. They are not directly public yet.

Culvii Console (console.culvii.com) is the web app. Developers watch dev runs in real time. Operators approve human-in-the-loop gates, manage workspaces and keys, review the audit log, and govern agents at scale.

Configuration vs. execution — the mental shift​

The single most important thing to internalize is this: the SDK is a configuration DSL, not a runtime. The TypeScript code you write is not "the program that runs your workflow." It's a typed description of what the workflow is. The platform runs it.

This is the same shape as AWS CDK or Pulumi: you write infrastructure in a real programming language, the CLI synthesizes a deployable artifact, and the cloud executes against that artifact. In Culvii's case the artifact is a workflow definition (JSON), and the cloud is the Culvii engine.

Two consequences:

  1. Your tool code runs in Culvii's cloud. When you write tool({ execute: async (input) => { … } }), that execute function becomes part of the deployed workflow. It runs on Culvii servers when the workflow runs. It does not run on your laptop or in your data center.
  2. There is no local execution mode in v1. You cannot run a workflow purely on your machine. Even during development, culvii dev is a live sync to your cloud dev environment, not a local engine.

This shape is deliberate. It's what makes operator-side governance possible: Culvii sees every run, every tool call, every model call, every gate. If executions could happen anywhere, the audit trail would have holes in it.

How a workflow run flows​

A typical run, from trigger to completion:

sequenceDiagram
    participant Trigger
    participant Engine as Culvii Engine
    participant Agent
    participant Tool
    participant External as External system<br/>(your API, MCP, model)

    Trigger->>Engine: run.start (workflow vN, input)
    Engine->>Engine: persist run state
    Engine->>Agent: invoke step
    Agent->>Engine: request tool call
    Engine->>Tool: execute(input)
    Tool->>External: HTTPS / MCP request
    External-->>Tool: response
    Tool-->>Engine: output
    Engine->>Agent: tool result
    Agent-->>Engine: step output
    Engine->>Engine: persist step state
    Engine-->>Trigger: run.complete (or run.paused at a gate)

Three things to notice:

  • The engine is the only thing that holds run state. If a tool call takes thirty seconds or thirty days, the engine remembers where it was. If a gate is pending approval for a week, the engine pauses cleanly and resumes when the gate clears.
  • All outbound calls (to model providers, your APIs, MCP servers) leave from Culvii's network, not your laptop.
  • The trigger can be a CLI command (culvii run), a scheduled cron, a webhook, or a Console action. The flow is the same.

Reaching data inside your network​

Tool code runs on Culvii. So how do you write a tool that needs data from inside your private network?

You expose an interface. Culvii reaches out to it.

ApproachUse when
HTTPS endpointYou already have or can deploy an internal API behind authentication. The tool's execute makes an authenticated HTTPS call to it.
MCP serverThe system you want to reach already speaks the Model Context Protocol — Jira, ClickUp, Notion, Linear, GitHub, your own MCP server. You connect it once via the MCP primitive.
Managed connector (roadmap)A pre-built connector to a SaaS system you use, with auth and schema handled by Culvii. Not in v1.
Smart Client Worker (roadmap)Tool code executes inside your network on a process you run, with Culvii calling back over a persistent channel. Not in v1.

For v1: if your data lives behind a firewall with no inbound path, you'll need to either expose an HTTPS interface or wait for the Smart Client Worker.

What's hosted by Culvii​

Everything in the runtime path:

  • The engine that orchestrates workflows.
  • The model gateway (calls to LLM providers happen from our network with our keys, or yours if you bring them).
  • Run state, audit log, traces.
  • The Console.
  • The MCP gateway.

Nothing in the build path:

  • Your code repository (GitHub, GitLab, your own — Culvii doesn't host it).
  • Your local development tools (your editor, Node, your package manager).
  • Your CI/CD pipeline (GitHub Actions, etc. — Culvii is something CI calls into).

What's not in v1​

Worth restating in one place:

  • Local execution. No standalone runtime that runs workflows on your machine.
  • Smart Client Worker. No way to host tool execution in your network.
  • Self-hosted Culvii. No on-prem or single-tenant cloud deployment.
  • Custom domain. You access the Console at console.culvii.com, not at a domain you own.

All of these are on the roadmap.