Install

Agentlas OS — for Claude Code, Codex, Antigravity, Cursor and the other hosts on your machine. No sudo, nothing written outside $HOME. Restart your agent host afterwards and run hephaestus doctor.

curl -fsSL https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh | bash

Agentlas Desktop — the app, if you prefer a window to a terminal.

curl -fsSL https://agentlas.cloud/install.sh | bash        # macOS · Linux

irm https://agentlas.cloud/install.ps1 | iex               # Windows PowerShell

<p align="center">_{Downloads the latest signed release, checks its sha512, and installs without <code>sudo</code> or an admin prompt · <a href="https://github.com/agentlas-ai/agentlas-desktop-releases/releases/latest">download manually</a> · <a href="https://github.com/agentlas-ai/agentlas-desktop">Agentlas Desktop is open source — view the repo</a>}</p>

<details> <summary><strong>Desktop and Agentlas OS together</strong></summary>

curl -fsSL https://agentlas.cloud/install.sh | bash -s -- --with-engine

$env:AGENTLAS_WITH_ENGINE="1"; irm https://agentlas.cloud/install.ps1 | iex

</details>

---

Build your own specialist

When nobody on the list fits, build one. /hep-build turns a sentence into a portable single agent or team: it asks only the questions that would change the result, writes the package, and runs the contract checks before calling it done. /hep-build session does the same from the conversation you are already in.

/hep-build an agent that reviews App Store replies before they go out
/hep-build session

Every build ships input and output schemas, a routing card, and the rest of the package contract below; a build that misses a required file fails instead of shipping. Keep it in your private Agent Cloud or publish it to the free Hub with /hep-upload, and /hep-network can staff it like any other candidate.

---

Install: every method, and what it writes

curl -fsSL https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh | bash

One line, no sudo, nothing written outside $HOME. Then restart your agent host and run hephaestus doctor — it prints what is wired and what is not. Prefer a GUI? Agentlas Desktop runs the same runtime on macOS, Windows and Linux.

It configures every supported host it finds on this machine, not only the one you are typing in — detection is by what is on your PATH.

<details> <summary><strong>Everything it writes</strong> — the full list, because "and so on" is not an answer</summary>

Two things that are easy to assume wrongly:

- It configures every supported host it finds, not just the one you are typing in. Detection is by what is on your PATH, so an otherwise empty home still gets Cursor, OpenCode and the rest wired up if those CLIs are installed. Hosts it cannot find are reported as skipped, not faked. - It edits files that already exist (~/.codex/config.toml, ~/.cursor/mcp.json, ~/.config/opencode/opencode.json, ~/.copilot/mcp-config.json, ~/.gemini/config/mcp_config.json). It replaces only the entries it owns — the hephaestus-network MCP server, plus the legacy agentlas entry it removes — and leaves every other key in place. A JSON config that does not parse is refused, not overwritten. No backup copy is written, except that a Codex marketplace-source change is snapshotted to ~/.codex/.agentlas-marketplace-backups/. An existing ~/.config/goose/config.yaml is never rewritten; the installer tells you how to add the entry yourself.

It never uses sudo, never writes outside $HOME, and downloads only from github.com. The release archive's SHA-256 is checked before anything is extracted, and a mismatch refuses the install.

Two more things worth knowing before you run it:

- An existing install is updated in place, not removed and reinstalled. An installed Claude Code plugin is updated with claude plugin update, and a marketplace entry is re-pointed only when it is the installer's own verified source, so unrelated plugin settings survive. - ~/.claude.json may appear at the root of your home. That is the claude CLI initialising itself; on native Windows it also records the MCP server the installer registers with claude mcp add --scope user.

</details>

Paste to Install

Already inside an LLM? Paste this into Claude Code, Codex, Antigravity or Cursor. It is written so the model can verify what it is running before it runs it, rather than being asked to trust it blindly:

