DEV Community: Manuel Bruña

APX MCP Resolution Should Start With Runtime, Not Global Defaults

Manuel Bruña — Tue, 25 Aug 2026 12:04:13 +0000

APX MCP Resolution Should Start With Runtime, Not Global Defaults

When one MCP name exists in more than one place, APX should not guess.

It should prefer the most local, most operationally specific definition first.

That is why APX resolves MCP servers in this order: runtime, then shared, then foreign IDE configs, then global last.

This is not a small storage detail. It is one of the practical boundaries between APC and APX.

APC is the portable context layer. It keeps committed project context such as AGENTS.md, .apc/agents/, .apc/skills/, and .apc/mcps.json.

APX is the daily-use runtime and tooling layer. It decides what actually runs on one machine: CLI behavior, daemon state, local sessions, message logs, engines, MCP discovery, and runtime files under ~/.apx/.

MCP resolution belongs on the APX side.

Why `runtime` should win first

The core rule is documented directly in apx/src/core/mcp/sources.js.

That file defines three APX-owned writable scopes:

runtime: ~/.apx/projects/<apxId>/mcps.json
apc / shared: .apc/mcps.json
global: ~/.apx/mcps.json

It also defines the merge priority by name conflict:

runtime
apc
foreign IDE configs such as Claude, Cursor, VS Code, Roo, and Gemini
global

The code comment explains the reason in plain terms: per-project local secrets should win.

That is correct.

If the same MCP server name appears in both .apc/mcps.json and a machine-local runtime file, the runtime copy is usually the one that knows the real endpoint, token, or local command path for this machine right now.

A global fallback should not silently override that.

What APC should keep

APC should keep team-safe, durable MCP definitions.

For example, a repository can commit a shared MCP entry that tells collaborators which server name the project expects, whether it is stdio or HTTP, and which command shape or URL pattern belongs to the project.

That is project context.

It is reviewable, portable, and appropriate for .apc/mcps.json.

But APC should not try to own the last-mile operational truth for each laptop.

A token-bearing HTTP header, a user-specific local path, or a localhost port forwarded by one developer is not portable context. That belongs to APX runtime state.

What APX should keep

APX should keep the effective local override.

The same sources.js file writes runtime MCP state under ~/.apx/projects/<apxId>/mcps.json, and writeRuntimeMcps() protects that file with chmod 0600.

That is a strong signal about intended ownership.

Runtime scope is not just "another place to store MCPs." It is the place for MCP definitions that may carry secrets or machine-local details and must never leak into the repository.

That also matches the repo guidance in apx/AGENTS.md: tokens belong in runtime scope, not in committed APC files.

Why `global` should lose last

A machine-wide default is useful, but it should be a fallback, not a winner.

Suppose you use a github MCP server across many projects. A global definition in ~/.apx/mcps.json can save setup time.

But if one repository needs a different endpoint, different headers, or a safer project-local override, that repo should not have to fight the machine default.

Putting global last solves that.

The project can keep a shared .apc/mcps.json entry for collaborators, and one developer can still place a runtime override on top without changing committed project truth.

That is the useful split:

APC describes shared project intent.
APX resolves local operational reality.

The CLI reflects the same rule

The CLI in apx/src/interfaces/cli/commands/mcp.js exposes shared, runtime, global, and all as explicit scopes.

Read operations can inspect them all. Write operations default differently depending on context, but runtime remains first-class because APX expects real setups to need local overrides.

That matters for practical work.

If a team commits a safe shared MCP definition and one operator needs a secret-bearing variant, that operator can add it in runtime scope and APX will resolve that one first. No repo churn. No fake portability. No accidental secret commit.

Bigger lesson

Portable context becomes fragile when it tries to own machine-local execution details.

APC stays useful when committed files remain small, durable, and broadly true for anyone who clones the repo.

APX stays useful when it handles the messy part honestly: merge order, local secrets, active machine paths, and effective runtime resolution.

MCP resolution is where that philosophy becomes concrete.

So the rule should stay simple:

keep shared project-safe MCP definitions in APC
keep secret or machine-local overrides in APX runtime scope
let global act as fallback, not authority
resolve runtime first when names conflict

That keeps APC portable.

And it keeps APX trustworthy in daily use.

Why I Keep APX Schedules on the Runtime Side

Manuel Bruña — Mon, 24 Aug 2026 13:05:22 +0000

Why I Keep APX Schedules on the Runtime Side

One of the easiest mistakes to make in an agent system is to treat a schedule like project truth.

I made that mistake more than once while building APC and APX. The intent felt project-level, so my instinct was to store it with the repo. The job itself felt durable. The reminder felt important. The whole thing looked like something the project should own.

That instinct is only half right.

The project can own the intention. The runtime has to own the execution.

That distinction sounds minor until you try to run real scheduled work across machines, restarts, and different agent surfaces. Then it becomes obvious. A schedule is not just a line in a file. It is timing, process uptime, daemon state, local logs, and delivery behavior. Those pieces do not travel cleanly with the repository.

The boundary I kept hitting

APC is the committed side of the stack. APX is the local one.

That split already tells me where the hard line should be: durable project context in the repo, runtime state on the machine. Routines exposed that boundary in a sharper way than I expected.

A routine is scheduled APX work. The daemon checks for due routines every 5 seconds. The routine itself has a kind, a schedule, optional JSON spec, and optional pre/post shell hooks. It can be a heartbeat, shell command, exec_agent, super_agent, or telegram delivery.

None of that is just a static project fact.

A schedule depends on the machine clock. A delivery step depends on local credentials and plugins. A routine history depends on what actually ran, not what the repo promised. That is runtime behavior, even when the routine is attached to a project.

That was the first useful lesson for me: if the thing needs a daemon to wake it up, it is already living in runtime land.

Why `--project` matters

The other thing that made this concrete was the --project flag.

APX does not pretend a routine can float free without a project. If you do not pass --project, the command falls back to the built-in scratch workspace at ~/.apx/projects/default/. That is not a bug. It is a guardrail.

I like that because it forces a decision.

If I am creating a weekly summary, or a recurring cleanup job, or a check that should belong to one repo, I need to say so. I need to bind the routine to a project on purpose. Otherwise APX assumes I am just experimenting in the shared default workspace.

