Getting Started

Go from a fresh clone to a working agent run.

Quickstart

git clone https://github.com/jasonbadeaux/assembly-line.git && cd assembly-line
pnpm install
pnpm build
pnpm assembly-line init scratch/agent
pnpm assembly-line run scratch/agent --tool list --input '{"path":"/workspace"}'

The last command builds the new MD-first agent and executes a framework tool locally with no model provider key. The rest of this page walks the same path in order: requirements, install, your first agent, the full example, serving, and the dev loop.

Requirements

Node.js >=22.19.0, pnpm 10.x, and Git. That is everything a first run needs.

Everything else is per-feature:

Set Up A Local Repository

Give Codex or Claude Code this one line from the repository you want to prepare:

Run `npx @assemblyline-agents/sdk@latest setup` in this repository. Set up Assembly Line only; do not create an agent.

The command detects the package manager, installs and pins the SDK, installs project-scoped guidance for both coding agents, verifies the bundled docs, and stops. It does not scaffold an agent, choose a provider, or start a build. The repository remains ready until the user asks to create an agent.

Run the command directly when not using a coding agent:

npx @assemblyline-agents/sdk@latest setup

Install And Build From Source

Assembly Line runs from a source checkout:

git clone https://github.com/jasonbadeaux/assembly-line.git
cd assembly-line
pnpm install
pnpm build

In a checkout, invoke every CLI command through the workspace script as pnpm assembly-line <command>; this page uses that form throughout. Every other page uses the installed form, assembly-line <command>. The two forms run the same command.

pnpm test runs the test suite and pnpm check typechecks the packages without running tests. pnpm assembly-line help lists every command, and pnpm assembly-line help <command> prints one command's flags.

If Codex or Claude Code will edit agents in this checkout, install the shared, project-scoped authoring guidance once:

pnpm assembly-line authoring install all .

The integration uses version-matched docs from the installed CLI. See Coding Agents for its progressive disclosure and optional MCP setup. For personal Codex sessions across repositories, you can instead install the latest routing skill globally:

npx skills add jasonbadeaux/assembly-line --skill assembly-line-authoring -g -y

Create Your First Agent

Scaffold a new agent folder:

mkdir -p scratch
pnpm assembly-line init scratch/agent

Created Assembly Line agent at /path/to/assembly-line/scratch/agent
Installed Codex and Claude Code authoring guidance with version-matched documentation routing.
Next: customize /path/to/assembly-line/scratch/agent/agent.md, then: assembly-line validate /path/to/assembly-line/scratch/agent --json
Run: set OPENROUTER_API_KEY, then: assembly-line run /path/to/assembly-line/scratch/agent --message "hello"

The authored runtime contract has one required file. The scaffold also adds coding-agent routing files so a Codex or Claude Code session started inside the agent folder can retrieve the matching documentation:

scratch/agent/
  agent.md
  skills/
  plugins/
  sandbox/
  subagents/
  assets/
  evals/
  AGENTS.md
  CLAUDE.md
  .agents/skills/assembly-line-authoring/
  .claude/skills/assembly-line-authoring/

The runtime supplies the default context, local infrastructure profiles, and the core read, write, edit, delete, list, grep, bash, handoff_artifact, deliver_artifact, load_skill, tool_search, and pair tools when their files are omitted.

Validate it:

pnpm assembly-line validate scratch/agent

Valid Assembly Line agent: /path/to/assembly-line/scratch/agent

validate catches shape, export, schema, route, schedule, plugin-lock, and adapter issues. A provider/model ID compiles only when its prefix is contributed by an installed and locked model plugin. The build asks that plugin to resolve the model's capabilities and records the result in the artifact.

Run a direct tool call. This needs no provider key: when --tool is provided, the runtime simulates the model step and executes the named tool with inferred or explicit input:

pnpm assembly-line run scratch/agent --tool list --input '{"path":"/workspace"}'

{
  "run": {
    "id": "3f9d2b1e-…",
    "status": "completed",
    ...
  },
  "toolCalls": [
    { "toolName": "list", "status": "completed", ... }
  ],
  "response": "{...}",
  ...
}

To run a full model turn, omit --tool and provide the auth required by the model prefix in agent.md: the scaffolded openrouter/openai/gpt-5.4-mini uses OPENROUTER_API_KEY, while openai-codex/gpt-5.6-terra uses Pi's provider-native OAuth flow (see the subscription setup below).

Export the model credential in your shell or configure the agent's secret store:

export OPENROUTER_API_KEY=...
pnpm assembly-line run scratch/agent --message "hello"

Agent-root .env files are not loaded. Put committed non-secret values in config.production.ts; local shell values override that file. Credentials do not belong there. See Runtime And Deployment.

Grow the agent with assembly-line add, which installs a published capability plugin or an explicit channel/infrastructure provider and updates agent.md, then prints the environment variables to set:

pnpm assembly-line add slack scratch/agent --role channel
pnpm assembly-line add docker scratch/agent --role sandbox

The package manager is detected from lockfiles (pnpm/yarn/npm). Pass --no-install to skip the package manager and print the exact install command. Registered channel and infrastructure selections can still update agent.md; published plugins are not selected or locked until their package is installed and validated. Use state: postgres for an ordinary DATABASE_URL. Use neon, railway, or supabase only when you need that placement preset.

Run the checked-in example

examples/minimal-agent/agent is a complete MD-first example with a root Skill, local plugin, subagent, and evaluation cases. Use it to inspect a larger source tree after the scaffolded agent works.

Validate and build it:

pnpm assembly-line validate examples/minimal-agent/agent
pnpm assembly-line build examples/minimal-agent/agent

