Hexforge Gateway

HexForge Gateway

= 20">

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)
• GET /capabilities - what the Gateway can do and which agents provide it (AGENTS)
• GET /workspaces/:id/artifacts / GET /artifacts/:id - directories and files finished tasks produced, with the run that made them (ARCHITECTURE)
• POST/GET /workspaces/:id/findings (filter by status or a cited entityId), GET/PATCH /findings/:id, GET /findings/:id/verification - claims with evidence checked against real artifacts and graph entities, and re-checked against the cited files (ARCHITECTURE)
• POST/GET /workspaces/:id/graph/entities, GET /graph/entities/:id, POST/GET /workspaces/:id/graph/edges - typed entities and relationships observed about the target (ARCHITECTURE)
• 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