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
  +----------------------+         +------------------------+
  | agent.md             |         | manifest.json          |
  | skills/  plugins/    |  build  | agent-revision.json    |
  | assets/  sandbox/    | ------> | route-table.json       |
  | subagents/ evals/    |compiler| automations.json       |
  | plugins.lock         |         | preflight.json         |
  |                      |         | 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 safely parses agent.md, statically reads each native plugin entry once without executing it, resolves one typed agent graph, and uses that same graph for validation and artifact emission. Declarative composition is stored as a manifest plan; generated modules are reserved for executable plugin adapters. 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.
• Plugins make every replaceable choice substitutable at a typed role: model, deploy, state, blob, sandbox, secrets, channel, media, connection, context, and observability. Scheduling and the Node/Pi runtime loop remain kernel orchestration. The same agent folder moves between providers without framework 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 the Markdown body of agent.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 reviewed compiled automation lifecycle code, 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, including coding-agent skill installation and version-matched docs commands.
• @assemblyline-agents/docs: generated developer-docs corpus, focused search/read APIs, diagnostic links, and read-only MCP transport.
• @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 provider-neutral model loop behind the internal AgentHarness contract; it loads only manifest-selected model registrations.
• @assemblyline-agents/node: hosted-container HTTP runtime host and generic plugin/provider loader.
• @assemblyline-agents/openrouter, openai, and openai-codex: ordinary model-provider plugins. The Codex plugin delegates to Pi's standard provider and OAuth store; there is no privileged Codex harness package.
• @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 observability profiles and plugin instrumentation.
• @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: SSH/Docker publisher behind the supported hetzner deployment profile.
• @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 plugin for LiveKit connections, dispatch, and SIP tools.

Assembly Line core does not import product app code. Provider packages own their live adapter behavior, registration metadata, declarative selection, and option schema. The compiler resolves installed providers from locked Agent Plugin contributions rather than a closed provider catalog.

Artifact construction follows the selected plugin graph. A package being installed and locked does not make it active: only typed selections, capabilities, qualified contribution references, and checked-in local-plugin presence bring its code and dependencies into the immutable artifact.

Related Docs

• Framework Guide: concepts and contracts.
• Runtime And Deployment: CLI, artifact, HTTP API, lifecycle, and deploy targets.
• Runtime Configuration: runtime and operator environment variables.
• Plugins: the extension model and plugin catalog.
• Authoring Plugin Providers: implementation contracts for plugin authors.