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.