DOCSEARCHbyAlgolia
Submit Docs

iii: Backend Composition and Agentic Workflow Platform

repository·main·Indexed 29 days ago

https://github.com/iii-hq/iii

A platform for composing, extending, and observing backend services using a unified Worker-Function-Trigger model. Designed for Agentic Workflows, it treats infrastructure components like sandboxes, queues, and state stores as composable workers. Includes the iii Developer Console, iii-sandbox for ephemeral microVM execution, and managed sandbox images for Node.js and Python.

Tokens
1.1M
Snippets
2.5K
Records
5.3K
Agent score
92%

What's inside iii

  1. Overview of the iii-queue worker

    main

    The iii-queue worker provides asynchronous job processing with retries, configurable concurrency, FIFO ordering, and dead-letter (DLQ) support. It supports two modes of operation:

    1. Durable Pub/Sub (Topic-based): Every distinct function subscribed to a topic receives a copy of each message (fan-out). Use the durable:subscriber trigger to register consumers.
    2. Named Queues: Targeted by enqueuing a function call directly using TriggerAction.Enqueue. No trigger registration is required; the target function acts as the consumer.

    Supported Adapters

    • builtin: In-process (in_memory or file_based). Best for local development or single-instance setups. Supports retries, DLQ, and FIFO.
    • rabbitmq: Best for multi-instance production environments. Supports durable delivery, retries, and DLQ.
    • redis: Multi-instance topic pub/sub only. It can publish to named queues, but does not implement named-queue consumption, retries, or DLQ.

  2. Overview of Agentic Workers architecture

    main

    The Agentic Workers architecture is a set of small, composable iii workers that form a reactive, durable agent backend. Instead of a monolithic agent harness, the system is split into four standalone workers that communicate via the iii bus (functions, triggers, and channels).

    Core Workers

    • context-manager: Manages context windows by pruning, summarizing, or fitting raw history into a model-ready format.
    • session-manager: Provides a durable, reactive, and branching store for typed conversation entries.
    • llm-router: Acts as a single entry point for all LLM providers, offering a stable interface for completions.
    • harness: The orchestration layer that wires the other three workers together into a durable turn loop. It can also spawn sub-agents as child sessions.

    Key Design Principles

    • Standalone First: Each worker is independently installable via iii worker add <name> and has no hard dependencies (though harness uses the others as soft dependencies).
    • Thin Orchestration: The harness is kept minimal; logic like approval gating or spend budgets should be implemented as separate sibling workers.
    • Reactive Surface: Consumers interact with the system by binding to triggers (e.g., session::message-added) rather than polling.

  4. Overview of the RBAC Proxy Worker

    main

    The rbac-proxy is a standalone iii worker designed to provide Role-Based Access Control (RBAC) in front of the iii engine. Unlike the engine-native worker-gateway, the rbac-proxy runs as a separate process or pod, allowing it to front remote or managed engines that you do not own.

    It acts as a transparent proxy that:

    • Authenticates incoming WebSocket connections.
    • Gates function and trigger invocations based on permissions.
    • Namespaces registrations using a prefix.
    • Rewrites the results of all eight engine::* discovery functions so clients only see permitted resources.
    • Bridges WebSocket channels from the engine to the downstream worker.

  6. Overview of Core Workers

    main

    Core Workers are high-performance components built with Rust that provide specific capabilities to the iii architecture. Common core workers include:

    • HTTP Worker: Exposes functions as HTTP endpoints.
    • Stream Worker: Provides durable streams for real-time data subscriptions.
    • Queue Worker: Handles topic-based message queuing with support for retries and Dead Letter Queues (DLQ).
    • PubSub Worker: Enables topic-based publish/subscribe for real-time events.
    • Cron Worker: Allows scheduling functions using cron expressions.
    • Observability Worker: Manages traces, metrics, logs, and alerts using OpenTelemetry.

  7. Overview of the Sandbox API

    main

    The Sandbox API provides a runtime interface for spawning short-lived, isolated microVMs (using libkrun) from worker code or the terminal. Each sandbox boots in milliseconds, runs commands in isolation, and discards its filesystem upon stopping.

    Use cases:

    • Running untrusted code or AI-agent tool calls.
    • Executing one-shot scripts without sharing state with workers.
    • Achieving per-request isolation with a fresh environment.

    Limitations:

    • Not for long-lived services: Use a regular worker instead.
    • Not for durable state: The overlay filesystem is wiped on stop.
    • Hardware Requirements: Requires hardware virtualization. macOS must be on Apple Silicon, and Linux must have KVM enabled (/dev/kvm must be readable by the engine process). Intel Macs, Windows, and Linux without KVM are not supported and will return error S300.

  8. Overview of the rbac-proxy worker

    main

    The rbac-proxy is a binary Rust worker that acts as a secure boundary for the iii platform. It opens a public WebSocket port and reverse-proxies all incoming connections (functions and channels) to a trusted engine listener while enforcing Role-Based Access Control (RBAC) at the boundary.

    Key characteristics:

    • Pure Boundary: It does not store data, run agent logic, or provide business functions.
    • Fail-Closed Security: If the control connection to the engine drops, the proxy fails closed, rejecting new upgrades and gated invocations until connectivity is restored.
    • Resilience: A failure in the control connection does not tear down existing established data connections, though new operations requiring auth or middleware will be denied.
    • Worker Prefix: rbac-proxy::*

  10. Understand the iii core architecture: Workers, Triggers, Functions, and the Engine

    main

    The iii platform is built on four fundamental components that interact via the Engine:

    • Workers: Independent processes that connect to the Engine via WebSocket. They host Functions and register Triggers. Workers are isolated; a crash in one does not affect others. They can be written in any language that supports WebSockets and JSON.
    • Functions: Named handlers inside a Worker that process a payload and return a result. They are identified by a stable service::name string (e.g., math::add), allowing them to be called across language and location boundaries.
    • Triggers: Bindings that cause a Function to run based on an event. A Trigger consists of a type (e.g., http, cron, queue), a config (e.g., a path or schedule), and a function_id to invoke. Triggers can also include an optional condition_function_id to gate execution.
    • Engine: The central coordinator. It maintains a live registry of all Functions and Triggers and routes all invocations between Workers via WebSockets. There is no direct worker-to-worker traffic; all communication goes through the Engine.

  11. Understand the iii Channels model

    main

    Channels are WebSocket-backed stream pipes used for real-time data transfer between iii workers. They allow one function to write bytes or text while another reads them, even across different processes or programming languages (Node, Python, Rust).

    Core Concepts

    • Channel: A pipe managed by the engine.
    • Writer: The entity that sends bytes or text messages into the pipe.
    • Reader: The entity that receives bytes or text messages from the pipe.
    • Ref: A small, serializable token (e.g., readerRef) passed through standard trigger() payloads to coordinate the stream.

    Why use Channels instead of standard function calls?

    Standard function invocations use JSON messages, which are ideal for structured commands but inefficient for:

    • Large files or media
    • Streaming responses (e.g., AI agent chats)
    • Long-running partial outputs

  12. Understand the iii core primitives: Worker, Trigger, and Function

    main

    iii organizes all software capabilities into three fundamental primitives. Every capability in a system—including queues, cron jobs, streaming, sandboxing, observability, agents, business logic, devices, and even frontend browser UIs—is built using these three components:

    • Worker: The entity that hosts work (e.g., a service running in Docker, Kubernetes, a browser, or a microVM).
    • Trigger: The mechanism that causes work to happen.
    • Function: The actual logic that performs the work.

    By using these unified primitives, adding new capabilities (workers) is a consistent operation regardless of scale, and all workers communicate via a single WebSocket connection model.