morphyDocs

Connect your AI

Use Claude, Codex, Copilot, Antigravity, Grok, OpenCode, Hermes Agent, Junie, OpenRouter, Ollama, any OpenAI-compatible API or ACP agent on your own plans.

Morphy doesn't come with its own AI subscription. It runs on the accounts you already have, signed in on your own computer. Your messages go straight from your computer to the AI you pick, never through a Morphy server.

Connect as many as you like. Every chat picks its own AI, so you can run Claude and Codex side by side on the same canvas.

At a glance

AIWhat you needWhat to install
ClaudeA Claude plan (Pro or Max)Nothing, it's built in
CodexA ChatGPT accountThe Codex CLI
GitHub CopilotA Copilot plan (Copilot Free works)The Copilot CLI
AntigravityA Google account (free; Google AI Pro and Ultra get more)The Antigravity CLI
GrokAn xAI plan with the Grok CLI, or an xAI API keyxAI's Grok CLI
OpenCodeNothing for its free models; your own keys or plans for othersOpenCode
Hermes AgentA model set up in it: Nous Portal, OpenRouter, your own key or a local modelHermes Agent
JunieA JetBrains AI plan, or your own API keyJetBrains' Junie CLI
OpenRouterAn OpenRouter account (free models need no card)The Codex CLI
OllamaNothing: it runs on your computerOllama, a model, and the Codex CLI
Custom providerAny OpenAI-compatible APIThe Codex CLI
Your own ACP agentAny agent that speaks ACPThe agent itself

No AI plan yet?

