Skip to main content

Assembly Line Architecture

Assembly Line turns a declarative agent folder into a durable runtime service. This page shows the shape of that system: the pipeline from folder to running service, the trust boundaries the runtime enforces, and the package boundaries that keep the framework core small.

System Shape​

        agent folder                    .assembly-line artifact
  +----------------------+         +------------------------+
  | instructions.md      |         | manifest.json          |
  | agent.ts  gateway.ts |  build  | agent-revision.json    |
  | tools/  skills/      | ------> | route-table.json       |
  | channels/ automations/|compiler| automations.json       |
  | connections/ sandbox/|         | preflight.json         |
  | subagents/ evals/    |         | server/boot.js  ...    |
  +----------------------+         +------------------------+
                                               |
                                               | boot
                                               v
  channels ---> +------------------------------------------+
  (Slack, HTTP, |              runtime host                |
   schedules,   |  durable runs - approvals - deliveries   |
   direct API)  |  checkpoints - recovery - workers        |
                +------------------------------------------+
                   |          |          |           |
                   v          v          v           v
                 state       blob     sandbox     engine
              (Postgres,  (S3/R2,   (Docker,    (Pi model
               local)      local)    Daytona,     loop)
                                     E2B, ...)
  • The compiler reads the folder statically (TypeScript AST, never executing config code), validates it, and emits a deterministic manifest plus a self-contained runtime artifact. The same source always produces the same agentRevision.
  • The runtime host loads the artifact and executes runs durably: every run is persisted before execution, every pause (approval, human input, suspension) is a durable state, and final delivery is an idempotent obligation backed by a queue.
  • Adapters make each infrastructure choice substitutable per role — deploy, runtime, state, blob, sandbox, scheduler, channel, connection — so the same agent folder moves between providers without rewrites.

Runtime And Deployment documents the artifact tree, HTTP API, and lifecycle; the Framework Guide explains each concept in depth.

Trust Boundaries​

Assembly Line separates three levels of trust and keeps them separate at runtime:

ZoneContainsTreated as
Trusted app codeagent.ts, gateway.ts, tool implementations, trigger handlers, context policy, channel normalizers, instrumentationReviewed source. Runs in the host process with access to adapters and secrets-by-reference.
Untrusted contextMemory, history, files, attachments, webpages, search results, tool output, remote tool descriptionsData, never instructions. Projected read-only where possible; never grants capabilities.
SandboxShell commands, generated code, CLI connections, subagent workspacesIsolated execution. Sees an allowlisted projection of logical paths, not the host filesystem.

Key consequences:

  • Instructions vs. context. Only instructions.md and durable skills are trusted instructions. Everything the agent reads at runtime — including MCP tool descriptions and dynamic-connection metadata — is untrusted context.
  • Credentials never enter the model. Connection secrets live in encrypted grant stores or the state adapter; they are resolved by trusted code and are never placed in model context, tool input, the agent folder, or the sandbox (except as explicitly configured short-lived materializations for sandbox CLI connections).
  • The sandbox is a projection, not a mount. /memory, /history, /files, and /workspace are logical paths hydrated on demand; /history and /files are read-only, and writeback flows through a durable sync queue rather than direct host writes.
  • Agents never author trusted code. Self-improvement is scoped to skills (instructions). Dynamic schedules can only reference compiled trigger handlers by name, and dynamic connections are URL-only, host-allowlisted, and approval-gated. Net-new typed tools are always a reviewed source change.
  • Ingress is authenticated per class. Control-plane routes require host auth or an admin token; provider webhook routes verify provider signatures; the scheduler tick requires its shared secret in production.

Package Boundaries​

The framework core stays small; everything provider-specific is an optional plugin package.

  • @assemblyline-agents/core: definitions, contracts, manifest types, and define* helpers.
  • @assemblyline-agents/compiler: folder discovery, validation, manifests, revisions, artifacts, routes, schedules, and deploy plans.
  • @assemblyline-agents/cli: command-line developer path.
  • @assemblyline-agents/sdk: public CLI/meta package that re-exports the core framework APIs.
  • @assemblyline-agents/runtime: durable lifecycle, context bundles, local adapters, engine-neutral harness loop, tool execution, approvals, human input, replay, and delivery obligations.
  • @assemblyline-agents/pi: the default multi-provider model loop behind the internal AgentHarness contract.
  • @assemblyline-agents/node: hosted-container HTTP runtime host, including the preview openai-codex/* provider-prefix route.
  • @assemblyline-agents/codex: official Codex app-server primary-model bridge.
  • @assemblyline-agents/railway: Railway deploy adapter helper and publisher.
  • @assemblyline-agents/postgres: Postgres state adapter migrations, query-client implementation, and provider presets.
  • @assemblyline-agents/s3: S3-compatible blob adapter plus AWS, MinIO, and R2 helpers.
  • @assemblyline-agents/r2: R2 compatibility wrapper.
  • @assemblyline-agents/otlp: OTLP/HTTP telemetry sink for instrumentation.ts.
  • @assemblyline-agents/daytona: Daytona sandbox adapter boundary.
  • @assemblyline-agents/docker: Docker deploy and sandbox adapters.
  • @assemblyline-agents/e2b: E2B sandbox adapter boundary.
  • @assemblyline-agents/modal: Modal sandbox adapter boundary.
  • @assemblyline-agents/fly: Fly deploy adapter helper and publisher.
  • @assemblyline-agents/vps: provider-neutral existing-VPS deploy helper and SSH/Docker publisher (preview).
  • @assemblyline-agents/slack, @assemblyline-agents/photon, @assemblyline-agents/discord, @assemblyline-agents/telegram, @assemblyline-agents/teams: agent communication channel helpers.
  • @assemblyline-agents/github: GitHub App and MCP connection helpers for authenticated repository tooling.
  • @assemblyline-agents/livekit: voice/telephony capability package for LiveKit connections, dispatch, and SIP tools.

Assembly Line core does not import product app code. Plugin packages own provider-specific helpers, live adapter behavior, and their own openeveProvider registration metadata; the CLI and Node host resolve built-in kinds from first-party defaults and any other kind through the adapter definition's packageName, failing with a specific error when a plugin package is missing or misshapen.