That saved me from a bad habit: making automation look more portable than it really was.

A routine without a project binding often means one of two things:

I have not thought about where the work belongs.
I am about to spread machine-specific behavior into something I will later expect to clone cleanly.

The --project requirement is small, but it keeps the boundary honest.

The job of a routine is not to do everything

I also had to unlearn the idea that a routine should generate text and deliver it in one step.

APX gives you a cleaner split than that.

pre_commands can gather local data. The routine kind can produce text. post_commands can deliver the result. And if the pre-step already knows nothing needs to happen, it can emit APX_SKIP and let APX skip the model call entirely.

That split matters because it keeps side effects visible.

A routine that both thinks and sends is harder to reason about. If it fails, I have to ask whether the problem was data gathering, model output, or delivery. If it double-sends, I have to inspect the whole chain.

I hit the same kind of issue in other parts of APX too: when generation and delivery blur together, the system gets harder to trust.

For routines, the fix was simple and boring:

gather the facts locally,
let the model write the message if needed,
let the shell or plugin deliver it.

That is not as flashy as a one-click automation story, but it is much easier to debug.

Here is the shape I now prefer:

apx routine add weekly-summary \
  --project my-app \
  --kind exec_agent \
  --schedule "every:7d" \
  --spec '{"agent":"reviewer","prompt":"Summarize the current project state in one short paragraph."}' \
  --post-commands 'apx telegram send "$APX_LLM_OUTPUT"'

The routine still feels like one thing to me from the outside. Internally it is three smaller concerns, and that is better.

Why `exec_agent` usually wins

One thing I learned while working on this: super_agent is not the default answer for every routine.

If a routine needs the full APX tool registry, super_agent makes sense. But most scheduled work does not need the whole kitchen sink. When I want one project agent to produce one bounded piece of text, exec_agent is the cleaner choice.

That keeps the tool surface closer to the problem.

It also keeps the routine easier to review later. A small routine is easier to inspect, easier to change, and easier to move when the project evolves. If a recurring job is really just “summarize this repo state and send it,” I do not want it to look like a giant general-purpose agent session with side effects buried inside.

The same rule applies when I look at history. APX can show me routine history, message logs, and runtime behavior locally. I do not need to reconstruct what happened from committed repo files. That is the point.

What changed in my own thinking

The real shift was not technical. It was conceptual.

I stopped asking, “Should this schedule be part of the project?”

I started asking, “What part is project truth, and what part is machine execution?”

That question is much better.

If the answer is “this is the policy for when work should happen,” I can keep the intent near the project. If the answer is “this depends on uptime, local auth, daemon state, and the current machine,” then it belongs in APX runtime state.

That separation gives me a few practical benefits:

The repo stays cleaner.
The runtime stays honest about what it owns.
I can restart or move machines without pretending the schedule was portable all along.
I can debug a failed routine by checking the runtime history instead of hunting through committed files.

It also keeps me from overpromising. A project can describe what it wants. Only a runtime can actually wake up on time and do the thing.

That sounds obvious once you say it out loud. It took me a while to stop fighting it.

The rule I keep now

My current rule is simple:

If it needs time, delivery, or daemon state, it lives on the APX side. If it needs to survive as project meaning, it lives on the APC side.

That rule has become one of the better design filters in this whole stack.

It keeps routines boring on purpose. It keeps the repo from pretending to be a scheduler. It keeps runtime behavior local, inspectable, and replaceable.

And that is the real win for me.

I do not want APC to become a place where every automation idea goes to get buried.
I do not want APX to become a second repo full of accidental project truth.

I want a clean split: intent in the project, execution in the runtime.

That is enough structure to keep the system useful, and little enough structure to keep it sane.

A Project Command Can Travel With APC. Its Execution Should Stay Local.

Manuel Bruña — Mon, 24 Aug 2026 12:03:13 +0000

A Project Command Can Travel With APC. Its Execution Should Stay Local.

A useful command definition is part of project context.

Its execution environment is not.

That is a small distinction, but it matters if you want APC and APX to stay clean.

APC is the portable context layer. It is where a repository can keep durable agent-facing files like AGENTS.md, .apc/agents/, .apc/skills/, and .apc/commands/.

APX is the daily-use runtime and tooling layer. It is what turns that context into real work on one machine: CLI sessions, web admin actions, Telegram turns, MCP calls, engines, and runtime state under ~/.apx/.

Project commands sit right on that boundary.

What should travel

A command body that explains a repeatable workflow belongs with the project.

For example, a repo might ship a markdown command in .apc/commands/release-checklist.md or .apc/commands/bug-triage.md.

That file is portable context. It tells any compatible tool, "when someone asks for this named workflow, here is the project-specific instruction body."

That is exactly the kind of thing APC should carry.

It is durable, reviewable, and tied to the repository rather than one operator's laptop.

What should not travel

The way that command gets resolved and executed should stay local.

APX's CLI code makes that boundary explicit.

apx command list and apx command show read markdown files from .apc/commands/, but they do not treat execution state as part of APC. First APX resolves which project you mean. In resolveCommandRoot(), it can use an explicit --project, the nearest APC root found from the current working directory, or a registered project path resolved through APX.

That path resolution is runtime behavior, not repository contract.

The project file travels.

The machine-specific answer to "which registered project does this command refer to right now?" does not.

That second part depends on local registration, current cwd, and APX runtime state.

Why this split matters

If you collapse those two layers, command systems get brittle fast.

One bad design is to store only runtime aliases and assume the command body lives in some hidden local database. Then the workflow stops being part of the project contract.

The opposite bad design is to push runtime details into APC, such as local execution history, channel bindings, machine-specific paths, or per-user resolution caches. Then the repository starts carrying private or unstable state it should never own.

The cleaner rule is simpler:

APC stores the command definition.
APX decides how to find the active project and run work from the current machine.

That keeps project intent portable without pretending execution context is portable too.

Practical example

The APX command implementation is deliberately modest.

listCommandFiles() scans .apc/commands/ for markdown files. cmdCommandShow() prints the requested file. And resolveProjectId() handles runtime-friendly lookup rules such as project id, exact path, exact name, fuzzy match, current APC root, or auto-registration.

