// Engineering & Architecture

Engineering & Architecture

How Driftless is built and run. This page describes the platform's architecture and operating model at a capability level — what the system does, how it stays reliable, how agents are controlled, and how it interoperates — so an evaluator can assess Driftless against the dimensions that matter for autonomous systems. It documents what the system does, not how it is implemented internally.

System design overview

Driftless is a multi-service platform. Independent services own separate responsibilities and each exposes its own health checks per route, so a fault in one area does not take down the whole system. The data layer pairs a document database for durable records with an in-memory cache for low-latency state, and every tier scales horizontally — capacity is added by running more instances, not by resizing a single machine.

The platform is multi-tenant with logical isolation: every organization's data is kept separate from every other organization's, enforced on every authenticated request. An agent or key authenticated for one organization cannot read or modify another organization's data.

For the full access-control, audit, and data-isolation model, see the Security page. This page covers architecture and operating behavior.

Reliability commitments

Driftless publishes its health, commits to an uptime target, monitors itself continuously, and writes postmortems for incidents.

Status page. Live system health is published at status.godriftless.ai, so customers and evaluators can see current and historical uptime without asking.
Service-level agreement. Uptime targets, how downtime is measured, and service credits are documented in the SLA.
Continuous monitoring. Independent health checks poll four endpoints every 30 seconds and alert on failure, so degradation is detected in minutes rather than discovered by a customer.
Postmortem policy. After any incident, Driftless writes a postmortem that captures what happened, why, and the corrective actions taken — and uses it to prevent recurrence. Postmortems are blameless and focus on system improvement.

Execution model

Driftless runs agents in two sandboxed contexts, each suited to a different kind of work. Both are sandboxed by design, and in both, agent output is version-controlled and reviewed by a human before it ships — operators own their CI/CD pipeline and decide what merges and deploys.

Hosted agents — the business-analyst agent

The hosted business-analyst (BA) agent runs in Driftless's multi-tenant Node.js web server, which scales horizontally to serve many organizations at once. Concurrency is isolated at the process and request level — the same standard isolation any HTTPS web server uses to separate concurrent connections. Each agent is scoped, tool-limited, and tenant-isolated: it can only act within the organization it was authenticated for and only with the tools it was granted.

Orchestrator agents — the coding agent

The orchestrator (coding) agent runs on the operator's own machine, sandboxed from the network. It can execute arbitrary code at the operator's discretion — building, testing, and shipping software locally — but it is tool-limited and cannot reach the network unless the operator allows it. The operator owns the runtime, the filesystem, and the execution environment.

In both contexts, agents are sandboxed by design: hosted agents are isolated from other tenants, and orchestrator agents are isolated from the network. Agents never self-certify completion or push to production on their own — human approval gates the transitions that matter.

Failure handling & adaptation

Driftless agents do not simply stop at the first error. Failures are handled with directive-driven retry, alternate strategies, and structured escalation — self-correction that goes beyond normal guardrails.

Directive-driven retry with alternate strategies. When an approach fails, the agent re-plans (LLM-driven) and tries a different strategy rather than blindly repeating the failed one.
Exponential backoff on transient failures. Rate limits, timeouts, and other transient errors are retried with exponential backoff so the system recovers without overwhelming a dependency.
Blocked-state routing with structured evidence. When an agent is genuinely blocked, it stops and documents its concrete attempts, the command outputs it saw, and why each attempt failed — so the operator has full context to unblock it.
Graceful degradation. Errors surface to the operator with context, not as silent failures; an agent that cannot complete a step reports the problem and the work it did get done.

A concrete example

When the update_task MCP tool rejects a description for exceeding its 5000-character limit, the agent detects the error from the response, adapts — it trims the content to the essentials — and retries successfully. That sequence is failure detection → strategy change → successful retry: self-correction beyond a normal guardrail. The behavior is directive-instructed and LLM-executed, and agent logs capture the full retry sequence so it can be reviewed afterward.

Operator control & sovereignty

Operators stay in control of model, infrastructure, and autonomy. Driftless is designed so that the human owns the decisions and the agent does the work.

Bring your own key (BYOK). Operators select both the model and the provider — OpenAI, Anthropic, OpenRouter, or Ollama — so inference runs where the operator wants it, on the terms the operator accepts.
Hosted or self-hosted. Run agents in Driftless's hosted runtime, or on your own infrastructure via the orchestrator. The same agent works in either place.
Open-source agent. The agent is being open-sourced, so operators can inspect, modify, and self-host it — no black-box execution.
Configurable autonomy. Wire CI/CD for autonomous deployment, or keep human gates on every merge. The level of autonomy is the operator's choice, not the platform's.

Planning & methodology

Driftless uses the Cascades methodology — a documented multi-step planning process with explicit decomposition and intermediate reasoning, not a single prompt turned into a single output. Work flows through four stages:

Shape	Requirements are decomposed into a paired PRD and tech spec with bidirectional traceability — every requirement traces to a spec, and every spec back to a requirement.
Gate	A spec gate validates the pair for completeness, buildability, contamination, and collision before any code is written — contradictions are caught when they are cheap to fix.
Ship	Work proceeds against TDD-ready acceptance criteria, with dependency chains traced so each piece lands in the right order.
Verify	Acceptance criteria pass with test evidence, and human verification is the final gate — an agent's claim of done is not the same as done.

Each stage produces an artifact and a checkpoint, making the reasoning explicit and reviewable at every step.

Memory & state continuity

Driftless agents use a layered context model that persists across sessions, so an agent can work over long horizons without losing the thread.

Layered context

Active window	Full-fidelity context for the work in progress.
Prior topics	Session-recency recall of earlier topics in the same session.
Persistent memory	Cross-session memory, promoted via just-in-time summarization so earlier work is available later.
Durable facts	Long-lived key-value facts the agent can rely on across sessions and tasks.

Memory curation

Memory is actively curated in a tri-state: promote a topic into persistent memory, demote it to a lower-fidelity tier, or deprecate it when it is no longer relevant. Curation is controlled by both the agent and the user, so the memory model stays accurate and current rather than accumulating noise.

Notes

Each topic carries ephemeral per-topic working notes the agent can read and update, giving it a scratchpad for the current line of work without polluting the durable layers.

This is advanced long-horizon memory management with cross-session persistence and agent-driven curation — the agent remembers what matters and forgets what does not. For the full architecture — the three-layer context model, just-in-time summarization, the tri-state curation model, durable facts, notes, and lifecycle triggers — read the memory architecture white paper.

Interoperability

Driftless speaks multiple agent and integration standards, so it fits into existing toolchains rather than forcing a replacement.

MCP (Model Context Protocol). A live endpoint using JSON-RPC 2.0 — connect any MCP-compatible client to Driftless. Documented at /docs/mcp.
ACP (Agent Communication Protocol). A second agent communication standard, in active development, so Driftless interoperates across agent ecosystems rather than locking into one.
REST API. A documented REST API with an OpenAPI spec for programmatic access to projects, initiatives, tasks, and more. Documented at /docs/api.
Integrations. Webhooks for event-driven automation; Slack and Jira bidirectional sync in active development; and provider integrations across four model providers.

Two agent communication standards — MCP and ACP — plus a documented REST API and a growing integration surface.