{"slug": "portable-context-does-not-mean-portable-runtimes", "title": "Portable Context Does Not Mean Portable Runtimes", "summary": "APC and APX, two components of a portable agent project, separate portable context from runtime availability. APC stores project contracts in the repository, while APX detects local runtimes via `apx env detect` before execution, ensuring portability does not assume identical runtimes across machines.", "body_md": "A portable agent project should not pretend every machine can run the same AI CLI.\n\nThat is the distinction APC and APX get right when used together.\n\nAPC is the portable context layer. It keeps the project contract in the repository: `AGENTS.md`\n\n, `.apc/agents`\n\n, `.apc/project.json`\n\n, skills, commands, and MCP hints. Clone the repo somewhere else and that meaning can travel with it.\n\nAPX is the daily-use runtime and tooling layer. It makes that context runnable through a local daemon, CLI, web admin, and bridges to external coding CLIs such as Claude Code, Codex, OpenCode, Aider, Cursor Agent, Gemini CLI, and Qwen Code.\n\nBut those runtimes are not part of APC.\n\nThat matters because a repo can be portable while the machine is not.\n\nOne laptop may have `codex`\n\nand `claude`\n\ninstalled. Another may only have `gemini`\n\nand `ollama`\n\n. A CI runner may have none of them. If a system treats runtime availability as if it were durable project context, it starts lying. The repo says one thing, the host can do another, and now every handoff becomes fragile.\n\nAPX avoids that by making runtime detection a local operation.\n\nThe APX runtime docs are explicit: before picking a runtime, run:\n\n```\napx env detect\n```\n\nThat command reports which runtime CLIs, engines, and tools are actually available on the current machine. In other words, APC defines the project, but APX checks the ground truth before execution.\n\nThat is a better boundary than storing runtime assumptions in the repo.\n\nA practical flow looks like this:\n\n```\napx env detect\napx run reviewer --runtime codex \"Review the diff in src/ for regressions\"\n```\n\nIf `codex`\n\nis installed, APX can spawn it. If it is not installed, the runtime is missing on that host, regardless of how cleanly the APC files travel.\n\nThis is also why APX separates `apx run`\n\nfrom `apx exec`\n\n.\n\n`apx run`\n\ndelegates to an external runtime binary. APX builds the system prompt, spawns the CLI, captures the output, and stores a session record. The external tool performs the actual model interaction and shell work.\n\n`apx exec`\n\n, by contrast, stays inside APX and calls a configured engine directly. Different path, different dependency surface, same APC project context.\n\nThat split is useful because it keeps portability honest.\n\nYou can move the same APC project between machines without editing the repository. Then APX can answer a local question:\n\nThose are runtime questions, not project-contract questions.\n\nThe APX introduction docs make the broader design even clearer: the filesystem is the source of truth for durable project meaning, while sessions, conversations, messages, caches, and other runtime state live under `~/.apx/`\n\nand never belong in the repo. Runtime availability follows that same philosophy. Installed binaries and local engine setup are machine facts.\n\nSo the practical rule is simple:\n\nThat makes APC more trustworthy, not less. The project contract stays small and durable. APX handles the messy part: local capability, runtime invocation, and session tracking.\n\nPortable context is valuable because it avoids vendor lock-in and repeated setup. But portability only works when it stops at the right boundary.\n\nThe project can travel.\n\nThe runtime must still be checked.\n\nThat is why `apx env detect`\n\nis not a convenience feature. It is the operational guardrail that keeps APC portable and APX honest.", "url": "https://wpnews.pro/news/portable-context-does-not-mean-portable-runtimes", "canonical_source": "https://dev.to/agentprojectcontext/portable-context-does-not-mean-portable-runtimes-15pa", "published_at": "2026-08-02 12:02:11+00:00", "updated_at": "2026-08-02 12:13:25.695869+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-infrastructure"], "entities": ["APC", "APX", "Claude Code", "Codex", "OpenCode", "Aider", "Cursor Agent", "Gemini CLI"], "alternates": {"html": "https://wpnews.pro/news/portable-context-does-not-mean-portable-runtimes", "markdown": "https://wpnews.pro/news/portable-context-does-not-mean-portable-runtimes.md", "text": "https://wpnews.pro/news/portable-context-does-not-mean-portable-runtimes.txt", "jsonld": "https://wpnews.pro/news/portable-context-does-not-mean-portable-runtimes.jsonld"}}