Local-first agent & plugin networking: call your agents from any AI runtime, route by standardized cards, keep memory on your machine.

Turn one rough agent idea into an installable Agentlas agent or team repository — then let the Hephaestus Network route every request to the right local agent, with Hub fallback only on your approval.

English · 한국어 · 中文 · 日本語 · हिन्दी

Paste Install · Quickstart · Where To Type · Visual Install Guide · What It Builds · Architecture · Compare · Desktop

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

_{Figure 2. Hephaestus Network 2.0 — runtimes, the global local-first orchestrator, routing cards, approval gates, local memory, and the Agentlas Hub A2A/MCP fallback.}

One command, every runtime, all local:

/hephaestus-network turn these meeting notes into a weekly report
/hephaestus-network draft a launch plan for my product
@Hephaestus organize and summarize this folder of documents   # runtimes without slash commands
hephaestus "find the right agent for this task"               # terminal

• Routing cards. Every agent, team, and plugin ships a standardized routing card (triggers, anti-triggers, capabilities, risk profile, memory behavior). Cards that fail the quality gates are never auto-routed.
• Local first. Explicit commands → project overrides → your local cards. The Agentlas Hub is a fallback that always asks before first remote use, and only ever receives redacted keywords — never your raw prompt.
• Memory stays local. Agent capability can come from the Hub; your user/project memory lives in ~/.agentlas/networking/ and never leaves the machine without an explicit export approval.
• Receipts and approval gates. Every routing decision writes a receipt; file writes, cloud calls, payments, publishing, deletion, private data export, and external tools always require your approval.
• Measured, not claimed. A routing benchmark (Korean + English) gates auto-routing: top-3 recall ≥ 90%, zero unsafe routes in the privacy suite.

Details: docs/hephaestus-network-2.0.md · runtime support matrix: docs/runtime-fallback-adapters.md

New to terminals? Don't run anything yourself. Open any AI coding tool — Claude Code, Codex, Gemini CLI, Antigravity, or Cursor — and paste the message below into its chat box. The agent runs the installer for you, then tells you the exact command to use next:

Set up the Hephaestus Agentlas meta-agent in this workspace. Run
`curl -fsSL https://raw.githubusercontent.com/agentlas-ai/Hephaestus/v0.4.4/scripts/install-all-runtimes.sh | bash`
in the terminal, then tell me the exact /hephaestus command for the tool I am
using (Claude Code, Codex, Gemini CLI, Antigravity, or Cursor). If anything
fails, read the error, fix it, and retry.

When it finishes, type /hephaestus in your tool. Prefer to run the commands yourself? Use the terminal Quickstart below.

Use one of these paths on a new computer. Start with a Claude Code or Codex plugin install unless you only want the package files copied into a normal project folder.

Claude and Codex plugin marketplace commands use git clone. On a fresh Mac, git requires Apple's Command Line Tools. If you see xcode-select: note: No developer tools were found, run this once:

xcode-select --install

Finish the Apple installer popup, open a new Terminal window, then verify:

git --version

After git --version works, rerun the Claude or Codex plugin install command.

Run this from your normal OS terminal. It installs or updates the runtime-neutral runner (~/.agentlas/runtime/current), the universal AgentSkills skill (~/.agents/skills/hephaestus-network), the Claude Code plugin, Codex plugin + custom prompts + local MCP, Gemini CLI extension/custom command, Antigravity workflow, and — when detected — Cursor, OpenCode, OpenClaw, and Hermes Agent surfaces. It also fixes the common Already added from a different source marketplace conflict by removing the old agentlas-core-engine entry and adding it again from this repo.

curl -fsSL https://raw.githubusercontent.com/agentlas-ai/Hephaestus/v0.4.4/scripts/install-all-runtimes.sh | bash

After it finishes, restart any open runtime sessions. Then use:

Claude Code: /reload-plugins, then /hephaestus ontology
Codex:       /prompts:hephaestus-network, or the $hephaestus-network skill
Gemini CLI:  /extensions list or /commands list, then /hephaestus
Antigravity: reopen the workspace, then /hephaestus
Cursor:      /hephaestus-network (command + skill)
OpenCode:    /hephaestus-network
OpenClaw:    /skill hephaestus-network <request>
Hermes:      hephaestus-network skill (+ MCP, hermes/README.md)
Ollama/Gemma/DeepSeek local models: docs/local-models.md

