Menu
AX project architecture and coding skills - use sub-skills for specific subsystems (agent, host, cli, providers, etc.)
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when modifying logging, error handling, or diagnostic messages — logger setup, transports, error diagnosis patterns in src/logger.ts and src/errors.ts
Use when modifying the trusted host process — server orchestration, message routing, IPC handler, request lifecycle, event streaming, file handling, plugin loading, or agent delegation in src/host/
Use when modifying the sandboxed agent process — runner, IPC client, local/IPC tools, tool catalog, prompt building, or identity loading in src/agent/
Use when modifying agent sandbox isolation -- Docker, Apple Container (macOS), or k8s providers in src/providers/sandbox/
Use when modifying IPC protocol between host and agent — schemas, actions, length-prefix framing, or Zod validation in ipc-schemas.ts and ipc-server.ts
Use this skill when the user asks for a capability the agent doesn't yet have — a new integration (Linear, GitHub, Notion, Slack, etc.), a new workflow, a new tool, or "can you check our team's X" where X is a service the agent has no existing connector for. Creates a proper AX skill under .ax/skills/<name>/ with the right frontmatter, credentials, and domain allowlist so the capability becomes permanent after admin approval. Use this skill whenever you'd otherwise be tempted to improvise with one-off scripts, `npm install`, or `execute_script` to reach an external service.
| name | ax |
| description | AX project architecture and coding skills - use sub-skills for specific subsystems (agent, host, cli, providers, etc.) |
This is the parent skill group for all AX project-specific architecture and coding skills. Use the appropriate sub-skill for the subsystem you're working on.
AX uses a provider contract pattern. The trusted host process (src/host/) orchestrates sandboxed agent processes (src/agent/) via IPC, with a plugin system (src/plugins/) for extensibility. Every subsystem is a TypeScript interface with pluggable implementations, loaded from a static allowlist in src/host/provider-map.ts (SC-SEC-002).
Agent isolation uses a unified container model with three sandbox providers:
| Provider | Platform | IPC Transport | Notes |
|---|---|---|---|
docker | Any | Unix socket | Container isolation via Docker |
apple | macOS | Unix socket (reverse bridge) | Apple Container framework |
k8s | Kubernetes | HTTP (IPC + work dispatch) | Session-long pods with HTTP-based IPC |
Old Linux-specific sandbox providers (seatbelt, nsjail, bwrap) and the subprocess dev fallback have been removed. The k8s provider uses HTTP for all communication — IPC (HttpIPCClient → POST /internal/ipc) and work dispatch (GET /internal/work). Session-long pods are managed by SessionPodManager and reused across turns. Pods cannot share a filesystem with the host.
Outbound HTTP via Web Proxy: Agents can optionally make outbound HTTP/HTTPS requests (npm install, pip install, curl, git clone) through a controlled forward proxy on the host. Opt-in via config.web_proxy (disabled by default). Containers keep --network=none — agents reach the proxy via a TCP bridge over a mounted Unix socket. The proxy enforces private IP blocking (SSRF), canary token scanning, and audit logging. K8s pods connect directly via a k8s Service (ax-web-proxy).
In k8s mode, all communication uses HTTP:
src/agent/http-ipc-client.ts → POST /internal/ipc route on host (src/host/server-k8s.ts)src/host/llm-proxy-core.ts → /internal/llm-proxy HTTP routeSessionPodManager.queueWork(); pods fetch via GET /internal/worksrc/providers/eventbus/postgres.ts (PostgreSQL-backed pub/sub for events)HTTP for all payloads: IPC requests use HTTP POST to /internal/ipc. Work dispatch uses SessionPodManager (in-process queue). NetworkPolicy allows sandbox pods egress to host on port 8080. Workspace persistence uses git-based providers (git-http for k8s, git-local for local dev).
The MCP fast path (src/host/inprocess.ts) runs the LLM orchestration loop directly in the host process — no pods, no IPC, no proxy, no GCS sync. Used for lightweight tool-calling tasks via MCP providers (database-backed). Key files: inprocess.ts (LLM loop), tool-router.ts (tool routing with per-turn limits), sandbox-manager.ts (cross-turn sandbox escalation). See src/providers/mcp/ for the McpProvider interface: listTools(), callTool(), credentialStatus(), storeCredential(). Implementations: none (no-op), database (per-agent HTTP/SSE MCP servers stored in DB with circuit breakers). Unified MCP routing via McpConnectionManager (src/plugins/mcp-manager.ts).
src/plugins/ now contains only the MCP connection manager — the per-agent registry that discovers tools and routes calls across all configured MCP servers. Skills and MCP servers reach it through the git-native skill flow (.ax/skills/<name>/SKILL.md → reconciler → admin approval → mcp-applier.ts → McpConnectionManager.addServer()).
Key files:
src/plugins/mcp-manager.ts — McpConnectionManager: unified MCP tool discovery and routing across skill-declared, database-backed, and default providerssrc/plugins/mcp-client.ts — HTTP client for querying remote MCP serverssrc/plugins/startup.ts — Bootstrap MCP servers from the database + config at startupThere is no longer a legacy install/uninstall/list_cowork IPC surface or ax plugin/ax mcp CLI. Third-party provider plugins (for LLM/memory/channel etc.) are still managed with ax provider add|remove|list|verify.
Session-scoped catalog built from each agent's active skill snapshot at turn start, shipped to the agent as a compact one-liner listing in the system prompt. Agents dispatch via two meta-tools rather than having every MCP/OpenAPI tool wired up as a first-class SDK tool.
src/types/catalog.ts — CatalogTool shape (discriminated union of mcp / openapi dispatch kinds) + Zod validator.src/host/tool-catalog/ — registry, MCP adapter, OpenAPI adapter, jq-based _select projection, per-session cache keyed on (agentId, HEAD-sha).src/host/skills/catalog-population.ts — iterates frontmatter.mcpServers[] + frontmatter.openapi[] from the skill snapshot, builds the catalog. Emits Diagnostic entries for populate failures + wide-surface advisories.src/host/ipc-handlers/describe-tools.ts — schema lookup by catalog name (describe_tools([]) lists the whole directory).src/host/ipc-handlers/call-tool.ts — single dispatcher: MCP via callToolOnServer, OpenAPI via makeDefaultOpenApiDispatcher (path/query/header/body routing, 4 auth schemes, URL rewrites, response parsing, _select projection, auto-spill on large responses).src/host/diagnostics.ts — per-turn ring-buffered collector; emitted as named SSE events (event: diagnostic) at end-of-turn so chat UI renders a banner.Skills declare REST APIs via openapi[] frontmatter (spec URL or workspace path + baseUrl + optional auth + include/exclude globs); the adapter emits one CatalogTool per operation with inputSchema derived from params + requestBody. MCP servers remain the first-class integration for vendors that publish one. Previous codegen pipeline (src/host/toolgen/, tool_batch IPC, execute_script + ax.callTool) was fully removed in the Phase 6 migration; the catalog + meta-tools replace that surface.
There are 15 provider categories in the static allowlist (src/host/provider-map.ts): llm, memory, channel, web_fetch, web_extract, web_search, credentials, audit, sandbox, scheduler, database, storage, eventbus, workspace, mcp, auth. Credentials is database-only. Workspace has git-http and git-local implementations. The mcp category has none and database implementations.