Portable Context Does Not Mean Portable Runtimes

A portable agent project should not pretend every machine can run the same AI CLI.

That is the distinction APC and APX get right when used together.

APC is the portable context layer. It keeps the project contract in the repository: AGENTS.md, .apc/agents, .apc/project.json, skills, commands, and MCP hints. Clone the repo somewhere else and that meaning can travel with it.

APX 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.

But those runtimes are not part of APC.

That matters because a repo can be portable while the machine is not.

One laptop may have codex and claude installed. Another may only have gemini and ollama. 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.

APX avoids that by making runtime detection a local operation.

The APX runtime docs are explicit: before picking a runtime, run:

apx env detect

That 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.

That is a better boundary than storing runtime assumptions in the repo.

A practical flow looks like this:

apx env detect
apx run reviewer --runtime codex "Review the diff in src/ for regressions"

If codex is 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.

This is also why APX separates apx run from apx exec.

apx run delegates 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.

apx exec, by contrast, stays inside APX and calls a configured engine directly. Different path, different dependency surface, same APC project context.

That split is useful because it keeps portability honest.

You can move the same APC project between machines without editing the repository. Then APX can answer a local question:

• which runtimes are installed here?
• which engines are configured here?
• which toolchain is available here right now?

Those are runtime questions, not project-contract questions.

The 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/ and never belong in the repo. Runtime availability follows that same philosophy. Installed binaries and local engine setup are machine facts.

So the practical rule is simple:

• APC should describe the project in a way that can survive clone, review, and handoff.
• APX should discover what the current machine can actually execute.
• The repo should not pretend local runtime binaries are portable artifacts.

That 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.

Portable context is valuable because it avoids vendor lock-in and repeated setup. But portability only works when it stops at the right boundary.

The project can travel.

The runtime must still be checked.

That is why apx env detect is not a convenience feature. It is the operational guardrail that keeps APC portable and APX honest.