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)  | capability snapshots - 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, and connection. 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:

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 automations can only reference compiled automation 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: supported provider-neutral existing-VPS deploy helper and SSH/Docker publisher.
• @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 assemblyLineProvider 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.

Related Docs

• Framework Guide: concepts and contracts.
• Runtime And Deployment: CLI, artifact, HTTP API, lifecycle, and deploy targets.
• Configuration Reference: every define* shape and environment variable.
• Plugins: the extension model and plugin catalog.
• Authoring Plugin Providers: implementation contracts for plugin authors.