Registry

An alineo "registry item" is just a URL that returns an AgentSpec JSON object (the same spec type used by alineo). Any URL works — a GitHub raw file, a Gist, your own server, or the small curated set of examples alineo hosts at registry.alineo.tech — there's no requirement to publish through a central service.

Publishing a spec

An agent spec is a static JSON file. Hosting it is as simple as pushing it to a public GitHub repository and sharing the raw URL:

https://raw.githubusercontent.com/your-org/your-repo/main/agents/node-toolchain.json

Anyone can then fetch it into their own project with:

bunx alineo-cli add https://raw.githubusercontent.com/your-org/your-repo/main/agents/node-toolchain.json

This only saves the spec locally — it doesn't run anything. See Running an agent spec for how to actually load and run it with Alineo.start().

Minimal example

Every spec runs inside a node:22 sandbox (there's no image field — the base image is fixed) and requires harness: "pi":

{
  "name": "node-toolchain",
  "harness": "pi",
  "setup": [{ "name": "install tools", "run": "npm install -g typescript eslint prettier" }]
}

Composition with registryDependencies

A spec can declare dependencies on other specs by URL. alineo add fetches and saves them first, depth-first, before saving the top-level spec — it does not merge or run them, each dependency just ends up as its own separate spec file in agentsDir:

{
  "name": "ts-reviewer",
  "harness": "pi",
  "registryDependencies": ["https://example.com/agents/node-toolchain.json"],
  "setup": [{ "name": "install linter", "run": "npm install -g @typescript-eslint/parser" }]
}

There's no cycle detection — avoid dependency chains that reference each other.