Valid Assembly Line agent: /path/to/assembly-line/examples/minimal-agent/agent
Built Assembly Line agent revision 4b0c9a17…
Artifact: /path/to/assembly-line/examples/minimal-agent/agent/.assembly-line

To keep generated artifacts out of the example directory during experiments, add --out /private/tmp/assembly-line-minimal to build, run, serve, or deploy --dry-run.

Run a direct tool call:

pnpm assembly-line run examples/minimal-agent/agent \
  --message "hello from Assembly Line" \
  --tool echo

Serve And Inspect

Inspect the compiled manifest:

pnpm assembly-line inspect scratch/agent --resolved

This prints the full compiled manifest JSON, agent metadata, tools, channels, schedules, connections, and the route table.

Serve the runtime locally:

pnpm assembly-line serve scratch/agent --port 3000

Assembly Line runtime serving 4b0c9a17…
http://127.0.0.1:3000

Then call the local runtime from another terminal:

curl http://127.0.0.1:3000/health

{"ok":true,"agentRevision":"4b0c9a17…"}

curl -X POST http://127.0.0.1:3000/runs \
  -H "content-type: application/json" \
  -d '{"message":"list the workspace","toolName":"list","input":{"path":"/workspace"}}'

{
  "runId": "3f9d2b1e-…",
  "status": "completed",
  "response": "{...}",
  "waitingForApproval": false,
  "waitingForInput": false,
  "waitingForConnection": false,
  "eventCount": 6,
  "toolCallCount": 1
}

Useful inspection endpoints:

• GET /health and GET /healthz
• GET /manifest (admin-authenticated in production)
• GET /routes (admin-authenticated in production)
• GET /conversations and GET /conversations/:id/messages (admin-authenticated in production)
• POST /conversations/:id/turns (dev-mode only by default; opt-in and admin-authenticated in production)
• POST /runs (dev-mode only by default; opt-in and admin-authenticated in production)
• GET /runs: GET /runs/:id, GET /runs/:id/events, and GET /runs/:id/timeline (admin-authenticated in production)

Local serve runs in dev mode, so the inspection and API-run endpoints are open on your machine. Production Node hosts require an admin auth policy or ASSEMBLY_LINE_ADMIN_TOKEN for /manifest, /routes, /conversations, /runs, and run detail endpoints. Production direct turns and POST /runs are disabled unless ASSEMBLY_LINE_ENABLE_API_RUNS=true is set and the request is authenticated with Authorization: Bearer <ASSEMBLY_LINE_ADMIN_TOKEN>. The full HTTP API table is in Runtime And Deployment.

Development Loop

Start with the watch mode, which keeps a local HTTP server running and rebuilds + restarts it (on the same port) whenever the agent folder changes:

pnpm assembly-line dev scratch/agent --watch

While the agent is invalid, the previous server keeps running and the CLI prints the validation issues until the folder is valid again.

For one-off steps:

1. Edit files under the agent folder.
2. Run validate to catch shape, export, schema, route, schedule, and adapter issues.
3. Run build to emit .assembly-line/.
4. Run run for local one-off checks.
5. Run serve when testing HTTP channels or the inspection API.
6. Inspect .assembly-line/manifest.json, .assembly-line/route-table.json, .assembly-line/automations.json, and .assembly-line/preflight.json when something looks surprising.

Use A ChatGPT Subscription Through Codex

openai-codex/* is an ordinary model-plugin selection. The plugin registers Pi's standard openaiCodexProvider(); Assembly Line does not maintain a separate Codex harness, start a Codex CLI app-server, or copy a Codex CLI login cache. Pi owns browser/device-code OAuth, token refresh, and subscription billing semantics through Assembly Line's generic durable model-credential store.

Install, lock, and select the plugin:

pnpm assembly-line add openai-codex scratch/agent --role model

The resulting model selection is:

model: openai-codex/gpt-5.6-terra
reasoning: medium
maxReasoning: medium

Authenticate the selected provider, then run it normally. Local login opens Pi's browser flow; hosted targets prefer device-code login through the deploy plugin's generic remote-command capability:

pnpm assembly-line auth openai-codex scratch/agent
pnpm assembly-line run scratch/agent --message "hello from my Codex plan"

OPENAI_API_KEY is not required for this prefix. Usage and limits come from the signed-in ChatGPT plan. The encrypted credential file or Postgres-backed credential store is shared by root and subagent model calls, but never exposed to model context. For API-backed traffic, select openrouter/* or openai/*. See Runtime And Deployment for local and hosted authentication.

Common Issues

Common failures, install and build errors, a missing assembly-line command, model provider key errors, .assembly-line artifact churn, serve auth, deploy preflight, ingress secrets, and durability workers, are collected in Troubleshooting.

Next Steps

• Look up every accepted field, default, and override in the Declarative Reference.
• Learn what each file in an agent folder does in the Agent Build Stack.
• Follow the linear tutorial in Building Agents, scaffold to gated tools, channels, schedules, and evals.
• Learn the production path in Runtime And Deployment.
• Customize the runtime, context, and providers with Customizing Agents.
• Look up agent fields in the Declarative Reference and runtime environment variables in Runtime Configuration.
• Explore the examples:
  • minimal-agent - a complete MD-first example with a local plugin, Skill, subagent, and evals.
  • custom-context-agent - a custom context policy layered on defaultContext.
  • self-improving-agent - durable skills, runtime-created automations, and gated connection saving.
  • vps-deployment-agent - a named Hetzner inventory plus the required Postgres, R2, hosted-sandbox, and deploy: hetzner configuration.