I want to install Agentlas OS / Hephaestus from this open-source GitHub repo:
https://github.com/agentlas-ai/Agentlas-OS

Before running anything, fetch and read the installer script so you know what
it does:
https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh

It downloads a release tarball from this same repo's GitHub Releases, verifies
its SHA-256 before extracting, and writes files only under ~/.agentlas,
~/.local/bin, and the plugin/command-adapter directories of the agent hosts it
finds on this machine (e.g. ~/.claude for Claude Code) — nothing outside those
paths, and never with sudo. If that matches what you read, run it:
curl -fsSL https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh | bash

Afterwards, show me the installer's own verification output for this host,
and tell me plainly whether `/agentlas build` (or this host's equivalent
command surface) is ready to use, or whether I need to restart the host or
reload plugins first.

Do not add the optional global router yet — I will decide that separately.

The package contract — what every build must emit

An agent package is not a worker with capabilities. It is a method document. Three layers, and conflating them is the single most expensive mistake this project has made:

"Can this agent read the web?" is a category error. The runtime reads the web. The only question a package can answer is what method does it carry, and what must the machine be able to do for that method to run.

package-contract.json is the machine-readable list of artifacts every build emits, and bin/hephaestus contract verify <folder> is what enforces it. A build that omits a required artifact fails; it does not ship. Four of those artifacts carry the routing contract:

contracts/intake.schema.json     what a requester must hand over before work starts
contracts/output.schema.json     what the requester ends up holding
contracts/output.example.json    one real instance, validated by a JSON Schema
                                 validator at publish time — never by a model
.agentlas/brief.json             the compiled resume, schemaVersion agentlas.brief/1

Direction lives in the filename because nothing else ever marked it, and a schema whose direction must be guessed cannot be matched against a request.

Two rules bind every enum a build writes. Both were paid for in production:

1. Any enum reachable from matching must carry an escape member ("other", "unknown"). Matching one stated requirement against a 23-word closed list took a three-candidate inventory to zero on eight probes out of eight. A publisher whose real case is not on the list must still be findable. 2. Sentences stay sentences. No field that holds an author's sentence may be split into terms for matching. Shredding refusal sentences into the bare words tests and ci cut a correct agent's score to a quarter and pushed it from rank 2 to rank 24 — on a query that was literally its own job.

Vendor and MCP names live in exactly one place, host[].preferred, and that field is display-only. Roughly 99.9% of machines have no MCP servers installed, so a package wired to its author's own Slack, Notion or Jira has to stay usable by everyone else: the matcher reads host[].capability ("open the page in a real browser and read what a user would see") and every requirement states withoutIt, what the method still does on a machine that lacks the facility.

agentlas.brief/1 is written from either side — side: "offer" is the package's resume, side: "need" is the requester's work order. The same form, so the two can be compared without a translation step. Its schema is schemas/agentlas-brief.schema.json, and it is compiled, never hand-written: the upload path writes it from the files the package already ships.