That is a good division of labor.

The repository owns the workflow text.

APX owns the local question of which project instance the operator is currently talking about.

So if two developers clone the same repository, they can share the same command body through APC while APX still resolves each clone locally on each machine.

APC portable, APX practical

This is the deeper APC/APX pattern in miniature.

APC should carry durable project meaning.

APX should supply local resolution, execution, logging, and runtime coordination.

A project command can travel with the repo because the instruction body is part of project truth.

Its execution should stay local because runtimes, registrations, channels, and machine paths are not.

That separation is what keeps portable context useful instead of leaky.

A Visible Agent Name Should Not Double as the Agent Profile

Manuel Bruña — Sun, 23 Aug 2026 12:04:52 +0000

A Visible Agent Name Should Not Double as the Agent Profile

One easy way to make an agent system confusing is to let one label do two jobs.

In APX, the visible agent name and the active agent profile should stay separate.

That separation matters because APC and APX solve different problems.

APC is the portable context layer. It gives a project stable files like AGENTS.md, .apc/, agent definitions, skills, and other committed context that can travel with the repository.

APX is the daily-use runtime and tooling layer. It decides how that context runs on a real machine: CLI, web admin, Telegram, ACP, routines, direct engines, or external coding runtimes.

A display name belongs to the runtime identity side. A profile belongs to the runtime behavior side.

If you mix them, both become harder to trust.

What the repo already says

The APX codebase keeps this boundary explicit.

resolveAgentName() reads the super-agent display name from ~/.apx/identity.json, with a fallback to super_agent.name, then to "APX". That is the user-facing label.

The CLI help describes apx profile differently: it installs, activates, and configures the super-agent's "line of work," and says that with no profile active, APX behaves exactly as it always has.

Those are not the same concern.

One answers, "What do users see this agent called?"

The other answers, "What kind of work package is currently shaping the default runtime behavior?"

Why APC makes this easier

APC already keeps project agents separate from runtime identity.

A project agent in APC has a stable slug, role, model, and optional skills. That definition is part of the repository contract. It should not change just because someone wants the default APX assistant to appear as APX, Ops Desk, or another local name in Telegram or the web UI.

That is exactly why APC works as a portable layer: project truth can stay reviewable while runtime presentation stays local.

APX then adds its own runtime-only layer on top:

identity fields for how the default assistant presents itself
profiles for the default assistant's line of work
channels and routines that use those choices on the current machine

What goes wrong when the two collapse

If the visible name also selects behavior, small cosmetic changes become risky.

Imagine renaming the default assistant from APX to Release Desk because that reads better in Telegram. That should change the label users see. It should not silently install a release-management behavior package.

The inverse problem is just as bad.

If you activate a profile like secretary, APX should gain that workflow package without pretending the assistant's public name must also become Secretary on every surface. Otherwise a behavior switch leaks into UI identity, logs, and user expectations.

Keeping the two separate preserves a clean rule:

identity answers who the assistant appears to be
profile answers what line of work it is optimized for right now

Practical example

These two commands should remain independent:

apx identity show
apx profile use secretary

The first is about runtime identity.

The second is about runtime behavior.

Neither should rewrite APC project agent files, because APC owns project context, not local presentation choices for the default runtime assistant.

That is the deeper APC/APX split in miniature.

APC keeps portable project meaning in the repo.

APX keeps local execution choices flexible: display name, active profile, channels, engines, and surfaces.

Small design rule, big payoff

When an agent platform lets one field carry both identity and behavior, debugging gets harder fast.

Users stop knowing whether a rename changed branding, prompts, capabilities, or all three.

APX is stronger when it keeps those concerns apart.

Let APC describe project agents.

Let APX decide how the default assistant should appear today.

And let profiles shape runtime behavior without hijacking the assistant's visible name.

Use `apx exec` for Direct Reasoning. Use `apx run` for Real Work.

Manuel Bruña — Sat, 22 Aug 2026 12:04:28 +0000

Use `apx exec` for Direct Reasoning. Use `apx run` for Real Work.

A lot of confusion around APC and APX comes from two commands that both look like "run an agent," but do very different jobs.

apx exec calls an LLM directly inside APX.

apx run delegates the task to an external coding runtime such as Claude Code, Codex, OpenCode, Aider, Cursor Agent, Gemini CLI, or Qwen Code.

That distinction matters because APC and APX split responsibilities on purpose.

APC is the portable context layer. It keeps project truth in repository files like AGENTS.md, .apc/project.json, agent definitions, skills, and other committed context.

APX is the daily-use runtime and tooling layer. It decides how to execute that context today: direct engine call, external coding CLI, daemon route, web admin, Telegram, or another surface.

apx exec and apx run are one of the clearest examples of that boundary.

What `apx exec` really does

The APX docs define an engine as a direct LLM adapter inside APX. When you call apx exec, APX resolves the model, picks the matching engine, and makes the provider API call itself.

No external coding process is spawned.

That makes apx exec the right tool for things like:

quick questions
summaries
classification
small rewrites
one-shot analysis using APC context

Example:

apx exec -a reviewer "What are the riskiest changes in this PR?"

In that path, APX reads the APC agent definition, builds the system prompt, loads the agent memory it needs, and asks the configured model directly.

The response stays inside APX conversation storage.

What `apx run` really does

The runtimes docs define a runtime differently: it is an external AI coding CLI that APX can invoke headlessly on behalf of an agent.

So apx run is not just "exec, but bigger." It is a different execution lane.

Example:

apx run reviewer --runtime codex "Refactor parseAgentsMd to use a state machine" --timeout 600

Here APX still provides the same APC-based project context. It still reads the same agent definition and builds the same kind of system prompt. But instead of calling an internal engine, it spawns an external tool and records the session envelope around it.

That matters because the external runtime can do things apx exec should not pretend to do:

edit files
run shell commands
use its own coding workflow
keep its own native transcript

The APX docs describe this bluntly in the run vs. exec table: apx run is for full coding-agent capabilities, while apx exec is for quick one-shot reasoning.

Same APC context, different execution surface

This is the important design point.

The agent does not change just because the execution lane changes.

APC still owns the portable part: the agent role, instructions, project contract, and committed context.

