HexForge Gateway

AI-assisted APK reverse-engineering workspace API. Dispatches tasks to MCP agents (jadx, apktool, adb, frida, filesystem, MT Manager's APK MCP, AI providers) and streams updates over WebSocket. Runs entirely on-device (Termux + MT Manager on Android) or on a normal PC - no cloud required.

Flow: Workspace -> Workflow -> Jobs -> Tasks -> MCP Agents, with modules talking through an Event Bus. MIT licensed. Contributing: run npm run typecheck && npm run build && ./scripts/smoke-test.sh before a PR - see CONTRIBUTING.md.

Getting started

npm install
cp .env.example .env
npm run dev

The Gateway starts on http://localhost:8080 and prints a banner with your workspaces and copy-pasteable commands. GET / returns the same as JSON - the quickest way to see what's here.

Core endpoints (request/response shapes are in the linked docs):

• GET / - live cheat sheet - GET /health - service + config status
• POST /workspaces / GET /workspaces[/:id] / PUT /workspaces/by-name/:name (idempotent get-or-create)
• POST /workspaces/:id/tasks - dispatch to an MCP agent, fire-and-forget; poll or watch /ws (AGENTS)
• POST /workspaces/:id/jobs / /workflows / /knowledge (ARCHITECTURE)
• GET /workspaces/:id/inbox - APKs dropped into APK_INBOX_DIR, if configured, and auto-claimed into this workspace (INBOX)
• POST|GET /workspaces/:id/chat (AI)
• GET /plugins (PLUGINS)
• WS /ws - real-time task:update, job:update, workflow:update, knowledge:entry_created, workspace:status_changed for every workspace
• WS /ws/workspaces/:id - same events, filtered to one workspace

Stack

Node.js 22+ / TypeScript, Fastify (+ @fastify/websocket), Zod. Storage is local files by default; Supabase is opt-in (STORAGE_BACKEND=supabase). Auth is an opt-in API key check, off by default (AUTH_ENABLED=false). npm test runs the Vitest unit suite (retry/failure-path logic, no live instance needed); scripts/smoke-test.sh covers end-to-end happy paths against a running Gateway - see tests/README.md for the split.

Documentation

Doc	Covers
docs/SETUP.md	Requirements, auth, storage backend, running on PC and Android/Termux
docs/ARCHITECTURE.md	Event Bus, Job Engine, Workflow Engine, Knowledge Engine
docs/AGENTS.md	Every MCP agent - operations and examples
docs/AI.md	The AI provider layer (9 providers), the ai agent, Terminal chat
docs/MCP_SERVER.md	Registering HexForge's agents as native tools in Claude Desktop/Code/Cursor
docs/PLUGINS.md	The Plugin System - contract, loader, reference plugins
docs/CLI.md	the hf CLI (scripts/hf.sh) and scripts/smoke-test.sh
docs/MT_MANAGER.md	MT Manager's APK MCP setup, with screenshots and troubleshooting
docs/PROJECT_STRUCTURE.md	Repo layout and how the pieces talk
docs/ROADMAP.md	What's done and what's still open