Skip to main content
Glama

Aitherium Agent Pack — ForgePilot

ForgePilot is a hackathon-ready agent pack for building and shipping agent integrations from wherever the work already happens.

The hackathon demo is deliberately self-referential: it shows the process used to build this pack. A plain-language request becomes research, a local aw* bootstrap plan, a scoped identity/policy boundary, desktop connectors, a phone PWA, and a shareable artifact.

It gives you one local runtime with four surfaces:

  • an Aitherium/awdk pack and fleet definition;

  • a small MCP server for Codex, Claude Desktop/Code, ChatGPT-compatible MCP clients, and any MCP host;

  • a WebMCP-enabled control room for browser agents;

  • generated OpenRouter and Exa adapter configs.

The demo story is simple: ask ForgePilot to research an API or integration, get grounded Exa sources, then produce a portable setup bundle for the coding client you are using.

The larger hackathon story is Agents Everywhere: bootstrap/AGENT_EVERYWHERE.md walks a new builder from zero to awdk, Bonsai/local inference, MCP, awsh, desktop, and secured remote connections.

Backend switching is a first-class path too: run bash bootstrap/switch-claude-backend.sh code (or the PowerShell equivalent) to use adk claude-model code for the DeepSeek Flash coding profile, then verify with adk claude-model check. The pack exposes the same plan through forgepilot_backend_switch_plan.

The pack is also designed to be opened alongside Aitherium Studio: use pack.yaml as the identity/tool contract, fleet.yaml as the orchestration view, and the control room as the browser-native demo surface. Use SHAREABLE_PACKS.md when you want to turn a new idea into a portable MCP + WebMCP + PWA tool that other builders can apply.

Quick start

Windows

Set-ExecutionPolicy -Scope Process Bypass
./setup.ps1

macOS/Linux

chmod +x setup.sh
./setup.sh

The setup script creates .venv, installs this project plus the aw* acceleration and authorization bricks, writes .env, and emits client config snippets under integrations/generated/. For an offline demo-only install, set SKIP_AWSDK=1.

Add EXA_API_KEY for live research and OPENROUTER_API_KEY for model-backed chat. The app still starts without either key in demo mode, so the control room and MCP handshake can be shown offline.

Start the control room:

python -m aitherium_pack serve

Open http://127.0.0.1:8787.

GitHub Pages

The repository ships an automated static deployment. Enable Settings → Pages → GitHub Actions, then push main. The pages.yml workflow builds the PWA and deploys it to the repository's Pages URL; verify.yml tests every pull request and checks the Pages bundle. The hosted page is a client only: configure its MCP endpoint to your own authenticated HTTPS ForgePilot/Aitherium node. See DEPLOY.md for CORS, token, and repository-variable setup.

Or create a durable run artifact directly:

python -m aitherium_pack run "Design a safe Codex and Claude MCP integration for this project"

That writes artifacts/runs/<run-id>/ with research.json, response.json, report.md, stack.json, and a SHA-256 manifest.json.

If you want the native Aitherium fleet server after setup:

adk-serve --fleet fleet.yaml --port 8080

Related MCP server: mcp-project-helper

What is included

pack.yaml                         awdk-style pack metadata
fleet.yaml                        awdk fleet definition
aitherium_pack/
  cli.py                          one-command setup/serve/config generation
  server.py                       stdlib HTTP + MCP JSON-RPC server
  providers.py                    Exa and OpenRouter adapters
  config.py                       generated client config helpers
  web/index.html                  ForgePilot control room + WebMCP tools
skills/                           portable pack skills
integrations/                     checked-in examples and generated snippets

Desktop integrations

The generated files are intentionally plain JSON snippets so they can be copied into the client of choice:

  • Claude Desktop / Claude Code: integrations/generated/claude.mcp.json

  • Codex-style MCP clients: integrations/generated/codex.mcp.json

  • ChatGPT or any remote MCP client: integrations/generated/remote-mcp.json

For a local stdio client, the server command is python -m aitherium_pack mcp. For a remote client, expose the HTTP server through a trusted tunnel and use /mcp. The HTTP server binds to loopback by default; non-loopback mode requires FORGEPILOT_MCP_TOKEN plus an explicit trusted-LAN flag. CORS is origin-allowlisted and request bodies are bounded.

awdk connection