APX owns the runtime choice.

That means you can keep one agent identity and switch execution style based on the task:

apx exec when you need judgment
apx run when you need action

That is a cleaner model than creating one "thinking agent" and one separate "coding agent" just because the tool path changed.

Practical rule

Use apx exec when the answer should come back as text and the job mostly fits inside one model call.

Use apx run when the job needs a real coding runtime with filesystem and terminal behavior.

A simple filter works well:

asking, comparing, summarizing, explaining: apx exec
editing, refactoring, reviewing live files, running commands: apx run

If you blur the two, you get bad expectations.

People ask apx exec to behave like a full coding CLI and wonder why it only answers.

Or they use apx run for tiny reasoning tasks and pay the overhead of spawning a whole external runtime for no reason.

Bigger APC/APX lesson

APC should describe what the project means.

APX should decide how that meaning gets executed on the current machine.

apx exec and apx run show that design in a very practical way.

Portable context stays stable.

Execution lane stays flexible.

So if you need one sentence to remember the split, use this:

APC keeps the agent portable. APX chooses whether that agent should think directly or act through a coding runtime.

If You Do Not Restart APX, You Are Testing Old Code

Manuel Bruña — Fri, 21 Aug 2026 12:03:28 +0000

If You Do Not Restart APX, You Are Testing Old Code

One of the most practical APX rules has nothing to do with prompts, models, or MCPs.

It is this: if you change APX code and do not restart the daemon before testing, you are usually testing the old runtime.

That sounds obvious. In practice, it causes a lot of false debugging.

APC and APX split responsibilities on purpose.

APC is the portable context layer. It keeps project truth in repository files such as AGENTS.md, .apc/project.json, agent definitions, skills, and other committed context.

APX is the daily-use runtime and tooling layer. It is the daemon, CLI, web admin, channel handling, sessions, message logs, and other machine-local state under ~/.apx/.

Because APX is a live runtime, code changes do not matter until the running daemon actually reloads them.

Why this matters

The APX project guide says it bluntly: skip restart and your test is a lie.

That is not style advice. The daemon keeps the JavaScript it booted with. Adapters, routes, prompt builders, and tool handlers all stay in memory until the process restarts.

So this sequence is broken:

edit APX code
run a manual check immediately
conclude the fix did not work
debug the wrong problem

The problem is often not the code. The problem is that the daemon is still serving the previous version.

What the docs and repo already say

The APX README describes APX as a daemon plus CLI plus web admin. The daemon starts on first use, and the browser UI talks to that same local process.

The APX repo guide goes further and turns that into a development rule:

know which checkout the daemon is running from
run apx restart after every code change and before manual testing
verify the restart actually happened
only then exercise the path you changed

That same guide warns about another easy mistake: the daemon runs from the main checkout, not from a random worktree. A fix committed somewhere the daemon never reads is not live, even if your branch looks correct.

Where APC fits

This restart rule also shows the APC/APX boundary clearly.

APC does not define a daemon. APC does not define process lifecycle. APC does not define how a local runtime reloads route handlers or tool wiring.

APC only defines portable project context.

APX owns the operational layer that makes that context usable today. The APC docs describe APX exactly that way: the reference runtime that keeps sessions, memory, and messages outside .apc/ under ~/.apx/, while the repository keeps the durable project contract.

So if APC answers, "What does this project mean?" APX answers, "What code is this machine actually running right now?"

Restart belongs on the APX side because live execution belongs on the APX side.

Practical loop

A safe APX edit loop is small:

apx restart
curl -s 127.0.0.1:7430/api/health
apx daemon logs --tail 30

Then test the exact path you changed.

changed a route: hit the route
changed agent or tool behavior: run apx exec or apx run
changed a web flow: restart first, then reload the browser and test end to end

That loop is boring, but it removes a whole class of fake failures.

Bigger lesson

A lot of agent-tool confusion comes from mixing portable context with live runtime behavior.

APC can be perfectly correct while APX is still running stale code.

Your repo may already contain the right project contract, agent files, and rules. But until the APX daemon reloads, the local runtime still reflects yesterday's process image.

That is why this rule matters so much.

Portable context tells every compatible tool what the project is.

APX restart makes sure the local runtime is actually using the code you just changed.

If you want one sentence to keep:

APC can stay stable in git, while APX must be restarted to make a code fix real.

A Channel That Does Not Log Is Invisible to APX

Manuel Bruña — Fri, 14 Aug 2026 12:02:52 +0000

A Channel That Does Not Log Is Invisible to APX

A runtime can claim it supports many surfaces, but that claim breaks fast if each surface keeps its own private history.

APX takes a stricter approach.

If a channel wants cross-channel continuity, it must log its turns into the shared runtime message store. If it does not log, APX cannot search it, retrieve it for memory, or hint that another thread is already active somewhere else.

That sounds like an implementation detail. It is not. It is a design rule.

APC and APX split responsibilities on purpose.

APC is the portable context layer. It keeps project truth in committed files like AGENTS.md, .apc/project.json, agent files, and skills.

APX is the runtime and tooling layer. It owns execution, sessions, channels, local memory, and message history under ~/.apx/.

That is why channel logs belong in APX, not APC.

One global place for cross-channel turns

The APX message store code documents two different lanes.

Project-specific runtime channels such as runtime, a2a, and exec live under:

~/.apx/projects/<project-id>/messages/YYYY-MM-DD.jsonl

Cross-project channels such as Telegram or other daemon-level surfaces live under:

~/.apx/messages/<channel>/YYYY-MM-DD.jsonl

The key function is appendGlobalMessage(). It writes one JSONL line per turn into ~/.apx/messages/<channel>/YYYY-MM-DD.jsonl.

That shared store is not just for archival.

In the APX project guide, the rule is explicit: the cross-channel message store is the spine. Every surface that wants to participate in shared awareness logs through that path. A channel that does not log is invisible cross-channel.

What APX gets from that rule

Three concrete features depend on this.

First, active thread awareness.

buildActiveThreadsBlock() reads recent turns from other channel folders under the global messages directory and injects a short block like “Recent chatter on other surfaces.” It skips the current channel, looks for recent meaningful turns, and tells the agent what may already be happening somewhere else.