provenance is the part that keeps the rest honest. absent is a legal value that scores zero, so a gap stays a gap. Filling gaps with something plausible is how capabilities came to equal snake_case(agent.md ## Responsibilities) in 130 of 130 packages — a field that was always full and never once informative.

The reference shape is Web_master: it ships input and output contracts as real JSON Schema, a domain catalogue its rules are checked against, and verification scripts that run. Everything above is what a build has to emit to be readable the way that package already is.

Deliberately absent: there is no field for what an agent is good at, and none for its permissions. Quality cannot be read off a package that has never run, and permissions are granted by the host after the fact — an employer hands you a computer once you are hired, so neither says anything about whether this method fits the work.

Manual LLM Adapter Install

Use this only when your current LLM cannot run setup for you. It installs the shared Hephaestus runner and command adapters for supported LLM tools.

xcode-select --install   # Command line tools (skip if already installed)
git --version            # Confirm git is available
curl -fsSL https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh | bash

Desktop startup and every /hep-* command start the same digest-verified, rate-limited update check in the background. The current command never waits for network or installation work. A successful update atomically moves ~/.agentlas/runtime/current and reconciles every already-installed host adapter; the next command or reloaded session uses the new release. Releases v1.1.63 through v1.1.68 briefly installed a separate six-hour OS scheduler. Current installs remove that retired scheduler automatically.

Offline or air-gapped install: set HEPHAESTUS_SOURCE_DIR=/path/to/checkout before running the installer to skip the GitHub release download and verified checksum step entirely and install straight from a local Agentlas-OS checkout instead, e.g. HEPHAESTUS_SOURCE_DIR=$(pwd) bash scripts/install-all-runtimes.sh. Use it when you already have the source on disk (a git clone or an already-extracted release) and want a fully local install.

Build telemetry

hep-build sends anonymous counters so we can see where builds fail: a random install id generated locally, which build step ran, whether it succeeded, a machine error code, a duration, and the OS/engine/python versions. Events are deleted 180 days after they arrive.

Never sent: file paths, package names, prompts, agent content, error message text, usernames, emails, or environment variables. The allowlist is enforced in the engine before the request is built and again on the server, which drops every field it does not recognize.

Turn it off with either of these — a build behaves identically with telemetry disabled, and every failure path (offline, DNS, server error, a bug in the telemetry code) is already swallowed silently without touching your build:

export AGENTLAS_TELEMETRY=0
export DO_NOT_TRACK=1     # the cross-vendor convention, honored here

Or permanently, in ~/.agentlas/networking/config.json:

{ "telemetry": false, "telemetrySetBy": "user" }

The telemetrySetBy marker is what separates a choice you made from the "telemetry": false that default_config() wrote into every install created before the key was ever read — that value never represented anyone's decision, so it is not treated as one.

---

Optional: route work automatically

Off by default. hephaestus global install appends roughly 75 lines to the global instructions file of every supported host it finds — measured on a clean machine that was ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md and ~/.gemini/GEMINI.md, three files, not one. It changes how substantial work is routed from then on, in every project, so it is a bigger decision than the rest of the install and it is yours to make separately.

It appends rather than overwrites, writes a timestamped .bak beside each file, is idempotent on a second run, and is fenced with ` so hephaestus global remove` takes it back out. To turn it on during the install instead, add HEPHAESTUS_INSTALL_GLOBAL_ROUTER=1 before bash.

Optional Global Router

hephaestus global install

The installed router prompt asks the host to report results by the workers that did the task rather than narrating the routing step — it is a conciseness convention, not a secrecy one, and it says so. It carries an explicit status-line contract for English and Korean sessions:

Global router command reference:

The independent Agentlas Terminal owns the agentlas shell command. The Core installer intentionally leaves that command untouched and removes only the exact legacy Core alias it created in older releases.

Portable package, local execution

Describe the work
  -> build a portable agent or team
  -> save it to my owner-scoped Agent Cloud
  -> install Agentlas OS and sign in on another supported host
  -> retrieve it with /agentlas cloud
  -> my chosen model and current host execute the work

Agent Cloud stores and retrieves the owner's package; it is not a hosted LLM that completes the work on the server. When you call a package, your selected model and current host runtime execute it under that host's permission and safety model. Credentials, local files, and machine-specific permissions do not travel with the package—you configure those separately on each computer.

Per-Runtime Plugin Drivers

<details> <summary>Claude Code Plugin</summary>

From your OS terminal:

claude plugin marketplace add https://github.com/agentlas-ai/Agentlas-OS --sparse .claude-plugin claude/plugins
claude plugin install hephaestus@agentlas-core-engine

</details>

<details> <summary>Codex Plugin</summary>

From your OS terminal:

codex plugin marketplace add agentlas-ai/Agentlas-OS --ref v1.2.69
codex plugin add hephaestus@agentlas-core-engine

</details>

<details> <summary>Copy Files into a Project (Manual Driver)</summary>

Clone the repo and copy AGENTS.md, agent.md, agents/, skills/, modes/, schemas/, templates/, and .agentlas/ into your workspace. Runtime folders (.claude/, codex/, antigravity/, .agents/) function as adapters over the same canonical core.

</details>

Just talk: After installation, speak in plain language within native Agentlas interfaces to auto-route tasks. In external LLM tools, use the explicit commands listed below. When you don't know what agents exist, start with /agentlas search.

One word to remember: everything starts with agentlas in an LLM host — /agentlas. In a shell the commands are hephaestus and hep-*; the agentlas shell command belongs to the separate Agentlas Terminal.

---

</details>

<details> <summary><strong>The Command Surface — every command</strong></summary>

Inside native Agentlas environments, Hephaestus operates commandless. External LLM tools use a deliberately small visible command set for building agents and staffing work with them:

/hep-orch sets which model runs the orchestrator and which runs the workers, so a fan-out of mechanical work does not bill frontier runs. The split only puts two models to work on Claude Code, which is the one host that spawns a real subagent and takes a model per subagent. Codex, Antigravity, Cursor, and OpenCode have no subagent of their own: one model plays every role in sequence there, the allocation receipt is still written, and the ceiling still bounds what that model may request — but no second, cheaper model appears.

/hep-goal adds a plan tree to your host's own /goal. It first decides the shape of the goal. Short work with one clear check stays a single tactic and behaves exactly like the host goal, with no extra text. A long goal with a number you named becomes a mission tree: key results, strategies, tactics, and a KPI reading that says whether the plan is moving. It tells you when the numbers say the plan has stalled, and when the target looks out of reach it asks you instead of re-planning forever. The host goal still decides when the work is done; /hep-goal only keeps the plan and the numbers honest. A target is only a number you wrote in the goal text, and every reading needs a source and a short evidence quote. It changes only its own files under .agentlas/goal/, never permissions or payments. The default mode is shadow (it records and measures, injects nothing, applies no re-plan); set AGENTLAS_GOAL_STRATEGY=on to use it.

What has been measured so far: against a simulated account, the engine saw a stalled approach on day 2 and told the owner about an unreachable target on day 3, where a loop that keeps one approach never does; with a better alternative to switch to it reached 298 of 300 followers against 44. That simulation assumes the alternatives are known, so it shows the mechanism, not a model's judgment. With real models, sonnet and haiku stored a valid plan in 12 of 12 runs (the right shape every time, targets equal to the owner's numbers), and submitted an accepted re-plan in 6 of 6 review runs. Not measured: whether it beats a plain host goal on real long-running work. Treat it as unproven until it has run on real goals.

Every row also answers to its original /hep-* name — /agentlas network and /hep-network are the same command. Nothing was renamed away, so existing scripts, notes, and muscle memory keep working. Current Codex uses explicit plugin skills $hephaestus-build, $hephaestus-network, $hephaestus-cloud, and $hephaestus-upload; other MCP surfaces can be requested in plain language. Custom /prompts:* commands were removed from Codex 0.117+.

---

</details>

<details> <summary><strong>Deeper — the build factory and the routing scheduler</strong></summary>

Questions you probably have

<details open> <summary><strong>So you recommend one to me in the end, right?</strong></summary>

<br>

Every place that sells agents ranks them. That is how they make money. People click what is near the top, and the company decides what is near the top.

We don't build a ranking. The schema pins allowHistoryEvidence to a constant false, and a source that returns a scored list has its whole answer refused.

Ratings, install counts, last month's sales — we read none of them. You get the candidates as they are, and your model picks.

</details>

<details> <summary><strong>Is this only for developers?</strong></summary>

<br>

No. Alongside backend, security and QA, the role ontology carries an insurance actuary, an M&A diligence lead, an underwriting diligence specialist and a travel planner.

Insurance alone has four communities. Domains outside the list are not blocked.

</details>

---