Coming from v1

APX v2 is a rewrite, not an upgrade. The ideas you liked are still here: a secretary, project agents, tasks, commitments, routines, channels. What changed is the plumbing underneath: where v1 had several ways to do the same thing, v2 has one. Your projects open as they are, and the import brings the rest.

Upgrade from v1

Upgrading means installing v2 next to v1 and importing. v1’s data in ~/.apx is never changed: the import only reads it, so you can go back to v1 whenever you want.

Desktop

1. Install the v2 desktop app for your system (Install). The beta apps are not signed yet; the install page says how to open them the first time.

2. On first run choose Server (APX runs on this computer). The setup finds ~/.apx on its own and, on Welcome, offers Import from APX v1 with the version and the projects it found.

3. Pick what to bring (the groups) and go on. On Done, Make apx this version points the apx command at v2.

4. If v1’s daemon still runs on this computer, quit it before you connect the same bots in v2 (see One bot, one daemon).

Server

1. Run the installer. It stops v1’s daemon (its systemd unit or launchd agent) and removes v1’s npm package @agentprojectcontext/apx, so the apx command becomes v2’s:

   curl -fsSL https://agentprojectcontext.github.io/apx/v2/install.sh | bash

2. Import from v1’s files:

   apx import-v1 --keys --skills

   Or do it as part of the setup: apx setup --headless --import --keys --skills. For chats, channels, tasks and the rest, open the setup wizard from an app connected to this server.

v1 installed with sudo npm

A global npm package installed with sudo needs sudo to go. The installer tries it only when sudo asks for no password; otherwise it warns that v1’s apx is still there. Remove it yourself, then open a new terminal:

sudo npm uninstall -g @agentprojectcontext/apx

Until then, v2 also answers to apx2, which no other program uses: apx2 v1 says whether v1 still runs, and apx2 v1 off turns its daemon off for good and makes apx v2’s.

Phone

The v2 phone app (dev.apx.mobile) is a different app from v1’s (dev.agentprojectcontext.apx): it installs side by side, so you can keep v1’s until you are done. Pair the new one with your v2 core (Your phone).

What’s the same

• Projects are still APC folders. AGENTS.md and .apc/ work unchanged, so your v1 projects open in v2 with no conversion. Agents are still one Markdown file each in .apc/agents/.
• The office is still there. Tasks with comments that call agents, commitments to people, routines, memory per project and per agent.
• Your channels and your secretary. Telegram, WhatsApp and Discord come over with their contacts, and your super-agent keeps its name, face and personality.

What changed

In v1	In v2
Ledgers per channel and day, session files, conversation files, code-session files	Threads. One place a conversation lives, with its runs (agent turns) and steps (tool calls), all in one database
Super-agent and its daily channel logs	Home, your secretary. Its chat is one conversation everywhere; the setup wizard still calls it the super-agent
The Default project	The base project: no folder of its own, home of Home and your global agents. It’s still called Default unless you rename it
Engines (LLM providers)	Providers, shown as engines in Settings › Engines and models. Models are named engine/model and a router picks one per turn
Runtimes (apx run with Claude Code, Codex, OpenCode…)	Harnesses. Coding CLIs run only in their own sessions: code threads (apx chat --code) and External sessions
apx exec, apx run, apx code and many other ways to talk to an agent	apx chat, the one way, for Home, any agent or a code thread
Several agent-to-agent paths	One: a sub-thread through threads.send, shown as a progress card in your chat
Hand-written REST endpoints	One typed protocol that every app and the terminal use
The agent vault	Agent templates you add from a project’s Agents tab with Import
apx daemon	apx service install, status, restart (apx daemon now only explains)
~/.apx, port 7430	~/.apx/v2, port 7440

A few v1-only commands, such as apx company, are gone.

Bring your crew over

The import only reads v1. Nothing in ~/.apx is changed, so you can go back whenever you want.

Setup wizard

1. Open the setup wizard: it starts on its own the first time, or from the account menu › First-run setup.

2. On Welcome, choose Import from APX v1. APX shows the version it found and how many projects it has.

3. On Import v1, pick what to bring. Each group shows what it found:

   Group	What comes
   Projects	Their folders and agents; v1’s Default agents become global agents, with their memory
   Skills	Your global skills
   Engines	Your model providers and keys (stored securely), Ollama, your ChatGPT sign-in, and your model chain
   Variables	Tokens and keys your MCP servers use
   MCP servers	Yours and each project’s; their keys move to your variables
   Memory	Your notes and each project’s
   Chats	Your chats with the super-agent (Telegram, WhatsApp, web…) and your agents’, with their dates
   Identity and profile	Who you are, your super-agent’s personality, its secretary profile and schedule, your quiet hours
   Embedding engine	The one that finds notes by meaning and picks skills
   Images and voices	Image servers, voices and voice-note transcription
   Channels	Telegram, WhatsApp and Discord: accounts, contacts and your server’s rooms
   Open tasks	With due date, priority and tags; finished ones stay in v1
   Commitments	They become tasks of the commitment kind, with their person
   Routines	They come in off: turn them on when you stop using v1

4. Go on through the wizard. On Done, if v1’s apx is still installed, Make apx this version makes the apx command this version. Your v1 files stay in ~/.apx.

Each v1 channel’s chats come in as one thread (one per chat on Telegram), so you find “Telegram” rather than a hundred days of it. Importing chats again adds nothing new. Routine logs and media files stay in v1.

Terminal

On a server, or if you only want the basics, import from the terminal:

apx

❯ apx import-v1 --keys --skills
imported 4 projects, 9 agents; keys: gemini, openai; 12 skills

Option	Also brings
(none)	The project folders v1 knows, with their agents
--keys	v1’s model API keys, into v2’s secret store
--skills	v1’s skills
--services	v1’s image engines and voices

On a fresh server, apx setup --headless --import runs the same import as part of the setup. For chats, channels, tasks and the rest, open the setup wizard from an app connected to that server.

Running both side by side

v1 and v2 don’t share a folder or a port, so they can run on the same machine while you switch.

	v1	v2
Data	~/.apx	~/.apx/v2
Port	7430	7440
Command	apx until you switch	apx once installed or switched

One bot, one daemon

Two daemons would both answer the same Telegram bot. The server installer stops v1’s daemon for that reason. If you keep v1 running on a desktop, don’t connect the same bots in both, and leave the imported routines off until v1 is retired.

The server installer stops v1’s daemon and removes v1’s apx command (npm uninstall -g), leaving its files in ~/.apx so you can import them later. In the desktop app, the wizard’s Make apx this version does the same switch for the command. If v1 still runs beside v2 (its routines and bots would run twice), the panel says so with a card that turns it off, and so do apx v1 and apx v1 off in a terminal (apx2 where apx is still v1’s).