That means a web conversation can notice that Telegram recently asked for a deploy, or a desktop voice session can notice that another surface already started the same task.

Second, retrieval.

The memory indexer walks ~/.apx/messages/<channel>/YYYY-MM-DD.jsonl for every channel, turns relevant records into chunks, and embeds them into the vector store. User and agent turns become retrievable context. Tool output can also be indexed in capped form.

No log, no chunk. No chunk, no recall.

Third, explicit search.

The search_messages tool resolves a project and runs full-text search over project messages so an agent can answer questions like “what did we decide yesterday?” without pretending to remember. Cross-channel awareness stays lightweight, while exact recovery stays searchable.

Why this should stay out of APC

It would be tempting to put all of this into the repository and call it “shared context.” That would be a mistake.

Raw channel traffic is runtime state. It can contain noise, private details, ephemeral commands, and local operational history. APC should stay portable, reviewable, and durable. It should not become a dumping ground for every chat surface.

So the boundary stays clean.

APC carries project contract.

APX carries live traffic.

Then APX can build useful runtime behavior on top: active thread hints, retrieval, search, compaction, and audit trails across surfaces.

That is deeper reason this logging rule matters.

Without one shared runtime log, “multi-channel” mostly means several disconnected inboxes.

With it, APX can treat channels as different entry points into one working system, while APC remains the portable layer that any compatible tool can read.

APX Web Features Should Reuse the Daemon, Not Fork the CLI

Manuel Bruña — Thu, 13 Aug 2026 12:04:44 +0000

APX Web Features Should Reuse the Daemon, Not Fork the CLI

A local web admin looks tempting: once you have buttons, tabs, and forms, it becomes easy to slip extra behavior into the browser and call it a feature.

APX explicitly rejects that path.

The rule in the APX project guide is blunt: the web is a GUI over the system, not a second implementation of the system. If a feature already exists in APX core or the daemon, the browser should call that. If it does not exist there yet, the answer is not to invent a web-only shortcut. The answer is to add the capability to the shared runtime first.

That design matters because APC and APX solve different problems.

APC is the portable context layer. It carries repository-owned truth such as AGENTS.md, .apc/project.json, agent files, skills, and other committed project context.

APX is the daily-use runtime and tooling layer. It runs the daemon, exposes the CLI and web admin, manages sessions, messages, routes, and local machine state under ~/.apx/.

Once you accept that split, the web admin has a clear job: present APX runtime capabilities in a browser without creating a parallel source of truth.

Same behavior, different surface

The APX architecture decision for core / host / interfaces makes this explicit.

core/ owns reusable logic
host/daemon/ exposes that logic over HTTP
interfaces/ are just surfaces such as CLI, web, desktop, or ACP

That is why the project guide also says: one domain function, one home.

If a behavior exists in both an API route and a CLI command, the logic belongs in core/, while the route and the command stay thin adapters.

The browser follows the same rule.

For example, the web hook useProjects() calls Projects.list(), and that client calls GET /projects. On the daemon side, src/host/daemon/api/projects.js answers that route by returning projects.list(). No browser-specific project registry exists. No duplicated model exists. The web surface asks the same runtime that the rest of APX uses.

That sounds small, but it prevents a lot of drift.

If the web panel kept its own project cache, project rules, or rebuild logic, it could slowly stop matching the CLI. Then users would have to ask a bad question: "which APX is correct, terminal or browser?"

A runtime should never force that question.

Why this protects APC too

The benefit is not only architectural neatness. It also protects APC.

APC works because the repository stays declarative and portable. Project context lives on disk in committed files that different tools can read.

If the web admin started adding browser-only behavior, hidden state, or mutations that bypass shared runtime logic, the practical contract would move away from APC files and into one surface. That would make the browser quietly more authoritative than the repo.

APX is supposed to do the opposite.

It should read APC, apply runtime rules, and expose those results consistently across surfaces.

So when the web panel fetches a bearer token and sends requests through src/interfaces/web/src/lib/http.ts, it is not becoming its own system. It is authenticating into the same daemon. When buildApi() mounts projects, agents, messages, routines, voice, desktop, and admin routes, the browser becomes one client among several, not a privileged fork.

Practical payoff

This rule makes daily work better in ordinary ways.

First, bugs get fixed once. If the daemon behavior changes, both CLI and web improve together.

Second, tests stay meaningful. APX project rules require behavior tests around shared functionality, not separate logic branches that only the browser understands.

Third, new surfaces stay easier to add. Desktop, ACP, CLI, and web can keep reusing the same APX runtime because the behavior lives underneath them.

That is the deeper APC/APX lesson.

APC should keep project truth portable.

APX should keep execution centralized.

And every surface, including the web admin, should stay honest about its role.

Not a second brain.

Not a forked implementation.

Just another window into the same runtime.

Use `apx setup` for Machine State. Use `apx init` for Project State.

Manuel Bruña — Wed, 12 Aug 2026 12:04:24 +0000

Use `apx setup` for Machine State. Use `apx init` for Project State.

A lot of confusion around APC and APX starts with two commands that look similar but do different jobs.

apx setup configures your machine.

apx init scaffolds your project.

That split is not cosmetic. It is one of the cleanest examples of the APC/APX boundary.

APC is the portable context layer. It defines project truth that should travel with the repository: AGENTS.md, .apc/project.json, agent files, skills, commands, and shared MCP hints.

APX is the daily-use runtime and tooling layer. It owns machine-local configuration, daemon behavior, runtime channels, engines, sessions, conversations, and message logs.

If you keep those two jobs separate, the system stays understandable.

What `apx setup` actually owns

The APX quick start and CLI docs describe apx setup as an interactive wizard for provider, model, channels, and daemon startup.

The implementation in src/interfaces/cli/commands/setup.js makes that concrete. The wizard asks for:

AI provider and model
optional API keys or Ollama base URL
Telegram bot settings
language
optional voice settings
optional Claude Code permission tweaks

Then it writes config to ~/.apx/config.json and starts the daemon.

That is machine state.

None of those choices belong in committed APC files by default. Your laptop may use Ollama. Another teammate may use OpenAI. One operator may wire Telegram. Another may not. Those differences are operational, not project truth.

