octo

module
v0.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 14, 2026 License: AGPL-3.0

README

Octo

Octo is a cloud-native integration runtime. The octo repository holds its stacks, including a Go module for the runtime engine and CLI.

Documentation: the docs site — overview, getting started, connector and CEL reference, guides, and the AI/MCP story — is built from apps/docs/ (Fumadocs, statically exported) and published with GitHub Pages at https://juancavallotti.github.io/octo/. Preview locally with task docs:dev.

Install

Download a prebuilt CLI — no Go toolchain needed. Unpack it and put the binary on your PATH. octo is the runtime; dolphin is its companion test runner, which drives octo to unit-test an integration.

octo — the runtime
Platform Download
macOS (Apple Silicon) octo_darwin_arm64.tar.gz
macOS (Intel) octo_darwin_amd64.tar.gz
Linux (x86-64) octo_linux_amd64.tar.gz
Linux (arm64) octo_linux_arm64.tar.gz
Windows (x86-64) octo_windows_amd64.zip
Windows (arm64) octo_windows_arm64.zip
dolphin — the test runner
Platform Download
macOS (Apple Silicon) dolphin_darwin_arm64.tar.gz
macOS (Intel) dolphin_darwin_amd64.tar.gz
Linux (x86-64) dolphin_linux_amd64.tar.gz
Linux (arm64) dolphin_linux_arm64.tar.gz
Windows (x86-64) dolphin_windows_amd64.zip
Windows (arm64) dolphin_windows_arm64.zip
Both checksums.txt

Have a Go toolchain? Install either CLI straight from source:

go install github.com/juancavallotti/octo/runtime/octo@latest
go install github.com/juancavallotti/octo/runtime/dolphin@latest

Prefer Docker? Two public images on Docker Hub, no install at all:

# The visual editor + runtime ("try Octo"): flows are read/written in $PWD.
docker run -p 3000:3000 -v "$PWD:/work" juancavallotti/octo

# The runtime alone: runs every .yaml in the mounted config directory.
docker run -p 8080:8080 -v "$PWD:/etc/octo/integrations" juancavallotti/octo-runtime

Building from source is one command (task runtime:build); see the installation docs.

Layout

  • runtime/: the Go module's packages — the runtime engine (core, types, connectors, services) and the two CLIs: octo (runtime/octo) and dolphin (runtime/dolphin), the test runner that drives it. The module itself is rooted at the repo root so both are go install-able.
  • apps/standalone/: the single-user Next.js visual editor (Docker image juancavallotti/octo). See apps/standalone/README.md.
  • apps/platform/: the orchestrator-backed multi-user Octo web app. See apps/platform/README.md.
  • apps/docs/: the documentation site (Fumadocs). Content in apps/docs/content/docs/.
  • packages/: shared pnpm workspace libraries (@octo/editor, @octo/mcp, @octo/run-host, ...).
  • orchestrator/: Go API that deploys integrations as Kubernetes workloads.
  • helm/: Helm chart for the GCP deployment; deploy/: k8s manifests (local k3d) and Terraform (GCP).
  • docs/: contributor policies (coding standards, lint, review, release) and internal deep-dives (deployment, processing pipeline).
  • samples/: runnable flow examples used throughout the docs.

Deployment

To run Octo on GCP (single-node k3s, Traefik, free Let's Encrypt TLS, and per-integration subdomains), see the published deployment docs or the internal deployment guide. For local development on k3d, use the task cluster:* targets.

Working rules

Read AGENTS.md before changing code. Read docs/coding-standards.md for code style and design rules. Read docs/linting-policy.md for lint expectations. Read docs/release-process.md before release-related work.

The Go runtime lives under runtime/; its module manifest is the root go.mod.

Runtime architecture

Read docs/processing-pipeline.md for the runtime building blocks: connectors, message sources, flows, blocks/processors, composite blocks (handle-errors/fork), the worker-pool concurrency model, the flow-event bus, and the start/stop lifecycle. A minimal flow looks like:

flows:
  - name: ingest-orders
    workers: 8
    source:
      connector: api
      type: http
      settings: { path: /orders }
    process:
      - type: validate
        rules:
          - { expr: "has(body.id)", message: "order id is required" }
          - { expr: "body.amount > 0", message: "amount must be positive" }

Tasks

  • task fmt
  • task test
  • task build
  • task tidy
  • task lint-strict
  • task policy-check
  • task release-check

Docs site:

  • task docs:dev
  • task docs:build
  • task docs:check

Standalone editor (Next.js):

  • task dev

Directories

Path Synopsis
runtime
connectors/cron
Package cron provides a connector whose sources emit a message on a cron schedule.
 Package cron provides a connector whose sources emit a message on a cron schedule.
connectors/database
Package database provides a connector that owns a database/sql connection pool.
 Package database provides a connector that owns a database/sql connection pool.
connectors/events
Package events exposes the platform's broadcast pub/sub (core.Topics) to flows as first-class DSL constructs: an "event" message source that runs every message published to a subject through a flow, and the "publish-event" block that broadcasts the current message to a subject.
 Package events exposes the platform's broadcast pub/sub (core.Topics) to flows as first-class DSL constructs: an "event" message source that runs every message published to a subject through a flow, and the "publish-event" block that broadcasts the current message to a subject.
connectors/http
Package http provides a connector that turns synchronous HTTP requests into flow executions and returns the result to the caller.
 Package http provides a connector that turns synchronous HTTP requests into flow executions and returns the result to the caller.
connectors/httpclient
Package httpclient provides a connector that owns a configured net/http client for calling external HTTP APIs, plus the "rest" block that runs a single request through it and folds the response into the message body.
 Package httpclient provides a connector that owns a configured net/http client for calling external HTTP APIs, plus the "rest" block that runs a single request through it and folds the response into the message body.
connectors/llm/aiblocks
Package aiblocks provides leaf processor blocks powered by an LLM connector.
 Package aiblocks provides leaf processor blocks powered by an LLM connector.
connectors/llm/anthropic
Package anthropic provides the "llm-anthropic" connector: a configured Anthropic Messages client that satisfies core.LLMClient so the AI flow elements (ai-router, ai-agent, ai-mapping, ai-retry) can drive it without knowing which provider is behind the name they reference.
 Package anthropic provides the "llm-anthropic" connector: a configured Anthropic Messages client that satisfies core.LLMClient so the AI flow elements (ai-router, ai-agent, ai-mapping, ai-retry) can drive it without knowing which provider is behind the name they reference.
connectors/llm/gemini
Package gemini provides the "llm-gemini" connector: a configured Google Gemini client that satisfies core.LLMClient so the AI flow elements can drive it interchangeably with the other providers.
 Package gemini provides the "llm-gemini" connector: a configured Google Gemini client that satisfies core.LLMClient so the AI flow elements can drive it interchangeably with the other providers.
connectors/llm/openai
Package openai provides the "llm-openai" connector: a configured OpenAI Chat Completions client that satisfies core.LLMClient so the AI flow elements can drive it interchangeably with the other providers.
 Package openai provides the "llm-openai" connector: a configured OpenAI Chat Completions client that satisfies core.LLMClient so the AI flow elements can drive it interchangeably with the other providers.
connectors/logger
This file provides the "log" leaf block: a pass-through wire tap that logs a line for each message and forwards the message unchanged.
 This file provides the "log" leaf block: a pass-through wire tap that logs a line for each message and forwards the message unchanged.
connectors/notion
This file provides the "notion-retrieve-blocks" block: it retrieves a page's (or any block's) child blocks (GET /blocks/{id}/children), following pagination, and stores them as a {results: [...]} object.
 This file provides the "notion-retrieve-blocks" block: it retrieves a page's (or any block's) child blocks (GET /blocks/{id}/children), following pagination, and stores them as a {results: [...]} object.