The pack is shaped for the current awdk workflow: pip install awdk, adk install pack:..., a named identity, and a fleet YAML. When awdk is installed, python -m aitherium_pack install-awdk --cloud runs the native cloud quickstart path and leaves this pack as the project-owned integration layer. The local MCP server remains dependency-light so the hackathon demo can run even before a full model backend is configured.

Identity and capability boundary

The device-flow and local-stack plans are designed around the Aitherium front door: awnboard receives the request, awiam identifies the caller/session, awbac makes a fail-closed capability decision, awdit records it, and awtunnel handles private reachability. Only after approval does awsh/awdk reach Bonsai-27B, awm, awrepl, awgraph, awgit, or ForgePilot MCP.

Safety boundary

ForgePilot’s first-party tools are read-only: health, web research, grounded chat, and config generation. Research results are marked untrusted before entering the model prompt. No email, purchase, file mutation, shell, or browser-navigation tool is exposed by default.

Sources

Available Tools

12 tools
forgepilot_backend_switch_planB

Show the safe adk/awsettings plan for switching Claude Code to a provider such as DeepSeek Flash. Read-only.

Inputs: profile.

forgepilot_chatC

Answer an integration question using optional Exa evidence through OpenRouter. Read-only.

Inputs: message (required), evidence.

forgepilot_community_bridge_planB

Show the safe ARC, awgym, awrelay, Relay, Forums, Spaces, and AwDesk connection plan. Read-only.

Inputs: no named parameters.

forgepilot_create_artifactB

Create a timestamped, read-only integration run bundle with evidence, response, report, and SHA-256 manifest.

Inputs: request (required).

forgepilot_create_community_bridge_packC

Create a no-secrets community bridge artifact for ARC, awgym, awrelay, Relay, Spaces, and AwDesk.

Inputs: name.

forgepilot_create_connector_artifactB

Generate runnable Claude Code and Codex MCP configs plus bootstrap scripts for the current local checkout.

Inputs: no named parameters.

forgepilot_create_shareable_packC

Scaffold a portable MCP + WebMCP + PWA agent tool pack with awnboard/awiam/awbac/awdit metadata.

Inputs: name (required), description (required).

forgepilot_generate_configB

Generate portable MCP client configuration snippets. Read-only.

Inputs: no named parameters.

forgepilot_healthB

Return the local ForgePilot runtime status. Read-only.

Inputs: no named parameters.

forgepilot_local_acceleration_planB

Inspect local aw* command/package presence and return the Bonsai model activation plan for Codex and Claude Code. Read-only.

Inputs: model.

forgepilot_start_device_flowC

Create a consent-scoped Aitherium device-flow handoff for local inference, MCP, workspace, and LAN capabilities. No token is returned.

Inputs: scopes.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 12 tools

    Disambiguation3/5

    Several tools generate configs or artifacts (generate_config, create_connector_artifact, create_artifact, create_shareable_pack, create_community_bridge_pack) with overlapping 'create' verbs, and chat/search both use Exa, so misselection is possible despite descriptive text.

    Naming Consistency4/5

    All tools use the forgepilot_ snake_case prefix, but four tools are noun-phrase plans (local_acceleration_plan, backend_switch_plan, community_bridge_plan) while the rest use verb or verb_noun patterns, a minor deviation.

    Tool Count5/5

    12 tools is well within the ideal 3-15 range and each tool maps to a distinct ForgePilot integration task (health, search, config, artifacts, plans), so the count is appropriate.

    Completeness3/5

    The surface covers many one-way generation/planning tasks but lacks lifecycle operations: no list, get, update, or delete for artifacts/packs, and device flow has only a start tool with no completion/poll tool.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Lets ChatGPT, Claude Desktop, Claude Code, and other MCP clients run an allowlisted set of local commands and read files from a chosen directory, so an assistant can analyse a codebase or trigger local generators (images, sprites, assets) without metered API tokens. The server is read-only and deny-by-default by default, with no shell, path containment, opt-in writes, and required auth when exposed over HTTP.
      3
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes MCP tools that give desktop agents durable two-tier memory with recall and graph traversal, project code intelligence (symbol lookup, impact walking, notes search), and web search with page-to-Markdown conversion. It also runs a local model gateway that routes Anthropic- and OpenAI-shaped traffic across providers with usage accounting.
      MIT