Use the same command again to update to the packaged ref. To force a different ref:

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

Open your normal OS terminal, not the Claude chat box, and run:

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

Then open or restart Claude Code in the project you want to work on and type:

/reload-plugins
/hephaestus ontology

If you already installed the old agentlas-meta-agent plugin and Claude says hephaestus is not found, refresh the marketplace and replace the old plugin:

curl -fsSL https://raw.githubusercontent.com/agentlas-ai/Hephaestus/v0.4.4/scripts/install-all-runtimes.sh | bash

/hephaestus ontology opens a local SaaS-style ontology dashboard for the current project. The dashboard has a left navigation rail, an Obsidian-style knowledge graph, source search, a GraphRAG query builder, a Memory Candidate Queue, and copyable commands. It creates these files in that project only:

.agentlas/ontology-inbox/
.agentlas/ontology-sources.json
.agentlas/ontology-runtime.sqlite
.agentlas/ontology-gui/index.html

It does not scan your home folder or sibling projects. Put approved company docs inside .agentlas/ontology-inbox/, then run /hephaestus ontology again to refresh the dashboard.

To create agents or teams after install:

/hephaestus create a research agent for SEC filing analysis
/hephaestus create a customer support operations team
/hephaestus package this existing Claude agent into Agentlas architecture

Claude also supports claude plugins ... as an alias, but this README uses claude plugin ... everywhere so the command shape stays consistent.

Open your normal OS terminal, not the Codex chat box, and run:

codex plugin marketplace add agentlas-ai/Hephaestus --ref v0.4.4
codex plugin add hephaestus@agentlas-core-engine

Then open or restart Codex in the project you want to work on and type:

/hephaestus ontology

If Codex still shows agentlas-meta-agent, refresh the marketplace and replace the old plugin:

curl -fsSL https://raw.githubusercontent.com/agentlas-ai/Hephaestus/v0.4.4/scripts/install-all-runtimes.sh | bash

The Codex OS-terminal CLI command is singular: codex plugin, not codex plugins. Inside the Codex app, the slash command for the plugin browser is plural: /plugins. After plugin install, /hephaestus ontology creates and opens the same project-local dashboard with graph, sources, query, memory queue, and command views:

.agentlas/ontology-gui/index.html
To create agents or teams after install:

```text
/hephaestus create a self-evolving research agent
/hephaestus create a finance analyst team
/hephaestus package this existing Codex workspace into Agentlas architecture

Every generated or packaged Agentlas agent receives a global command during creation. The final handoff must include global_commands for Claude Code, Codex, Gemini CLI, generic AGENTS.md tools, and terminal use. For a team, that public command routes to the orchestrator/HQ.

Run these local checks before uploading an existing agent to Agentlas Cloud or publishing a clean copy to the Hub:

bin/hephaestus wizard ./some-agent --name instagram-operator
bin/hephaestus security scan ./some-agent --strict
bin/hephaestus runtime bundle ./some-agent
bin/hephaestus runtime read-agent-file ./some-agent AGENTS.md
bin/hephaestus field-test

The wizard creates agentlas.json, the scan writes .agentlas/security-scan.json, and the runtime bundle uses manifest allowlists instead of sending an entire ZIP to the model.

Use this if you are not installing the Claude/Codex plugin and just want the repo package files in your current project. Open macOS Terminal, Linux terminal, Windows Git Bash, or WSL in that project folder and run:

curl -fsSL https://raw.githubusercontent.com/agentlas-ai/Hephaestus/v0.4.4/scripts/install.sh | bash
scripts/verify-package.sh
scripts/public_safety_check.sh

Windows PowerShell:

$zip = "$env:TEMP\hephaestus-v0.4.4.zip"
$extract = "$env:TEMP\hephaestus-v0.4.4"
Invoke-WebRequest "https://github.com/agentlas-ai/Hephaestus/archive/refs/tags/v0.4.4.zip" -OutFile $zip
Remove-Item $extract -Recurse -Force -ErrorAction SilentlyContinue
Expand-Archive $zip -DestinationPath $extract -Force
$src = Get-ChildItem $extract -Directory | Select-Object -First 1
Get-ChildItem $src.FullName -Force | Copy-Item -Destination (Get-Location) -Recurse -Force

After file install, run the ontology GUI directly:

bin/hephaestus ontology

Use this only when you are already inside Claude Code and want to install from the Claude chat UI instead of the OS terminal.

Claude Code chat:

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

Codex does not accept /plugin marketplace add inside the app. In Codex, install from the OS terminal with codex plugin ..., then restart Codex and use /plugins only to browse or enable installed plugins. After Hephaestus is installed, run /hephaestus ontology.

If a Claude chat session does not show the new command after install, restart Claude Code in that project.

Use the Claude slash-command image only when you are already inside Claude Code. For Codex, install from the OS terminal; inside the Codex app, use /plugins to browse installed plugins.

Type these commands directly into Claude Code:

Use this path when the claude command is available in your shell:

Use this only after the OS-terminal codex plugin ... install:

Use this path when Codex shows a Plugins settings screen:

Use this path when the codex command is available in your shell:

Installation also registers the agentlas Hub MCP for you — Claude Code gets it from the bundled .mcp.json, Codex/Antigravity from the one-touch install script, and Gemini CLI from the extension manifest. No separate MCP setup needed.

/hephaestus is for building agents. To find and pull in agents that already exist, talk to the MCP in plain language as below.

You never call MCP tools directly. Just say what you want and the AI picks the right tool.

To verify the registration:

• Just ask: "What agents are on agentlas?", "Recommend agents that could help me launch my app" — the search tools take it from there.
• Browse on the web: agentlas.cloud/marketplace
• Register the MCP manually in other clients (Cursor, Windsurf, VS Code, ...): agentlas.cloud/mcp

Hephaestus leaves behind a repository that another runtime can inspect, install, verify, and keep improving.

All three modes must create .agentlas/global-commands.json and report the exact global command after generation. The user should not have to infer how to run the new agent.

Generated or repaired packages can include:

AGENTS.md
CLAUDE.md
GEMINI.md
agent.md
agents/
skills/
modes/
.agentlas/
.agentlas/global-commands.json
.agents/
.claude/
.gemini/
.gemini/commands/
codex/
schemas/
templates/
scripts/verify-package.sh
scripts/public_safety_check.sh

The public core is the architecture and foldering contract. Runtime-specific folders are adapters over the same core, not separate sources of truth.

The default export state is conservative. Generated skills are searchable candidate metadata, not automatically promoted runtime behavior. A local Curator must see execution evidence, sealed holdout or replay proof, rollback coverage, and workspace policy approval before a skill becomes first-class recall.

For knowledge-heavy personal or company agents, Hephaestus now ships a real local-first ontology runtime under ontology/ with the executable CLI bin/ontology. It turns approved files into an agent-readable source archive, chunk store, full-text index, vector index, ontology graph, GraphRAG result, Memory Curator candidate ticket, and Agent Working Memory cache.

New in v0.4.4 — Hub invocation through Hephaestus Network MCP:

• hephaestus_hub_invoke MCP tool. Hephaestus Network now has a real Hub invocation surface, not only Hub candidate search. The tool skips local routing, calls Agentlas Hub MCP (marketplace.search_agents, agentlas.get_runtime_bundle, agentlas.resolve_plugins), and writes execution receipts under ~/.agentlas/networking/ledgers/executions.jsonl.
• Hub-only local bypass. hub_only routing and Hub invocation can be used with local_inventory: [] and reject_paid_slug: true so local Paid/Free/plugin cards are not selected or executed.
• Global Agentlas memory bootstrap. Hub invocation can create the missing shared files under ~/.agentlas/ (memory-map.json, project-soul-memory.md, invocation-ledger.jsonl, etc.) and appends invocation evidence without storing raw prompts or secrets.
• Installed-runtime verification. The one-touch installer now verifies five runtime surfaces and keeps the neutral runner at ~/.agentlas/runtime/current/bin/hephaestus.

Ontology runtime upgrades:

• CJK search works. The tokenizer now emits character bigrams for Korean/Japanese/Chinese runs and the FTS index uses the trigram tokenizer, so Korean corpora (proposals, contracts, and quotes in HWPX and Office formats) are searchable with zero install. Existing databases migrate and re-index automatically on first open.
• RRF hybrid ranking. Full-text and vector rankings fuse via Reciprocal Rank Fusion instead of mixed-scale fixed weights, on a bounded candidate pool (no full-corpus Python scan).
• Host-LLM search hooks (optional, zero extra cost). A host CLI runtime (Claude Code / Codex) can inject query-expansion and rerank hooks — no embedding API or key needed. Chunks scoped private/confidential are never passed to cloud hooks; the gate is enforced inside the search pipeline.
• Chunk overlap. Sliding windows now overlap 15% so context is not cut at chunk boundaries.
• Ontology-backed agent mode. Builders can generate retrieval-first, citation-attached agents (see modes/ontology-backed-agent.md and the golden-path reference in examples/ontology-proposal-agent/), with governance contracts injected by rule and loop_policy (none / self-correct / verified) derived from task risk.
• Adapter drift gate + MCP surface check. scripts/sync-adapters.sh --check keeps runtime adapters byte-identical to the canonical core, and scripts/verify-mcp-surface.sh guards the agentlas MCP registration contract across Claude Code, Codex, Gemini, and Antigravity.

The Super Ontology files under .agentlas/ remain the safety/governance layer. They define the source-lineage, privacy, task-coverage, causal, consensus, and memory-write gates around the runtime. The runtime is the implementation layer.

In Agentlas Terminal and Desktop, the same runtime is exposed as agentlas ontology; in plugin-hosted tools, use /hephaestus ontology. The runtime never scans your home folder or sibling projects; it only ingests explicit approved paths, registered sources, and project-local inbox files.

Supported ingest formats:

The storage default is SQLite at .agentlas/ontology-runtime.sqlite, ignored by Git. The schema includes sources, source_lineage, chunks, chunk_fts, entities, entity_aliases, relations, memory_candidates, memory_candidate_events, working_memory, runtime_adapters, and schema_migrations.

Basic local run:

bin/ontology ingest examples/ontology-corpus --scope internal
bin/ontology query "Project Helios Memory Curator" --agent verifier
bin/ontology graph entity "Project Helios"
bin/ontology memory candidates
bin/ontology working-memory read --agent verifier
bin/ontology verify

The query response includes relevant chunks, related entities, relation edges, evidence refs, source spans, confidence, Memory Curator candidate suggestions, and optional Agent Working Memory writes. It is not a vector-only result.

The runtime stack is layered:

Memory Curator flow:

bin/ontology memory candidates
bin/ontology memory decide <ticket-id> approve --reason "Curator accepted source-backed fact"
bin/ontology memory decide <ticket-id> quarantine --reason "Needs source owner review"

Approval records review state but still does not write durable memory. The Memory Curator owns durable promotion. Agent Working Memory is intentionally a cache, not a source of truth.

See docs/ontology-runtime.md for the schema, adapter behavior, storage commands, and verification coverage.

Desktop and Terminal make this package useful beyond a static prompt:

• Desktop shows the agent/team structure, local projects, Apps, vault references, and runtime choices.
• Terminal runs the same package from a shell with agentlas.
• The built-in Core Engine Meta-Agent path means fresh Desktop/Terminal installs can create or package agents without a separate standalone plugin install.
• Standalone Claude/Codex install is still useful when you want this package directly inside those runtimes.

OpenAI and Claude are model/runtime surfaces. OpenClaw and Hermes are local-agent experiences. Hephaestus is the package layer that makes agents portable, inspectable, installable, and publishable.

Single agent:

/meta-agent Create a research agent for SEC filing analysis.
Package it for Codex, Claude Code, Gemini, and Agentlas Desktop.

Multi-agent team:

Use Hephaestus.
Build a customer-support operations team with PM Soul, Memory Curator, Policy Gate, QA, eval, and public-safe release checks.

Package an existing workspace:

Package this local OpenClaw/Hermes-style workspace into Agentlas architecture.
Keep private notes, machine paths, raw logs, and secrets out of the public repo.

This repo intentionally does not include hosted Agentlas billing/account logic, production credentials, customer data, raw private logs, raw transcripts, desktop keychain storage, local database implementation, or private deployment configuration.

Public output packages should not include local machine paths, API keys, tokens, private keys, service-account JSON, .env secrets, private research notes, raw chat transcripts, customer logs, hosted billing/account/OAuth internals, or desktop storage internals.

Before opening a PR or publishing a release, run:

scripts/verify-package.sh
scripts/verify-ontology-runtime.sh
scripts/public_safety_check.sh

Apache-2.0. See LICENSE.