connectors/queue
This file provides the "queue-dispatch" block: it sends the current message to a queue subject to load balance work across replicas.
 This file provides the "queue-dispatch" block: it sends the current message to a queue subject to load balance work across replicas.
connectors/slack
This file provides the "slack-event" block: it unwraps a verified Slack event_callback into a friendly, flat shape and filters it.
 This file provides the "slack-event" block: it unwraps a verified Slack event_callback into a friendly, flat shape and filters it.
core
Schema metadata registry.
 Schema metadata registry.
core/expr
Package expr is the runtime's expression engine.
 Package expr is the runtime's expression engine.
core/internal/dsl
core/internal/engine
Agent memory: per-thread conversation transcripts for the ai-agent block, persisted in the runtime KV store.
 Agent memory: per-thread conversation transcripts for the ai-agent block, persisted in the runtime KV store.
core/internal/pool
Package pool provides the shared worker pool a flow owns and hands to any block that needs parallelism (e.g.
 Package pool provides the shared worker pool a flow owns and hands to any block that needs parallelism (e.g.
core/runtime
Package runtime is the application layer that wires configured connectors and flows into a running service.
 Package runtime is the application layer that wires configured connectors and flows into a running service.
core/schema
Package schema generates the editor capability catalogue (packages/editor/src/app/schema/capabilities.json) from the block and connector metadata registered in package core.
 Package schema generates the editor capability catalogue (packages/editor/src/app/schema/capabilities.json) from the block and connector metadata registered in package core.
dolphin command
dolphin is octo's companion test runner: it drives the real octo CLI against an integration and checks what comes back, so a flow can have a test suite the way any other unit of code does.
 dolphin is octo's companion test runner: it drives the real octo CLI against an integration and checks what comes back, so a flow can have a test suite the way any other unit of code does.
dolphin/internal/assert
Package assert decides whether a flow did what a case said it would, and says what was wrong when it did not.
 Package assert decides whether a flow did what a case said it would, and says what was wrong when it did not.
dolphin/internal/report
Package report renders what a run did — to a terminal, and to the JUnit XML a CI job reads.
 Package report renders what a run did — to a terminal, and to the JUnit XML a CI job reads.
dolphin/internal/runner
Package runner runs a case against octo and says what came back.
 Package runner runs a case against octo and says what came back.
dolphin/internal/suite
Package suite is what a _test.yaml is: the format, its validation, and the rules for pairing a suite with the flows it exercises.
 Package suite is what a _test.yaml is: the format, its validation, and the rules for pairing a suite with the flows it exercises.
internal/schemafmt
Package schemafmt renders a JSON Schema document the way both CLIs print one.
 Package schemafmt renders a JSON Schema document the way both CLIs print one.
octo command
services
Package services selects and constructs the runtime services provider chosen at startup by the RUNTIME_SERVICES_MODULE environment variable.
 Package services selects and constructs the runtime services provider chosen at startup by the RUNTIME_SERVICES_MODULE environment variable.
services/k8s
Package k8s implements the runtime services provider for a Kubernetes cluster: leader election backed by coordination/v1 Leases (so work runs on one replica) and a KV store backed by the orchestrator API (deployment-scoped, with encrypted secrets).
 Package k8s implements the runtime services provider for a Kubernetes cluster: leader election backed by coordination/v1 Leases (so work runs on one replica) and a KV store backed by the orchestrator API (deployment-scoped, with encrypted secrets).
services/standalone
Package standalone implements the single-process runtime services module: leader election always grants leadership (there is nothing to elect) and the KV store lives in process memory.
 Package standalone implements the single-process runtime services module: leader election always grants leadership (there is nothing to elect) and the KV store lives in process memory.
types

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.