So apx setup lives on the APX side because APX is supposed to own local runtime reality.

What `apx init` actually owns

apx init does almost the opposite job.

In src/interfaces/cli/commands/init.js, the command calls initApf() and reports the files it created. The scaffolding code in src/core/apc/scaffold.js creates AGENTS.md, .apc/, .apc/project.json, and the APC gitignore guard. It also generates the stable apx_id that links the committed project definition to runtime storage under ~/.apx/projects/<id>/.

That is project state.

It belongs in the repository because it describes the project, not one machine.

The APX docs say the same thing in plain language: the .apc/ tree holds committed project context, while ~/.apx/projects/<id>/ holds sessions, conversations, messages, caches, and other local runtime state.

That is the APC/APX contract in one sentence.

Why the distinction matters in practice

Imagine a fresh clone.

If a teammate gets the repo, they should inherit the project definition after checkout:

apx init --name "My Project"

That leaves durable context on disk in a form other tools can read too.

But the same teammate should not inherit your personal runtime choices just because they cloned your repo. They should choose those locally:

apx setup

That is why setup and init should not collapse into one command or one storage location.

If setup data leaks into APC, the repo starts carrying machine assumptions: provider keys, Telegram choices, localhost URLs, voice settings, or editor-specific permission tweaks.

If project scaffolding stays only in APX runtime state, the opposite problem appears: the repo stops being self-describing.

Both failures make APC less portable and APX harder to trust.

Useful mental model

Use this rule:

if the file should survive clone, review, and multi-tool use, it belongs in APC
if the setting depends on one machine, one operator, or one local runtime, it belongs in APX

That rule explains these two commands perfectly.

apx init creates the portable contract.

apx setup prepares the local executor.

One tells any compatible agent system what this project is.

The other tells APX how this machine should run it today.

Small detail that proves the design

apx init also detects scattered existing context and can write .apc/migrate.md when migration work is needed.

That only makes sense on the project side, because migration is about curating durable context into APC.

apx setup, by contrast, ends by saving local config and starting a local daemon.

That only makes sense on the runtime side.

The commands are different because the ownership is different.

Bigger lesson

APC and APX work well together when the repository stays declarative and the runtime stays operational.

APC should answer: what is this project, which agents exist here, and which committed rules travel with it?

APX should answer: how does this machine run those agents right now?

So if you are explaining the system to a new team member, keep it simple:

run apx init when you need project structure
run apx setup when you need local runtime configuration

Portable context first.

Machine-local execution second.

That is not just good CLI naming. It is the boundary that keeps APC portable and APX useful.

Auto-Registered MCP Servers Should Stay in APX Runtime, Not APC

Manuel Bruña — Tue, 11 Aug 2026 12:03:28 +0000

Auto-Registered MCP Servers Should Stay in APX Runtime, Not APC

An integration can expose an MCP server without meaning that server belongs in the repository.

That boundary matters more than it looks.

APC is the portable context layer. It keeps durable project meaning in committed files such as AGENTS.md, .apc/agents/, skills, and .apc/mcps.json. APX is the daily-use runtime and tooling layer. It owns machine-local state, plugin lifecycle, daemon behavior, and the MCP merge order that turns those files into something runnable.

Auto-registered MCP servers belong on the APX side.

Why this is the right boundary

A plugin-generated MCP definition often points at local facts: a vault path, a localhost endpoint, or a token-bearing environment variable. Those are operational details. They help one machine run a tool today, but they are not safe portable project truth.

APX's MCP source model makes that explicit.

In src/core/mcp/sources.js, APX defines three writable scopes:

shared in .apc/mcps.json for project-wide, committable MCP definitions
runtime in ~/.apx/projects/<apxId>/mcps.json for per-project local definitions, protected with chmod 0600
global in ~/.apx/mcps.json for machine-wide fallbacks

The same file also documents the merge order: runtime wins first, then project-shared APC entries, then foreign IDE configs, then global last.

That tells you what APC and APX each own.

APC can carry stable, reviewable MCP hints. APX decides which local definition actually runs on this machine.

What APX does with auto-MCP integrations

The clearest example is plugin sync.

In src/core/integrations/mcp-sync.js, APX maps integration scope to MCP scope with one deliberate rule:

integration global maps to MCP global
everything else maps to MCP runtime

The comment above that function explains why: auto-registered servers point at machine-local paths, so project integrations should become per-project runtime MCPs, not committed APC MCPs.

That same file says it directly: APX deliberately avoids the committed .apc/mcps.json scope for those generated servers.

That is a good design.

If APX wrote plugin-generated MCPs into .apc/mcps.json, one developer could accidentally commit a local vault path, a machine-only endpoint, or a secret-shaped environment contract into the repo. Another clone on another laptop would inherit a definition that looked official but was only true on the first machine.

That would weaken APC.

Practical example: Obsidian

Today the Obsidian integration is the concrete case.

APX documents an optional auto_mcp flow, and reconcilePluginMcp() keeps the MCP server in sync with the plugin lifecycle. When the integration becomes active, APX writes or updates the MCP definition in the runtime or global store, depending on the integration scope. When the integration is removed or disabled, APX removes the generated MCP there too.

That gives you the convenience people want from integrations without moving ownership into the wrong layer.

The repo can still keep a clean shared MCP file for team-safe tools. But a plugin that depends on one operator's local setup does not silently rewrite project truth.

This matches the CLI too

The CLI keeps the same idea.

In src/interfaces/cli/commands/mcp.js, write operations default to shared when you are inside an APC project and global outside one. But runtime is still a first-class explicit scope, and APX's own MCP skill docs say to use it for tokens and machine-specific endpoints.

That is the important nuance.

Human-authored MCPs can be shared when they are genuinely repo-safe. Auto-generated MCPs should be more conservative because they are derived from live runtime state.

So APX uses two different defaults for two different jobs:

manual project intent can go to APC shared scope
generated integration state stays runtime-local unless it is truly machine-wide

That split keeps convenience from turning into accidental portability.

Bigger lesson

Agent systems get messy when they commit outputs that were only valid as runtime side effects.

APC works best when committed files stay small, reviewable, and broadly true for everyone who clones the repo. APX works best when it handles the messy local part: plugin activation, machine-local files, tokens, and effective MCP resolution.