Start with OpenCode or OpenRouter: their free models cost nothing and need no credit card (OpenCode's need no account at all). Or run models on your own computer with Ollama. Which ones are good enough for coding: free and local models for coding agents.

Where to connect

Open Settings (Ctrl + ,, or the gear at the bottom of the sidebar) and click Account. Under Connections there's a card for every AI with its status:

  • Not installed: its command-line tool isn't on your computer yet. The card tells you how to install it.
  • Not connected: click Connect. A browser tab or a small terminal window opens for you to sign in (on a Mac, terminal windows open in the Terminal app). The card updates by itself when you're done. On Windows the terminal window closes by itself too; on a Mac, close it yourself once the card says Connected. Changed your mind? Click Cancel on the card.
  • Connected: ready to use. Reconnect signs in again, for example with another account. To keep two Claude, Codex or Grok accounts and switch between them, see More than one account. Sign out disconnects Claude, Codex and Grok; OpenRouter's button is called Disconnect. Copilot and Antigravity sign out in their own tools (see below), and Ollama has nothing to sign out of. OpenCode says Ready as soon as it's installed; its button is Add a provider. Hermes Agent says Not set up until it has a model; its button is Set up. Junie signs out in its own tool, like Copilot.
  • Can't start: Morphy found the AI's command-line tool, but your computer wouldn't run it. The card says where the tool is and why. See Troubleshooting.
  • Couldn't check: Morphy couldn't find out this AI's status. The card says why; click Check again. The other cards aren't affected.

Installed a tool while Morphy was open? Click Check again. You don't need to restart Morphy.

If a chat's AI isn't ready, the chat tells you what's missing, with a link straight to Settings → Account.

About Node.js

Several command-line tools below are installed with npm, which comes with Node.js. Install Node.js first (the LTS version is fine), then run the npm command in a terminal: the one in Morphy's side dock, PowerShell on Windows or the Terminal app on a Mac. In your own PowerShell on Windows, type npm.cmd instead of npm if it says "running scripts is disabled on this system".

Claude

Claude Code comes built into Morphy, so there's nothing to install.

  1. In Settings → Account, click Connect on Claude Code.
  2. Your browser opens on Claude's sign-in page. If it didn't, click Open it again on the card. If the page shows a code, paste it into the box on the card and click Sign in.
  3. Sign in with your Claude account (Claude Code needs a Pro or Max plan). The card shows your email and plan.

Signing out of Claude is computer-wide

Morphy uses Claude Code's own sign-in, which it shares with any Claude Code you run yourself on this computer. Sign out signs Claude Code out everywhere on the computer, not just in Morphy.

When you sign in with a different account, Morphy restarts its Claude chats on the new account. A chat that's busy finishes its answer first.

Codex

Codex is OpenAI's coding agent and signs in with your ChatGPT account.

  1. Install the Codex CLI in a terminal (needs Node.js). It's the same command on Windows and Mac:

    npm install -g @openai/codex
  2. In Settings → Account, click Check again, then Connect on Codex.

  3. Your browser opens. Sign in with your ChatGPT account.

Codex on Windows outside Morphy too (the ChatGPT desktop app, the CLI in PowerShell, its sandbox and WSL): see Codex on Windows.

More than one account

Have a second Claude, ChatGPT or xAI account? Morphy can keep both and switch between them in one click. This works for Claude, Codex and Grok.

  1. On the Claude Code, Codex or Grok card in Settings → Account, click Add another account.
  2. Sign in with the other account: for Claude and Codex in your browser, for Grok in the terminal window that opens (it sends you to your browser). If the browser signs you straight back into the account you already have, sign out of claude.ai, chatgpt.com or accounts.x.ai in the browser first, then try again.
  3. The card now lists both. The new account is the one in use; the other one has a Switch button.

To change accounts, click Switch. You can also press Ctrl + K and type "Switch Claude", "Switch Codex" or "Switch Grok", or switch from your phone in Morphy Remote's Settings.

  • Your chats keep their conversations. Each chat uses the other account from its next message on, except chats that keep their own account, or are in a project that does (below).
  • If an agent is working when you switch, the switch waits until it finishes. The card says so and has Cancel.
  • Like signing in, a switch is for the whole computer: Claude Code or Codex in your own terminal uses the other account too, once you restart it. Grok in your own terminal picks it up by itself.
  • Codex: OpenAI may not continue a conversation that was started on another account. If that happens, the chat says so. Switch back to that account, or start a new conversation in that chat.
  • Codex: an account is you in one ChatGPT workspace. Two people in the same Team are two accounts, each shown by its email, and so are your own personal and Team workspaces (the plan beside each says which). In two workspaces on the same plan, the end of each workspace's ID tells them apart.
  • The × on an account (shown when you point at it) removes Morphy's copy of that account's sign-in. Sign out removes the account in use.
  • Sign-in ended: when an AI won't renew an account's sign-in any more (Codex says "your refresh token was revoked"), the chat says so, and that account says Sign-in ended in the list, with Sign in again in place of Switch. Click it and sign in to that account in your browser: it keeps its place, and the projects and chats that keep it. For the account in use, Reconnect does the same.
  • Codex: a Codex sign-in somewhere else on this computer (codex login in your own terminal, the Codex app) ends the sign-in it replaces. If that was an account Morphy keeps, sign in to it again. Morphy's own Add another account and Reconnect keep your other accounts working. If Morphy can't set that up for a moment (its file of accounts is busy, say), it says "Couldn't start the sign-in safely. Try again in a moment." and doesn't start the sign-in.
  • Grok: an XAI_API_KEY in your workspace keys isn't an account Morphy can switch. Sign in with grok login (Connect) to keep accounts.

Morphy keeps a copy of each account's sign-in in your Morphy data folder, encrypted with your system's secure storage (Windows' own, the macOS Keychain or your Linux keyring).

Advanced: limits and projects

With two accounts or more, the card has an Advanced fold under the list.

Switch accounts when a limit is hit decides what a chat does when it hits that AI's usage limit, or when the account runs out of credits (a ChatGPT workspace "out of credits"):

  • Off (the default): the chat offers Switch to … your other account, next to Send when it resets. One click switches and sends the stopped message again.
  • On: Morphy switches by itself and sends the stopped message again. The chat says which account it moved to.

Morphy picks an account that hasn't hit its own limit and whose sign-in hasn't ended, the one you used longest ago first. When a ChatGPT workspace is out of credits, that holds for everyone in it: Morphy picks an account in another workspace (or a personal one) and leaves the others in that workspace out for 12 hours. A spend cap is yours alone, so another member of the same workspace can still carry on. Like any switch, it waits for agents still working on the old account. If the turn had already done some work, the chat is sent "Carry on where you left off." instead of the same message.

Projects lets a project keep one of your accounts. Pick an account next to the project's name, and the chats in that project run on it, whichever account is in use for the rest. They keep their conversations. Chats in a project with its own account never switch by themselves when they hit a limit.

One chat can keep an account of its own too, so several accounts work at the same time: click the chat's model button, then Account, and pick one. Account in use (or Its project's, in a project that keeps one) goes back. A chat that's working moves to the new account when its turn ends. A chat's own account comes before its project's, and it never switches by itself at a limit either. In a flow, Morphy can give each chat its own account for you.

  • A chat moved into or out of such a project uses the right account from its next message.
  • If Morphy can't use the project's or chat's account on this computer (for example because its sign-in can no longer be read), the chat says so and runs on the account in use. Sign in to that account again under Add another account.
  • Codex: OpenAI may not continue a conversation that was started on another account. If that happens, the chat says so. Start a new conversation in that chat.
  • Claude Code, Codex or Grok in your own terminal stays on the account in use.
  • On a Mac, projects and chats can't keep their own Claude account yet (Codex works).

GitHub Copilot

Uses the models of your Copilot plan. Copilot Free works too; on Free and Student plans Copilot picks the model for each request (Auto), while paid plans list their models in the model picker.

  1. Install the Copilot CLI in a terminal:

    npm install -g @github/copilot

    or winget install GitHub.Copilot.

  2. In Settings → Account, click Check again, then Connect on GitHub Copilot.

  3. A terminal window opens. Follow its steps to sign in to GitHub.

To sign out of Copilot, run copilot in a terminal and type /logout.

Antigravity

Google's Antigravity runs Gemini on your Google account. It's free with a Google account; Google AI Pro and Ultra get more.

  1. Install the Antigravity CLI:

    In PowerShell:

    irm https://antigravity.google/cli/install.ps1 | iex

    or with winget install Google.AntigravityCLI.

  2. In Settings → Account, click Check again, then Connect on Antigravity.

  3. A terminal window opens. Pick Google sign-in, open the link it shows, and paste the code back into the terminal.

Antigravity can't ask for permission

Antigravity can't stop and ask you inside Morphy. In Ask first and Workspace write it skips any step that needs your OK, and tells you so. In Read only it can read the files in its folder but can't run any command, not even one that only looks. To let it edit files and run commands, set the chat to No guardrails; Workspace write lets it edit files only. In a flow, a step that skipped something waits for you instead of going on. In No guardrails on Windows, commands on your Always ask before list still wait for your OK. See Permissions.

Morphy handles a few hiccups for you:

  • Google's servers are busy, or the connection drops mid-answer. Antigravity tries again by itself, and the chat's working line says reconnecting meanwhile. If it still can't get through after about two minutes, the chat says so and whose side it's on: Google's servers (try again in a few minutes, or pick another model) or your internet connection.
  • Antigravity can't reach Google as it starts. Morphy waits a moment and sends your message again. The working line says connection dropped · again in 12s (or servers busy) meanwhile.
  • Google retires a model a chat uses. The message runs on Antigravity's default model instead, the chat says so, and its model picker moves to default.
  • A model doesn't offer the reasoning effort you picked. The message runs on the nearest level it does offer, and Morphy remembers that for the next messages.

To sign out, run agy in a terminal and sign out there.

OpenCode

OpenCode is an open-source coding agent. Its free models (from OpenCode Zen) work as soon as it's installed, with no account. Add your own providers, such as OpenAI, Anthropic, Google, OpenRouter or GitHub Copilot, to use their models with your own keys or plans.

  1. Install OpenCode:

    npm install -g opencode-ai

    (needs Node.js), or scoop install opencode, or choco install opencode. For OpenCode 2: npm install -g @opencode/cli.

    Morphy works with OpenCode 1 and OpenCode 2, whichever opencode you have.

  2. In Settings → Account, click Check again. The OpenCode card says Ready, and you can pick OpenCode for any chat.

  3. Optional: click Add a provider. A terminal window opens where you pick a provider and paste its API key or sign in. When you're done, the card says which provider was added (on a Mac, close the Terminal window yourself), and OpenCode chats restart and list that provider's models too.

The free models need no provider. OpenCode in that list is for OpenCode Zen's paid models, which use credits on your OpenCode account.

In an OpenCode chat the model picker groups the models by provider, with the free OpenCode Zen ones first. Models from your own providers bill your keys or plans with them. To remove a provider, run opencode auth logout in a terminal.

Your own OpenCode settings apply in Morphy too. If you've set permission rules in OpenCode's config, those decide what it asks about; otherwise Morphy's permission modes do. Plan only uses OpenCode's own plan mode.

OpenCode 2

OpenCode 2 works like OpenCode 1 in Morphy, with your own conversations, providers and settings. With OpenCode 2:

  • The card lists the providers OpenCode 2 has, including keys it finds in your environment.
  • The model picker offers Effort for the models that have levels.
  • Morphy's chats and terminals each run OpenCode on a private server that stops with them. OpenCode 2's background server, which its own app uses, is left alone.

If Morphy finds OpenCode 1 but you also use OpenCode 2, OpenCode 2 can leave files OpenCode 1 can't read: a database OpenCode 2 made itself, or OpenCode 2's permissions in your OpenCode config. Morphy then gives its OpenCode 1 its own (in .morph/opencode/ in the data folder) and never changes OpenCode 2's. Your providers stay shared. Your OpenCode 2 conversations don't show up in Morphy, and while your config has OpenCode 2's permissions, Morphy's permission modes decide what OpenCode asks about. Don't move or delete OpenCode's database to make Morphy work: it holds OpenCode 2's conversations.

Hermes Agent

Hermes Agent is an open-source agent by Nous Research. It runs on the models you set up in it: a Nous Portal subscription, OpenRouter, an API key of your own (Anthropic, OpenAI, Google, DeepSeek and many more) or a model on your own computer.

  1. Install Hermes Agent:

    In PowerShell:

    iex (irm https://hermes-agent.nousresearch.com/install.ps1)
  2. In Settings → Account, click Check again. The Hermes Agent card says Not set up, or Ready if you already set up a model in Hermes.

  3. Click Set up. A terminal window opens with Hermes's own setup: pick a provider, sign in or paste its key, then pick a model. When you're done, the card says Ready and which provider Hermes runs on (on a Mac, close the Terminal window yourself), and Hermes chats restart on it.

Change model runs the same setup again. Hermes keeps its own keys and sign-ins, and Morphy never reads them. To sign out of a provider, run hermes logout in a terminal.

In a Hermes chat the model picker groups the models by provider.

What's different about Hermes:

  • Permissions. Hermes asks before it edits a file and before commands it considers risky. Its own approval rules decide which commands those are, and with its default smart approvals it can approve some by itself. Morphy's permission modes answer what Hermes asks: Ask first shows you each request, Auto-accept edits allows the edits, No guardrails allows everything, and Plan only refuses them and tells Hermes to only look and plan. Commands Hermes doesn't ask about run in every mode.
  • Its background service. Hermes does its work in a background service of its own. It starts with the first Hermes chat and stops by itself about ten minutes after the last one closes. Hermes's own apps on your computer use the same service.
  • Past conversations. A Hermes chat picks up its own conversation again after you restart Morphy, but Hermes 0.22 doesn't list your other Hermes conversations, so Conversations may be empty.
  • Hermes chats can't be opened as a terminal, given more folders or work in a folder on another computer yet.

Junie

Junie is JetBrains' coding agent. It runs on a JetBrains AI plan (AI Pro, AI Ultimate or your organization's) or on an API key of your own: OpenAI, Anthropic, Google, xAI, OpenRouter or GitHub Copilot.

  1. Install Junie:

    In PowerShell:

    irm https://junie.jetbrains.com/install.ps1 | iex
  2. In Settings → Account, click Check again. The Junie card says Not connected, or Connected if Junie is already signed in.

  3. Click Connect. A terminal window opens with Junie: pick Continue with JetBrains to sign in with your JetBrains account in your browser, or add an API key of your own. When you're done, the card says Connected and what Junie runs on (on a Mac, close the Terminal window yourself), and Junie chats restart on it.

Reconnect opens Junie again, to change the account or key. Junie keeps its own sign-ins and keys, and Morphy never reads them. There's no Sign out button: sign out or remove a key in Junie itself (run junie in a terminal).

In a Junie chat the model picker shows Junie's models, grouped by where they run, and Effort offers Low, Medium and High.

What's different about Junie:

  • Permissions. Junie never asks before it edits a file. Before a command it asks when its own setting says so: by default, only for commands it doesn't judge safe. Morphy's permission modes answer what it asks: Ask first shows you each request, No guardrails allows everything, and Read only switches Junie to its own Plan mode, where it looks and plans but changes nothing. In Ask first a Junie chat says once that only its commands can wait for you.
  • Starting. Each Junie chat runs its own copy of Junie, which takes a few seconds to start, and Junie chats start when Morphy does.
  • Past conversations. A Junie chat picks up its own conversation again after you restart Morphy, and Conversations lists your other Junie conversations in the chat's folder.
  • When its AI service says no. Connected means Junie is signed in or has a key. If the service behind it still refuses a message (a key it doesn't accept, a plan it can't use), the chat says what the service answered, for example 401 Unauthorized. Reconnect Junie, or pick another model.
  • Junie chats can't be opened as a terminal, given more folders or work in a folder on another computer yet. JetBrains calls Junie on Windows experimental.

Grok

Uses your xAI account.

  1. Install xAI's Grok CLI:

    In PowerShell:

    irm https://x.ai/cli/install.ps1 | iex

    Using it needs an xAI plan that includes the Grok CLI.

  2. In Settings → Account, click Check again, then Connect on Grok.

  3. A terminal window called "Grok login" opens (on a Mac, a Terminal window). Follow its steps.

Instead of signing in, you can also add an XAI_API_KEY to your workspace keys. A sign-in comes first when you have both. To keep more than one xAI account, see More than one account.

OpenRouter

OpenRouter gives you hundreds of models from many labs through one account, including free ones and paid models like Gemini, GPT and Claude.

  1. In Settings → Account, click Connect on OpenRouter.
  2. Your browser opens. Sign in to OpenRouter and click Authorize.
  3. Morphy saves the key for you. The card shows whether you're on the free tier and how much credit you've used.

OpenRouter chats run through the Codex CLI, so install that too:

npm install -g @openai/codex

In an OpenRouter chat, the model picker lists the free models first, under Free models, and the newest free model is the default, so nothing costs money unless you pick a paid model. Paid models come next, under the company that made them (Paid · Anthropic, Paid · Google and so on), show their price per million tokens and use your OpenRouter credits. Point at a model to see more: its price, how much it can read (context) and write in one answer (max output), and what it can do (use tools, read images or files, reasoning). More models has a search box (more).

Disconnect removes the key from Morphy. To use another OpenRouter account, click Disconnect first, then Connect: Reconnect keeps the key you have.

If the card says Key rejected, the saved key no longer works and Connect won't replace it. Open your workspace keys, delete the OPENROUTER_API_KEY line, click save, then Connect again.

Ollama

Ollama runs open models on your own computer: no account, and with local models your messages never leave your machine. (Ollama's cloud models, also in the model picker, need an Ollama account and run on Ollama's servers.)

  1. Install Ollama (version 0.13 or newer) and start it.

  2. Pull a model that can use tools, in a terminal:

    ollama pull gpt-oss:20b
  3. Install the Codex CLI, which Ollama chats run on:

    npm install -g @openai/codex
  4. In Settings → Account, click Check again. The Ollama card says Ready.

Give it a long context

Agents need room to work. Set Ollama's context length to 64k or more, in Ollama's settings or with the OLLAMA_CONTEXT_LENGTH setting. Ollama's cloud models already have it.

Morphy looks for Ollama at http://127.0.0.1:11434. If you run it somewhere else, set OLLAMA_HOST in your workspace keys. The model picker shows the models on your computer first, then Ollama's cloud models.

Thinking. Effort in the model menu shows what the chosen model can do:

  • A model that can turn its thinking off, like qwen3.5, has Auto (it thinks) and None (it doesn't). Turning it off makes answers faster. The chat keeps your choice; pick Auto to turn thinking back on.
  • gpt-oss always thinks, so it offers Low, Medium and High instead.
  • A model that doesn't think has only Auto.

Ollama tells Morphy what each model can do. An older Ollama that doesn't say it offers None, Low, Medium and High for any model that can think.

Only using Ollama?

Morphy never switches to Ollama by itself. In Settings → General, set Morphy runs on, and Provider under New chats, to Ollama, or Morphy's chat and new chats keep asking you to connect Claude or Codex.

Custom provider

Use any service that speaks OpenAI's API: a reseller with cheaper models, your company's AI gateway, or a server on your own computer like LM Studio or vLLM. Adding one is part of Pro; on Freemium its Add says Pro, and one you added before keeps working.

  1. Install the Codex CLI, which these chats run on:

    npm install -g @openai/codex
  2. In Settings → Account, find Custom provider at the bottom of the list and click Add.

  3. Fill in:

    • Name: what Morphy calls it, for example the service's name.
    • Address: the address of its API, usually ending in /v1 (for example https://api.example.com/v1). The service's docs call it the base URL.
    • API key: the key from the service. A server on your own computer usually needs none.
    • Default model (optional): the model a chat uses until you pick another. Left empty, it's the service's router when it has one (for example auto), else the first model it lists that can run now.
    • API (Automatic unless you change it): which of the service's APIs its chats use. See Chat completions or the Responses API below.
    • Show the model's thinking (off by default): asks the service for a summary of the model's reasoning, shown under Thinking in the chat. Only reasoning models send one. Some services refuse the request; if every message then fails, turn it off again.
  4. Click Connect. Morphy checks the address and the key before it saves anything, and the card says Ready.

If the check fails, the card says why:

  • Key refused: the service turned the key down, and the card quotes its reason (for example "API key expired."). Make a new key at the service and click Edit.
  • Blocked by a firewall: a firewall in front of the service (often Cloudflare) stopped Morphy before the service saw the request, so the key was never checked. Try again later, or ask the service to let it through.
  • Can't reach it: nothing answered at that address. Check it, and that the service is running.
  • API not found: the address lists models, but answers neither /v1/responses nor /v1/chat/completions. Check the address. If you picked an API yourself and the service doesn't answer on that one, the card says so: set it back to Automatic.

Then pick it in a chat's model menu, under Provider, by the name you gave it. Its model menu lists the models the service offers.

Routers come first, under Routing: for example FreeLLMAPI's auto, auto:coding and fusion, where the service picks the model for each message. The models follow under Models, or under their maker when their names start with one (groq/...). Point at one to see what the service says about it, when it says: its full name, price, context, max output and what it can do. A model the service can't run right now says so, and one it has no key for isn't listed. When the service gives a model's context, the chat's context ring shows how full the conversation is.

Chat completions or the Responses API

Morphy's agents speak OpenAI's newer Responses API (/v1/responses). Many services only offer the older /v1/chat/completions, for example DeepSeek's and Mistral's own APIs, Gemini's OpenAI-compatible endpoint, llama.cpp and most resellers. Those work too: Morphy translates between the two on your computer, and the card's details say chat completions. Tools, files and the terminal work the same.

Some services have both, but serve only some of their models on /v1/responses. NVIDIA's, for example (address https://integrate.api.nvidia.com/v1, with a key from build.nvidia.com), serves its own models there and the rest only on /v1/chat/completions. With API on Automatic, Morphy sends each message to /v1/responses first. If the service doesn't serve that model there, the message goes to /v1/chat/completions instead, and so does every later one on that model. The card's details say responses + chat completions.

Automatic needs no setup. To make a service's chats always use one API, Edit it and set API to Responses or Chat completions.

Edit changes the name, address, key, default model, API or Show the model's thinking; leave the key empty to keep the saved one. If you change the address to another service, type that service's key: the saved key is never sent to a different address. Remove takes it out of Morphy. Until you add one, the custom provider doesn't appear in any menu.

You can add more than one, for example a reseller and LM Studio side by side: under the ones you have, Another custom provider has its own Add (up to nine). Each gets its own card in Settings → Account, its own key, and its own entry in the AI menu, under the name you gave it.

As with Ollama, Morphy never switches to it by itself: to run Morphy's own chat on it, set Settings → General → Morphy runs on.

Your own ACP agent

Use any agent that speaks the Agent Client Protocol (ACP), the open protocol code editors like Zed use to run coding agents: an agent you built, a variant of Hermes Agent with a setup of your own, or another harness such as Pi, DSH or Odysseus. Morphy starts it with the command you give and talks to it over ACP. Adding one is part of Pro, like a custom provider; on Freemium its Add says Pro.

  1. Install the agent and set it up the way its own docs say: its sign-in, its keys, its models.
  2. In Settings → Account, find ACP agent at the bottom of the list and click Add.
  3. Fill in:
    • Name (optional): what Morphy calls it. Left empty, it's the name the agent gives itself.
    • Command: what starts it in ACP mode, as you'd type it in a terminal, for example hermes acp or pi --acp. Put a path with spaces in quotes: "C:\Program Files\Pi\pi.exe" --acp.
    • Variables (optional): settings the agent reads when it starts, such as an API key, one NAME=value a line.
  4. Click Connect. Morphy starts the agent and asks it to introduce itself before it saves anything. The card says Ready, with what the agent answered: its name and version, and what it supports (for example reopens conversations or pictures).

If the check fails, the card says why in one line:

  • Not found: there's no such program on your computer, or not in its PATH. Check the command, or give the program's full path.
  • Exited: the agent started and stopped before answering. The card shows the last thing it said.
  • Not speaking ACP: it printed something else, or nothing at all. Check that the command starts its ACP mode (often a word like acp or a flag like --acp).
  • Refused to start: it answered with an error, which the card quotes.

Check on its card starts it once more and asks again, for example after you've installed or updated it. Then pick it in a chat's model menu, under Provider, by its name.

What a chat on it does. Morphy shows only what the agent says it offers:

  • Models, modes and effort: the model menu lists its models, its own modes under Mode (for example a planning mode), and Effort when it has levels. An agent that offers no models picks its own, and the menu says so.
  • Permissions: when the agent asks before it does something, Morphy answers as the chat's permission mode says, as for any AI (in Ask first you see the request). What an agent does without asking follows its own settings: the chat tells you the first time it happens. Read only refuses what it asks to change and tells it not to; to be sure, pick its own planning mode under Mode too, if it has one.
  • Morphy's instructions go along with the first message of each conversation.
  • Stop works. A command's output shows while it runs if the agent sends it, else when the command ends.
  • History: an agent that can reopen conversations picks up where it left off after Morphy restarts. One that can't starts a new conversation with your next message, and the chat says so.

Not yet: a terminal view, more folders, folders on other computers, and messages sent mid-turn (they wait for the turn to end). Morphy doesn't run an agent's own sign-in either: if the chat says it needs one, sign in with the agent itself in a terminal.

Edit changes the name, the command or the variables. Variables show by name only: a name alone keeps its saved value, a line you take out drops it, and NAME=value sets a new value. The values are kept in your workspace keys and never shown in full, and only the agent gets them. Remove takes it out of Morphy. You can add up to nine, each with its own card and its own entry in the AI menu. As with a custom provider, Morphy never switches to one by itself.

Which AI runs what

  • Morphy's own chat runs on Claude by default. Change it in Settings → General → Morphy runs on; any connected AI can run it (not while Morphy is working). If Claude isn't connected and you've never chosen, Morphy switches to one you have connected, other than Ollama, Hermes Agent, Junie, a custom provider or your own ACP agent (OpenCode counts once it's installed, after the others).
  • Double-click on the canvas makes a Claude chat, and so do New chat and the canvas menu's New … chat. Change it in Settings → General. Until you do, a double-click whose AI isn't connected uses one you have connected (again, not Ollama, Hermes Agent, Junie, a custom provider or your own ACP agent).
  • Any other chat can switch AI: click its model button under the text box and point at Provider. The conversation goes along (more). The menu lists the AIs that can run on your computer (one you're signed out of says not connected); Connect more providers… opens Settings → Account.

MCP servers

OpenRouter, Ollama and custom-provider chats run on the Codex CLI, so they use the MCP servers you set up for Codex: add one with codex mcp add (or in the [mcp_servers] part of ~/.codex/config.toml), and chats that start after that have it (one already open gets it when Morphy restarts). Codex chats use them anyway. Morphy copies them into the settings it keeps for those chats every time one starts; nothing else from your Codex settings comes along. Hermes chats use the MCP servers you set up in Hermes itself.

Workspace keys

Some AIs can also use an API key: OPENROUTER_API_KEY, XAI_API_KEY, CUSTOM_PROVIDER_API_KEY (the custom provider's, saved there for you; a second one's is CUSTOM_PROVIDER_2_API_KEY, and so on), your own ACP agent's variables (ACP_AGENT_1__ before each name), or your own keys for the tools your agents use. Add them in Settings → Account → Workspace keys (.env) → Open. It opens as a card on the canvas: edit, then click save.

The keys are stored in a file on your computer, never on a Morphy server: %APPDATA%\Morphy\assistant\.env on Windows, ~/Library/Application Support/Morphy/assistant/.env on a Mac.

On this page