Getting Started

Go from a fresh clone to a working agent run.

Quickstart

git clone https://github.com/jasonbadeaux/openeve.git && cd openeve
pnpm install
pnpm build
pnpm assembly-line run examples/minimal-agent/agent --tool echo --message "hello from Assembly Line"

The last command builds the example agent and executes its echo 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:

Feature	Requirement
Model-backed runs	A provider key matching the model prefix, such as OPENAI_API_KEY or OPENROUTER_API_KEY
openai-codex/* subscription runs (preview)	A current Codex CLI and a ChatGPT account with Codex access
Docker sandbox or Docker deploys	Docker
Railway deploys	Railway CLI and RAILWAY_TOKEN
Fly deploys	Fly CLI and FLY_API_TOKEN
Generic VPS deploys	AMD64 Ubuntu 24.04/26.04 or Debian 12 host; existing Docker host or hcloud for secure Hetzner bootstrap
Production Postgres state	DATABASE_URL
Production file-backed connection credential stores	ASSEMBLY_LINE_CONNECTION_STORE_SECRET or ASSEMBLY_LINE_SECRET
Production blob storage	S3 or R2 credentials

Install And Build

Assembly Line runs from a source checkout:

git clone https://github.com/jasonbadeaux/openeve.git
cd openeve
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> — read them as 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.

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
Next: export OPENAI_API_KEY, then: pnpm assembly-line run /path/to/assembly-line/scratch/agent --message "hello"

The scaffold includes:

scratch/agent/
  instructions.md
  agent.ts
  gateway.ts
  .env.example
  tools/
    echo.ts

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, and adapter issues. It also warns when agent.ts names a model outside the local model catalog (pnpm assembly-line models lists it; --no-model-check skips the check).

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 echo --message "hello"

{
  "run": {
    "id": "3f9d2b1e-…",
    "status": "completed",
    ...
  },
  "toolCalls": [
    { "toolName": "echo", "status": "completed", ... }
  ],
  "response": "{\"message\":\"hello\"}",
  ...
}

To run a full model turn, omit --tool and provide the auth required by the model prefix in agent.ts: openai/gpt-5.4-mini requires OPENAI_API_KEY, while openai-codex/gpt-5.4-mini uses the Codex CLI session from codex login (see the Codex preview below).

Export provider values in your shell or put them in the agent-root .env:

cp scratch/agent/.env.example scratch/agent/.env
# Edit scratch/agent/.env and set OPENAI_API_KEY.
pnpm assembly-line run scratch/agent --message "hello"

Local dev, run, serve, and deploy --target local --serve commands load that file into the runtime process. Existing shell values win over .env, empty values still count as missing, and local execution does not upload the file or copy its values into a secret store or build artifact. See Runtime And Deployment.

Grow the agent with assembly-line add, which installs a plugin and wires its contribution into the agent (a gateway.ts slot, a channels/<kind>.ts file, or provider-specific guidance), then prints the environment variables to set:

pnpm assembly-line add slack scratch/agent      # installs @assemblyline-agents/slack, scaffolds channels/slack.ts
pnpm assembly-line add postgres scratch/agent   # installs @assemblyline-agents/postgres, sets state: adapter("postgres")
pnpm assembly-line add docker scratch/agent --role sandbox

The package manager is detected from lockfiles (pnpm/yarn/npm). Pass --no-install to only wire files and print the exact install command instead of running it.

Run The Full Example Agent

The example at examples/minimal-agent/agent includes instructions, an agent definition, a local HTTP channel, tools, a skill, a schedule, a connection declaration, a sandbox declaration, a subagent, and instrumentation.

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/openeve-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 manifest examples/minimal-agent/agent

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 examples/minimal-agent/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":"hello","toolName":"echo"}'

{
  "runId": "3f9d2b1e-…",
  "status": "completed",
  "response": "{\"message\":\"hello\"}",
  "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/schedules.json, and .assembly-line/preflight.json when something looks surprising.

Use A ChatGPT Subscription Through Codex (Preview)

Preview — this surface may change without notice.

The Node host can route an openai-codex/* model through OpenAI's official Codex app-server. Codex owns the ChatGPT sign-in and token storage; Assembly Line does not read, copy, or replay the OAuth cache against undocumented endpoints.

Install a current Codex CLI, then sign in and verify the session:

codex login
codex login status

Select a Codex model in scratch/agent/agent.ts:

import { defineAgent } from "@assemblyline-agents/core";

export default defineAgent({
  model: "openai-codex/gpt-5.4-mini",
  reasoning: "medium"
});

Run it normally; OPENAI_API_KEY is not required for this prefix:

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

Use this integration on a trusted local machine where you performed codex login; usage and limits come from the signed-in ChatGPT plan. For general hosted API traffic, use an API-backed prefix such as openai/*. See Runtime And Deployment for the hosted-auth boundary.

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

• 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 any config field or ASSEMBLY_LINE_* env var in the Configuration Reference.
• Explore the examples:
  • minimal-agent - the full agent folder shape with tools, skills, channels, schedules, connections, sandbox, subagents, and instrumentation.
  • custom-context-agent - a custom context policy layered on defaultContext.
  • self-improving-agent - durable skills, runtime-created schedules, and gated connection saving.
  • vps-deployment-agent - an existing-VPS inventory plus the required Postgres, R2, hosted-sandbox, and vpsDeploy() configuration.