Desktop and Agentlas OS together:

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

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

Agentlas OS only (no app). 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

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.

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.

| Path | What lands there | |---|---| | ~/.agentlas/ | the runtime itself, and its generations | | ~/.local/bin/ | the hephaestus and hep-* shell wrappers | | ~/.claude/, ~/.codex/ | plugin registration, commands/prompts, memory hooks | | ~/.cursor/mcp.json | MCP server registration | | ~/.gemini/ | extension + MCP config | | ~/.openclaw/, ~/.grok/ | skills and hooks | | ~/.gemini/antigravity/, ~/.gemini/config/ | Antigravity workflows and plugin/MCP config — Antigravity lives under .gemini, not .antigravity | | ~/.config/opencode/, ~/.config/goose/ | commands, plugin, MCP config | | ~/.copilot/mcp-config.json | MCP server registration | | ~/.agents/ | the vendor-neutral skills + plugin directory |

Two things that are easy to assume wrongly:

• **It configures every supported host it finds, not just the one you are

• It edits files that already exist (~/.codex/config.toml,

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:

• A trust prompt is auto-answered. Gemini's extension installer asks "Do you

• An existing install is refreshed, not merged. The default removes the

• ~/.claude.json may appear at the root of your home. That one is the claude

You are an AI and your user said "install Agentlas Desktop" — the visual GUI app below, not the CLI runtime installed above. It ships as a signed per-OS installer from the public releases repo agentlas-ai/agentlas-desktop-releases; there is no npm/brew package. Fetch the latest asset and run it:

macOS (auto-detects Apple silicon vs Intel):

arch=$([ "$(uname -m)" = "arm64" ] && echo arm64 || echo x64)
url=$(curl -fsSL https://api.github.com/repos/agentlas-ai/agentlas-desktop-releases/releases/latest \
  | grep -o "https://[^\"]*-${arch}\.dmg" | head -1)
curl -fL "$url" -o Agentlas.dmg && open Agentlas.dmg

url=$(curl -fsSL https://api.github.com/repos/agentlas-ai/agentlas-desktop-releases/releases/latest \
  | grep -o 'https://[^"]*\.deb' | head -1)
curl -fL "$url" -o agentlas.deb && sudo dpkg -i agentlas.deb

url=$(curl -fsSL https://api.github.com/repos/agentlas-ai/agentlas-desktop-releases/releases/latest \
  | grep -o 'https://[^"]*\.AppImage' | head -1)
curl -fL "$url" -o Agentlas.AppImage && chmod +x Agentlas.AppImage && ./Agentlas.AppImage

$r = Invoke-RestMethod https://api.github.com/repos/agentlas-ai/agentlas-desktop-releases/releases/latest
$u = ($r.assets | Where-Object { $_.name -like '*Windows-x64-Setup.exe' }).browser_download_url
Invoke-WebRequest $u -OutFile "$env:TEMP\AgentlasSetup.exe"; Start-Process "$env:TEMP\AgentlasSetup.exe"

This is a separate product from the CLI runtime installed via Paste to Install above — the two don't conflict and can both be present. If your user only wants the CLI/router (no GUI app), use that installer instead. No prebuilt asset for your OS/arch? Point your user at agentlas.cloud/desktop or the Releases page.

An agent you create should remain an asset you can move, rather than a setting trapped in one chat, one model-vendor workspace, or one computer. Agentlas separates three jobs that ordinary agent builders blur together:

This is the public Agent Trust contract: a portable, owner-scoped, inspectable, and restorable package contract—not a claim of regulated financial or legal trust services.

| Value | What Agentlas does | Entry point in an external LLM host | | --- | --- | --- | | Build | Compiles a plain-language request into a runnable single-agent or team package with roles, tools, memory boundaries, permissions, routing, and verification contracts. | /agentlas build | | Use | Finds free public Hub agents and brings the selected runtime bundle into your current Agentlas host. The publisher's private source work is not copied into your workspace. | /agentlas hub (Hub only) or /agentlas network (Local + Cloud + Hub) | | Own | Keeps agents you create in a private, owner-scoped Agent Cloud so you can retrieve and call them again after changing models or computers. | Choose private Agent Cloud at /agentlas upload, then retrieve with /agentlas cloud |

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.

Turn a working session into an owned agent

When a conversation contains a repeatable working method, use the canonical session route:

hep-build session

In an interactive host, the current visible conversation is the source. Agentlas asks for the destination first; if you do not name another folder, it creates a new safe-slug child below AGENTLAS_AGENT_HOME or, by default, ~/.agentlas/agentlas-agent. Existing children are never overwritten. It then shows a generalized session report for your review, turns the approved method into a standalone agent prompt and package, registers it locally, and runs the normal verification gates.

You do not need to export JSON for this interactive route. JSON/JSONL remains an explicit option for terminal, replay, and headless workflows only. The default output is a single agent; choose a team explicitly. Raw transcripts, hidden prompts, credentials, private paths or URLs, screenshots, and literal tool arguments/results are not carried into the generated package. Uploading to Agent Cloud or the public Hub is a separate, explicit choice. See the session build contract for the deterministic export boundary.

current conversation
  -> destination question
  -> generalized session report
  -> owner review
  -> standalone agent/package
  -> local registration and verification

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:

| layer | what it is | who supplies it | |---|---|---| | LLM | the worker: reasoning, language, general knowledge | you (BYOM) | | Runtime | the facilities: read the web, write files, run a shell, drive a browser | the host machine | | Agent | the work manual: procedure, judgement rules, source priority, input/output contracts, stop conditions | the package |

"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 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",

1. Sentences stay sentences. No field that holds an author's sentence may be

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.

| field | what it holds | where it comes from | |---|---|---| | statement | the author's own sentence about the work | the routing card, carried whole | | deliverables[].label / .contains | what the requester ends up holding, and what is inside it | contracts/output.schema.json — the title and its property names | | deliverables[].shape | ledger / verdict / dossier / computation / blueprint / rendition / other | computed from the output schema's topology — arity and value spaces, never a title or a filename | | deliverables[].rowVerdict / .verdictValues | the per-record judgement and its allowed values | copied verbatim from the publisher's own enum; there is nothing to match them against, so no value is ever rejected | | obligations[].about / .stage | a fact the requester must supply, and when it comes to exist | contracts/intake.schema.json and the card's stated inputs | | authority.performs / .gated | what this method does to the requester's world, and what it stops to ask about first | derived from the approval requirements, not from what the package calls itself | | host[].capability / .withoutIt | what the machine must be able to do, and what still happens when it cannot | .agentlas/mcp-policy.json | | provenance | per field: extracted, read, graded or absent | written by the compiler |

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.

Hub and Agent Cloud are different scopes

| Surface | What it contains | What it is for | | --- | --- | --- | | Agentlas Hub | Public packages from creators and teams | Discover and use public agents for free with /agentlas hub; /agentlas network federates Hub with Local and owner Cloud. Publish only through an explicit public-Hub choice. | | My Agent Cloud | Only the signed-in owner's Cloud packages | Privately store, restore, and call packages you own with the /agentlas upload Cloud choice and /agentlas cloud. | | Current host | The installed runtime, chosen model, local project, credentials, and granted permissions | Execute the selected local, Cloud, or Hub package. |

Agentlas maps agent work to operating-system-like responsibilities without forcing your work into one model provider:

| What it handles | Implementation in Hephaestus | | :--- | :--- | | Kernel / Policy Gate | Deterministic router + security gates. Every routing action yields an auditable receipt; tool execution permissions are enforced by the active host and runtime. | | Processes / Threads | Independent agents and multi-agent teams compiled as packages with explicit, typed contracts (Routing Cards, anti-scopes, memory boundaries, and verification shims). | | Scheduling | The Workforce pipeline: a typed work order, federated candidate retrieval across Local, Cloud and Hub, a host-authored selection, and pinned execution — combined with Stormbreaker's parallel execution fabric and append-only run journals. Ratings, install counts and usage history are forbidden as routing authority. | | Memory Management (MMU) | Two-boundary governed memory: local project memory remains isolated on the machine, while durable promotions are gated by a local Memory Curator. | | Virtual File System | Production Ontology Runtime: local-first source ingestion, CJK trigram FTS5 search, hybrid Reciprocal Rank Fusion, and GraphRAG retrieval. | | Inter-Process Call (IPC) | A2A Agent Card Boundary (cryptographic import/export and caller-gating) + Model Context Protocol (MCP) tool registrations. | | Package Manager | Agentlas Hub for free public publishing and use; owner-scoped Agent Cloud for private package storage and retrieval. Neither is a server-side model executor. | | Shell Interface | A small, unified command set in external client runtimes; plain-language intent routing in native Agentlas shells. | | Process Initialization | Meta-Agent Factory with an integrated Briefing Interview Gate—specifying agent parameters before compiling code. |

_{Figure 1. Request shaping, four builders, generated package contracts, memory curation, skill lifecycle, runtime adapters, and sync boundaries.}

Agents generated from vague, single-sentence prompts fail under real-world edge cases. Hephaestus v1.1.0 positions task specification as a first-class OS service through the Briefing Interview Engine:

The current v1.2.54 release carries the resolved Work Brief through host-owned Network 2.0 selection, exact release pinning, and server-first tool discovery.

• Quantitative Ambiguity Gates: The compilation scheduler evaluates prompt clarity across four key vectors (Goal, Constraints, Scope, Context). The build process is strictly gated until the ambiguity score passes a numeric threshold (ambiguity score $\le 0.2$, with per-dimension safety floors). Clear prompts bypass the interview loop entirely via a budget system that caps questions for trivial tasks.

• The Work Brief: Resolved details are frozen into .agentlas/work-brief.json—recording the validated goal, concrete constraints, an assumption ledger with source tags, and the metadata ambiguity score.
• Contextual In-Flight Briefs: The CLI tool cards migrate automatically maps brief details directly to triggers and anti-triggers on the agent's routing card. Running route --brief propagates this brief to all Stormbreaker execution packets, ensuring constraints and exit conditions govern parallel subprocesses across the entire lifecycle.
• Enhanced Routing Discrimination: Prevents same-topic/different-intent collision (e.g., a security agent intercepting a deployment prompt) via double-sided gating: interview-validated anti-triggers on the routing card, and low-confidence LLM re-ranking escalation inside the router.

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.

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:

| Session language | Agent route example | Host-skill adapter example | | --- | --- | --- | | English | Agents used: . Reason: . | Skills used: . Reason: . | | Korean | 사용 에이전트: . 이유: . | 사용 스킬: . 이유: . |

Global router command reference:

| Command | What it does | | --- | --- | | hephaestus global install | Install or refresh the managed router block for Codex, Claude Code, and Antigravity/Gemini. | | hephaestus global status | Show whether each runtime file has the managed router block. | | hephaestus global remove | Remove only the managed Hephaestus router block. Existing user content stays in place. | | hephaestus global install --target codex | Install only ~/.codex/AGENTS.md. | | hephaestus global install --target claude | Install only ~/.claude/CLAUDE.md. | | hephaestus global install --target antigravity | Install only ~/.gemini/GEMINI.md, which Antigravity shares with Gemini CLI. | | hephaestus global install --target codex --target claude --target antigravity | Explicitly install all supported targets. | | hephaestus global install --dry-run | Preview what would change without writing files. | | hephaestus global install --no-backup | Edit without writing a timestamped .bak.* file. | | hephaestus global install --home /tmp/test-home | Test against another home directory. Useful for installer QA. | | hep-global install | The original spelling of the same command. Still supported. | | ~/.agentlas/runtime/current/bin/hephaestus global status | Use the installed runtime directly when shell shims are not on PATH. |

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.

Per-Runtime Plugin Drivers

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

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

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. To connect Telegram, use /agentlas connect.

One word to remember: everything starts with agentlas — /agentlas in an LLM host, agentlas in a shell.

Inside native Agentlas environments, Hephaestus operates commandless. External LLM tools use a deliberately small visible command set. System-level utilities like Stormbreaker, research loadouts, and configuration tables attach automatically from context:

| System Subsystem | Command | Example | | :--- | :--- | :--- | | Agent / Team Builder | /agentlas-build (or /agentlas build, /hep-build) | /agentlas-build create a customer support agent for Shopify refunds | | Session-to-Agent Builder | /hep-build session (canonical route: hep-build session) | /hep-build session | | Workforce Federation (Local + Cloud + Hub) | /agentlas-network (or /agentlas network, /hep-network) | /agentlas-network split this launch plan into research, copy, QA, and release agents | | Stormbreaker Loop | /agentlas-storm (or /agentlas storm, /hep-storm) | /agentlas-storm build full-stack saas landing page | | Graph Automations | /agentlas-graph (or /agentlas graph, /hep-graph) | /agentlas-graph create daily market summary automation | | Personal Agent Mode | /agentlas-one on|off (or /agentlas one on|off, /hep-one on|off) | /agentlas-one on | | Registered Local Agents Only | /agentlas-local (or /agentlas local, /hep-local) | /agentlas-local use only agents registered on this machine | | Owned Cloud Agents Only | /agentlas-cloud (or /agentlas cloud, /hep-cloud) | /agentlas-cloud use my saved finance analyst agent to review this report | | Public Hub Agents Only | /agentlas-hub (or /agentlas hub, /hep-hub) | /agentlas-hub find public specialists for accessibility QA | | Directory Search | /agentlas-search (or /agentlas search, /hep-search) | /agentlas-search find agents for a market report workflow | | Browser Hardpoint | /agentlas-browser (or /agentlas browser, /hep-browser) | /agentlas-browser https://example.com | | Inter-Process Call (IPC) | /agentlas-call (or /agentlas call, /hep-call) | /agentlas-call market-researcher, report-writer {draft a market report} | | Cloud / Hub Destination Gate | /agentlas-upload (or /agentlas upload, /hep-upload) | /agentlas-upload ./agents/customer-support-hq | | Messenger / Channel Setup | /agentlas-connect (or /agentlas connect, /hep-connect) | /agentlas-connect Telegram for Marketing Agent Team | | Orchestrator / Worker Models | /agentlas-orch (or /agentlas orch, /hep-orch) | /agentlas-orch orchestrator=frontier worker=economy | | Runtime + Adapter Update | /agentlas-update (or /agentlas update, /hep-update) | /agentlas-update |

/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 su

... (README truncated for length)