Beta Coming soon. This feature is still being built, so names and details may change before it ships.

External agents (ACP)

Run an open-source coding agent (OpenCode, Goose or OpenHands) or any Agent Client Protocol agent you add inside Ingot, next to Ingot's own agent. It streams its plan and tool calls and asks before it edits.

The Agent Client Protocol (ACP) is an open standard for connecting coding agents to editors. Ingot starts the agent as its own process in your project folder and talks to it over ACP: you get Ingot's panel, permission cards and file tracking around it.

The External Agents panel: Ingot Agent first, then the open-source agents OpenCode, Goose and OpenHands with their licences, and the agents you addedThe External Agents panel: Ingot Agent first, then the open-source agents OpenCode, Goose and OpenHands with their licences, and the agents you added
The External Agents panel: Ingot Agent first, then the open-source agents OpenCode, Goose and OpenHands with their licences, and the agents you added

Turn it on

External agents are off until you turn them on. There are three ways, as for every optional feature:

  • In the chat. Name an agent in the agent chat ("let OpenCode handle this", "ask Goose to…", or the name you gave your own agent) and a small line suggests Enable. It turns the feature on, opens the panel on that agent and puts your message in its composer. × hides the suggestion for good.
  • In Settings. Settings › Features › External agents is the on/off switch. Settings › Tools › External agents (ACP) has the rest of the options.
  • One click. The Agents button in the status bar turns the feature on and opens the panel. The shortcut is ⌥⇧⌘End on macOS and Ctrl+Alt+Shift+End on Windows and Linux; in Find Action, search for "External Agents".
The agent chat after asking Team Bot, an agent added in .ingot/acp.json, to summarize the README: an inline suggestion with Enable and a close button above the composerThe agent chat after asking Team Bot, an agent added in .ingot/acp.json, to summarize the README: an inline suggestion with Enable and a close button above the composer
The agent chat after asking Team Bot, an agent added in .ingot/acp.json, to summarize the README: an inline suggestion with Enable and a close button above the composer

The agent list

The panel lists agents in three groups:

  1. Ingot. Ingot's own agent always comes first. Open Ingot chat opens it in the agent chat, with your models, rules, MCP servers and checks. Nothing to install.
  2. Open-source agents (ACP). Vetted open-source agents that speak ACP, each with a permissive licence. They use the provider you set up in the agent itself, so the panel never asks you for a vendor API key for them.
  3. Your agents. Agents you add in .ingot/acp.json or ~/.ingot/acp.json, shown with the name you gave them.
AgentLicenceHow Ingot starts itSign-in
OpenCodeMITopencode acp when OpenCode is installed, else npx -y opencode-ai acpopencode auth login once in a terminal
GooseApache-2.0goose acp (install Goose first)goose configure once in a terminal
OpenHandsMITopenhands acp (install the OpenHands CLI first)run openhands once and set a model with /settings

An agent that is not installed is marked not installed, with a How to install link to its project page. The first OpenCode start through npx downloads it, so it can take a minute; Node.js 18 or later must be on your PATH.

The bottom of the agent list: Your agents, with Home Helper from ~/.ingot/acp.json and Team Bot from the project's .ingot/acp.jsonThe bottom of the agent list: Your agents, with Home Helper from ~/.ingot/acp.json and Team Bot from the project's .ingot/acp.json
The bottom of the agent list: Your agents, with Home Helper from ~/.ingot/acp.json and Team Bot from the project's .ingot/acp.json

Run a task

  1. Open the panel and pick the agent in the header, or press Start on its card.
  2. Describe the task and press Enter (Shift+Enter for a new line). The first message starts a session in the first project folder.
  3. The agent's reply streams into the panel with its thinking (folded), its plan and a card for every tool call: what it read, what it ran, and a diff for every edit.
  4. When the agent wants to edit a file or run a command, a permission card shows the change with Allow, Always allow and Reject (the options come from the agent).
  5. Files the agent changed are listed above the composer; click one to open it.