Auto-registered MCPs sit exactly on that seam.

So the rule should stay simple:

keep team-safe MCP definitions in .apc/mcps.json
keep token-bearing or local-path MCPs in APX runtime scope
let plugin lifecycle update runtime MCP state automatically
do not let generated local integrations rewrite committed project context

That is how APC stays portable and APX stays practical.

Portable context should describe the project.

Runtime-generated MCP servers should describe the machine currently running it.

I Stopped Carrying Project Truth in Runtime State

Manuel Bruña — Mon, 10 Aug 2026 19:24:51 +0000

I Stopped Carrying Project Truth in Runtime State

For a while, I kept using runtime state as if it were project truth.

That worked when I had one tool, one editor, and one short-lived session. Then the setup grew. APC became the project contract. APX became the local runtime. Once that split existed, the old habit started to hurt.

The mistake was simple: I kept asking runtime state to remember things that should have lived with the repository.

That sounds small. It is not. It changes how I debug, how I register a project, how I move between runtimes, and how I decide what deserves to be committed at all.

My current rule is blunt:

If it must survive a restart, a machine change, or a runtime swap, it belongs in APC. If it does not, it belongs in APX or disappears.

That rule has become one of the most useful design filters in the whole stack.

The old failure mode

Before APC and APX felt real to me, project knowledge lived in too many places.

Some of it sat in chat history.
Some of it sat in editor-specific config.
Some of it sat in local notes I forgot to update.
Some of it sat in the runtime because that was the easiest place to stash it after a session.

That kind of setup creates a fake sense of safety. The information exists somewhere, so I assume I can recover it later. In practice, I just get a slower version of amnesia.

Different tools remember different slices. One runtime thinks the project has one set of agents. Another thinks the rules are slightly different. A third one keeps a private shortcut that nobody else can see. The repo stops being the source of truth and becomes just one more place where the truth may or may not live.

That is the part I wanted to stop.

What APC gave me

APC is the part I wanted the repository to own.

The docs say it plainly: APC is a filesystem convention for project-level agent context. It is about the project itself, not a single runtime. It is meant to hold durable things like agent definitions, reusable skills, long-lived project facts, and expected MCP endpoints.

That matters because it gives me a stable place to answer boring but critical questions:

What is this project?
Which agents belong here?
Which rules should every runtime respect?
Which facts should survive tool changes?

Once those answers live in .apc/, I stop rebuilding them from memory.

That is the real win. Not elegance. Not branding. Less re-derivation.

A repo that can tell the same story tomorrow, on another machine, with another agent runtime, is easier to trust. APC is the thing that makes that possible.

What APX takes off my plate

APX is the other half of the split.

It owns the local runtime state: sessions, messages, caches, conversations, and agent memory under ~/.apx/projects/<project-id>/. That is where the noisy stuff belongs. That is where the private, transient, machine-specific work should stay.

I like that split because it stops me from pretending every bit of agent output is durable project knowledge.

A session can be useful without being canonical.
A cache can be helpful without being committed.
A memory note can be stable without being public.
A transcript can explain a decision without becoming part of the contract.

That distinction is easy to say and hard to enforce unless the tools help. APX helps by keeping the runtime local and the repository clean.

What changed in my daily work

The biggest change was not in architecture diagrams. It was in my habits.

I now ask a different question before I write something down:

Am I preserving project truth, or just preserving what happened in this session?

If the answer is project truth, I look for APC:

.apc/project.json for project identity
.apc/agents/*.md for agent roles and responsibilities
.apc/skills/ for reusable project behavior
.apc/mcps.json for the tool hints the project expects
.apc/rules/ or .apc/plans/ when the repo needs durable direction

If the answer is just session history, I leave it in APX or let it die.

That sounds severe, but it keeps the repository cleaner. It also makes the runtime more honest. I do not need APX to become a second memory product. I need it to be a good local execution layer.

The practical payoff

This split changed how I move between surfaces.

If I switch from CLI to a browser admin, or from one agent runtime to another, I do not want to re-decide the same project facts.
I want the repo to keep the contract.
I want the runtime to keep the execution.

That makes debugging easier too.

When something goes wrong, I ask a smaller set of questions:

Is the problem in the repo contract, or in the runtime?
Did I misclassify a fact?
Did I accidentally promote a transient note into durable context?

Most of the time, the bug is not technical magic. It is a boundary mistake.

A note that should have stayed local got committed.
A rule that should have stayed portable got hidden in a machine-specific config.
A memory that should have been curated got treated like a transcript dump.

APC and APX give me a way to catch those mistakes earlier.

Why I think this matters

I do not think the point of APC is to store more things.
I think the point is to store the right things in one place.

That is a narrower goal, and it is better.

The project should own its durable meaning.
The runtime should own its temporary work.
The machine should own its local state.
The model should not have to guess which layer matters.

Once I accepted that, a lot of the project got easier to reason about. The repo got less noisy. The runtime got more disposable. My own decisions got less emotional and more mechanical.

That is probably the best sign the split is working.

I am not trying to make APC absorb everything APX learns.
I am not trying to make APX pretend it is the project.
I am trying to make each layer own one truth.

That gives me fewer hidden dependencies, fewer accidental forks of meaning, and fewer sessions where I have to ask, "wait, where did we decide that?"

Now I already know where.

If it is durable, it lives in APC.
If it is runtime noise, it lives in APX.
If it does not matter tomorrow, it should not pretend to matter today.

Tool Catalogs Belong in APX Runtime, Not APC

Manuel Bruña — Mon, 10 Aug 2026 12:04:18 +0000

Tool Catalogs Belong in APX Runtime, Not APC

One easy way to bloat an agent system is to treat the tool catalog like portable project context.

That is the wrong boundary.

APC is the portable context layer. It carries durable project meaning through AGENTS.md, .apc/, skills, MCP hints, and other repo-owned artifacts. APX is the runtime and tooling layer. It decides what to execute, where to store local state, and which tools to expose on each surface.

The tool catalog belongs on the APX side.

That sounds small, but it matters a lot in daily use.

Why this boundary matters

A project contract should travel well. A runtime capability list should adapt to the moment.

Those are different jobs.

If you push a giant tool catalog into APC, every compatible runtime inherits a lot of operational detail that may be local, temporary, or channel-specific. That makes the portable layer noisier than it should be.

APX takes a better approach. In src/core/agent/tools/registry.js, the full tool schema set is commented as roughly 25 KB / ~6.3 K tokens. That is already large enough to dominate a lightweight turn. So APX does not send the whole catalog everywhere.

Instead, it keeps APC stable and lets runtime exposure stay dynamic.

What APX actually does

On lightweight channels, APX starts with a small base set of tools and reveals the rest on demand.

The code calls this BASE_TOOL_NAMES. It includes common things an agent often needs immediately: project and agent inventory, memory reads, session and message search, file reads and writes, basic shell access, tasks, skills, and discover_tools itself.

Everything else stays out of the first prompt.

That matters most on chat-like surfaces such as Telegram, desktop, and other lightweight channels where prompt budget is tighter and the user usually wants one small action, not a full coding cockpit.

Then APX adds a narrow expansion path: discover_tools().

That handler does two useful things:

with no arguments, it returns a grouped catalog of tools that exist but are not loaded yet
with category or exact names, it activates those tools for the next model step

So a lightweight agent does not need browser automation, fetch tools, runtime delegation, or voice tools on every turn. It can ask for them only when the task actually requires them.

Why this is better than a giant always-on list

The benefit is not only token savings.

It also improves separation of concerns.

APC says what the project is.
APX says what the runtime can do right now.

Those should not collapse into one file or one prompt blob.

A project may define agents, memory, commands, and MCP hints in a portable way. But whether a Telegram session should receive browser schemas up front is not a repository truth. It is a runtime decision.

APX makes that decision per channel.

In the same registry file, some channels deliberately get the full catalog up front: routine, api, web, code, and web_code. That also makes sense. If the user already chose a richer surface, APX can spend the budget there.

So the system stays practical in both directions:

portable context stays small and durable in APC
runtime capability exposure stays adaptive in APX

Practical example

Imagine a Telegram conversation with a project agent.

The user asks for a quick answer about current tasks. The base tool set is enough: list projects, inspect tasks, read memory, maybe search messages.

Later, the user asks the same agent to inspect a live website.

That is when discover_tools({ category: "browser" }) becomes useful. APX activates the browser tool group, merges those schemas into the next model step, and the agent continues with the richer capability set.

The repository did not change. APC did not get polluted. Only the runtime surface changed, which is exactly what should happen.

Bigger lesson

A lot of agent architectures become messy because they confuse durable context with executable capability.

APC and APX work better when those stay separate.

APC should carry the portable contract: agents, rules, memory worth committing, and machine-safe project facts.

APX should handle runtime mechanics: sessions, channels, prompt budget, local state, tool exposure, and dynamic activation.

Tool catalogs are runtime mechanics.

So the clean rule is simple:

Keep project meaning in APC.

Keep channel-specific tool exposure in APX.

When a surface needs more power, load more tools there. Do not turn the portable context layer into a giant runtime manifest.

DEV Community: Manuel Bruña

APX MCP Resolution Should Start With Runtime, Not Global Defaults

APX MCP Resolution Should Start With Runtime, Not Global Defaults

Why runtime should win first

What APC should keep

What APX should keep

Why global should lose last

The CLI reflects the same rule

Bigger lesson

Why I Keep APX Schedules on the Runtime Side

Why I Keep APX Schedules on the Runtime Side

The boundary I kept hitting

Why --project matters

The job of a routine is not to do everything

Why exec_agent usually wins

What changed in my own thinking

The rule I keep now

A Project Command Can Travel With APC. Its Execution Should Stay Local.

A Project Command Can Travel With APC. Its Execution Should Stay Local.

What should travel

What should not travel

Why this split matters

Practical example

APC portable, APX practical

A Visible Agent Name Should Not Double as the Agent Profile

A Visible Agent Name Should Not Double as the Agent Profile

What the repo already says

Why APC makes this easier

What goes wrong when the two collapse

Practical example

Small design rule, big payoff

Use `apx exec` for Direct Reasoning. Use `apx run` for Real Work.

Use apx exec for Direct Reasoning. Use apx run for Real Work.

What apx exec really does

What apx run really does

Same APC context, different execution surface

Practical rule

Bigger APC/APX lesson

If You Do Not Restart APX, You Are Testing Old Code

If You Do Not Restart APX, You Are Testing Old Code

Why this matters

What the docs and repo already say

Where APC fits

Practical loop

Bigger lesson

A Channel That Does Not Log Is Invisible to APX

A Channel That Does Not Log Is Invisible to APX

One global place for cross-channel turns

What APX gets from that rule

Why this should stay out of APC

APX Web Features Should Reuse the Daemon, Not Fork the CLI

APX Web Features Should Reuse the Daemon, Not Fork the CLI

Same behavior, different surface

Why this protects APC too

Practical payoff

Use `apx setup` for Machine State. Use `apx init` for Project State.

Use apx setup for Machine State. Use apx init for Project State.

What apx setup actually owns

What apx init actually owns

Why the distinction matters in practice

Useful mental model

Small detail that proves the design

Bigger lesson

Auto-Registered MCP Servers Should Stay in APX Runtime, Not APC

Auto-Registered MCP Servers Should Stay in APX Runtime, Not APC

Why this is the right boundary

What APX does with auto-MCP integrations

Practical example: Obsidian

This matches the CLI too

Bigger lesson

I Stopped Carrying Project Truth in Runtime State

I Stopped Carrying Project Truth in Runtime State

The old failure mode

What APC gave me

What APX takes off my plate

What changed in my daily work

The practical payoff

Why I think this matters

Tool Catalogs Belong in APX Runtime, Not APC

Tool Catalogs Belong in APX Runtime, Not APC

Why `runtime` should win first

Why `global` should lose last

Why `--project` matters

Why `exec_agent` usually wins

Use `apx exec` for Direct Reasoning. Use `apx run` for Real Work.

What `apx exec` really does

What `apx run` really does

Use `apx setup` for Machine State. Use `apx init` for Project State.

What `apx setup` actually owns

What `apx init` actually owns