The External Agents panel: Team Bot read README.md, shows its plan and asks for permission to write NOTES.md with a diffThe External Agents panel: Team Bot read README.md, shows its plan and asks for permission to write NOTES.md with a diff
The External Agents panel: Team Bot read README.md, shows its plan and asks for permission to write NOTES.md with a diff

The mode menu under the composer switches the agent's own modes (for example Code or Ask) when it has them. Stop cancels the turn, the + button starts a fresh session, and Agent log shows what the agent printed on stderr, which helps when it fails to start.

Permissions and safety

SettingWhat Ingot answers when the agent asks
ask (default)shows the permission card and waits for you
allowallow once, automatically; the thread notes "(automatic)"
denyreject, automatically: the agent can read but not change anything
  • Ingot reads and writes files for the agent only inside the project folder. A request for any other path is refused, whatever the agent asks for.
  • Ingot does not hand the agent a terminal. Commands the agent runs with its own tools run under the agent's own sandbox and settings, and they still ask through the permission card.
  • The agent runs with your user's permissions, like any program you start. Only run agents you trust, and check the command in the agent card before you start one you added.
  • Turning the feature off stops every running agent.

API keys for your own agents

An agent you add can name the environment variable that carries its API key (keyEnv). When it needs a sign-in, the panel shows Set API Key…, the agent's own sign-in methods and Retry. The key is kept in the Ingot key store (the OS keychain), never in settings or project files, and is given only to that agent, in that variable. Set External Agent API Key… in Find Action changes or removes it (leave it empty to remove). The built-in open-source agents have no key button: they sign in with their own CLI.

Add your own agents

Any program that speaks ACP can be added in .ingot/acp.json in the project, or in ~/.ingot/acp.json for every project. The gear button in the panel creates the project file.

{
  "agents": {
    "team-bot": { "name": "Team Bot", "command": "team-bot", "args": ["--acp"], "keyEnv": "TEAM_BOT_API_KEY" },
    "goose": { "command": "/opt/tools/goose", "args": ["acp"] }
  }
}
KeyWhat it does
command, argshow to start the agent (required for a new agent)
name, descriptionshown in the panel and used in chat suggestions
envextra environment variables for the agent
keyEnvthe variable that receives the API key saved with Set API Key…

The id is the key (team-bot), in lowercase letters, digits, dots, dashes or underscores. Using a built-in id (opencode, goose, openhands) changes how that agent starts. The project file wins over the global one.

From the terminal

npx @ingotide/cli acp agents                      # the agents you can run, how each starts and its licence
npx @ingotide/cli acp doctor goose --session      # check the ACP handshake and whether it needs a sign-in
npx @ingotide/cli acp run opencode --prompt "Add a test for the cart total" --allow
npx @ingotide/cli acp run team-bot --file task.md --read-only --json
npx @ingotide/cli acp add team-bot --command team-bot --args="--acp" --key-env TEAM_BOT_API_KEY

run prints the reply on stdout and the thoughts, plan and tool calls on stderr. Without --allow or --deny it asks in a terminal and refuses in CI and pipes. Every option is on CLI.

Settings

SettingDefaultWhat it does
External agentsoffthe feature switch (also in Settings › Features)
Default agentOpenCodethe open-source agent the panel starts with
When the agent asks for permissionaskask, allow or deny (above)
Agents button in the status baronthe one-click button
Suggest features in chatonSettings › Features: every inline suggestion, for all features
Suggestions you closedemptySettings › Features: features whose suggestion you closed with × (External Agents is acp.external-agents); remove one to see it again

FAQ

Does it use my Ingot plan or units? No. The agent uses its own provider; Ingot only runs it and shows its work.

Does Ingot send my code anywhere? No. The agent talks to its own provider, as it does in a terminal.

Why is an agent I used before not in the list? The built-in list holds vetted open-source agents only. Any other ACP agent still works: add it in .ingot/acp.json or ~/.ingot/acp.json and it shows with the name you give it.

Why does an open-source agent say it needs a sign-in? It uses the provider set up in the agent itself: run its sign-in once in a terminal (see the table above) and press Retry.