1# ACP providers
2
3T3 Code can run installed ACP commands or coding agents from the official
4[ACP Registry](https://agentclientprotocol.com/get-started/registry). Registry agents bring their
5own models, tools, and sign-in, while T3 Code provides projects, threads, checkpoints, and task
6delegation.
7
8Agents that T3 Code supports as their own providers, such as Codex, Claude, Cursor, Grok, OpenCode,
9Pi, and [Antigravity](./providers-antigravity.md), don't appear in the Registry list. Enable them in
10**Settings → Providers** instead.
11
12T3 Code prefers the current ACP v2 preview protocol and uses its richer messages, usage, plans,
13configuration, compaction, and agent-terminal updates when the agent supports them. It also
14negotiates ACP v1 for Registry agents that have not migrated yet, so they continue to work through
15the same generic integration.
16
17Claude Agent uses the ACP v2 preview by default for Registry and local `claude-agent-acp`
18commands. If you encounter preview issues, set `CLAUDE_AGENT_ACP_EXPERIMENTAL_V2=0` in the
19provider instance's environment overrides to use ACP v1.
20
21## Add an agent
22
23Open **Settings → Providers**.
24Select **Add provider**, then **Show more**.
25Search the ACP Registry for the agent and select **Add** on its result.
26Confirm the name and instance ID, then complete the agent's sign-in step.
27
28Search only shows agents that can run on the connected server. Registry agents are third-party
29code; review an agent's source and license before adding it.
30
31## Add a local command
32
33In **Settings → Providers → Add provider**, select **Show more**, then **Local ACP command**. Enter the executable
34name or path on the selected environment, add one literal argument per row, and choose a display
35name. For DeepSeek Harness, use `dsh` with arguments `--profile` and `acp`.
36
37Local commands require no registry entry or download. Environment overrides apply to the command;
38credentials and skills remain managed by the installed agent or its wrapper. Models and reasoning
39options come from ACP, including model IDs that contain JSON. T3 Code launches the executable directly
40without expanding shell expressions.
41
42## Where agents run
43
44Registry agents always run on the machine that hosts your T3 Code server. That stays true when you
45connect through `app.t3.codes`, T3 Connect, or a relay.
46
47Agents install under `tools/<agent-id>/<version>/` inside T3 home. T3 Code verifies SHA-256 when the Registry entry
48provides one; entries without a checksum retain the Registry's HTTPS distribution guarantee.
49Registry `npx` and `uvx` packages use T3-owned npm prefixes and Python tool directories at the exact
50version published by the Registry. Their commands are available in a new server terminal for
51sign-in and direct use. Removing an agent's last provider instance removes T3-managed binary files
52but keeps package installs. To use an existing local binary, set **Executable override** explicitly.
53
54## Signing in
55
56Open the agent's account section in **Settings → Providers** on web or desktop. Choose
57**Sign in** and, if the agent offers several methods, select one. For an installed, configured
58provider, mobile also offers **Settings → Providers**.
59
60Browser sign-in shows the agent's URL and waits for you to open or copy it before telling the
61agent to proceed. The page opens on your device, while the agent runs on the environment.
62Terminal methods run in an in-app terminal on that environment. On mobile, send responses
63through the terminal response field. T3 Code reconnects after terminal login and waits for the
64agent to confirm sign-in before reporting success. You can cancel or retry an expired attempt.
65
66Browser and terminal sign-in leave credentials in the agent's own store. Agents that use API keys
67through environment variables still take those keys in the instance's environment settings.
68A configured environment or agent home applies to both sign-in and chat.
69
70If the agent advertises logout, choose **Sign out**. Changing a shared agent login stops running
71threads for instances of that same agent on the environment. Thread history and workspace files
72are kept. ACP does not describe account isolation, so adding another instance does not guarantee
73a separate account; use the agent's own configuration to isolate accounts when supported.
74
75If an agent cannot complete its advertised flow remotely, its CLI remains available on the
76server. For example, Codex supports `codex login --device-auth`, and Grok Build supports
77`grok login --device-auth`.
78
79## Models and options
80
81The model picker lists the models the agent reports. If the agent reports none, or hides some, add
82your own model IDs under **Custom models** in the instance settings.
83
84Other settings the agent offers, such as reasoning effort or approval mode, appear in the
85composer's model picker, beside the model list, like they do for built-in providers. Models and options that change while an agent
86is running update the picker without waiting for another provider probe.
87
88## Commands and skills
89
90Slash commands the agent provides appear under **Provider** in the `/` menu while a session is
91running. Commands the agent names with a `$` prefix appear in T3 Code's `$` skill menu instead.
92
93## Native sessions
94
95When an agent advertises ACP session listing and import support, expand its provider card,
96choose a project, and select **List sessions**. Importing one creates a deterministic T3 thread
97backed by that native session. Importing the same agent session again returns the existing thread,
98including when another client performs the import.
99
100The thread keeps the native session's title and last-update value as provider metadata without
101overwriting a title you set in T3 Code. Agents that report ACP context usage drive the thread details
102context window and cumulative cost metadata. See
103[commands and skills](./composer.md#commands-and-skills) to show it on web and desktop.
104Text resources and links render as assistant output;
105binary resources, images, and audio that T3 Code cannot render yet appear as explicit placeholders
106instead of disappearing.
107
108## Permissions and terminals
109
110Registry agents read files, edit, and run commands themselves, under their own sandbox and
111approval rules. They start in their own default mode, and their mode picker in the model options
112menu switches it. How far an agent is confined depends on that mode and the agent's own settings,
113so use its sandbox and permission controls when that matters.
114
115When a registry agent asks for approval, T3 Code answers by the thread's
116[permission mode](./permission-modes.md): **Supervised** shows the request in the conversation,
117**Auto-accept edits** approves edits and shows the rest, and **Auto** and **Full access** approve
118automatically. File reads and searches never wait for approval.
119
120Devin runs its commands through T3 Code's terminals, and those commands follow the thread's
121permission mode. For other agents, T3 Code shows the command, output, and exit status the agent
122reports but does not run or stop their terminals.
123
124Registry agents can schedule work and use T3's MCP tools. Child-task presentation depends on what
125the agent exposes: ACP has no portable native subagent-lineage contract, so richer delegation views
126remain agent-specific.
127
128## Checkpoints
129
130Checkpoint rollback restores your files as usual. ACP agents cannot rewind their own conversation,
131so the next turn after a rollback starts a fresh agent session that no longer remembers the
132conversation from before the checkpoint.
133
134Registry instances are not used for T3's app-owned text generation, such as thread titles, commit
135messages, branch names, or pull request descriptions. Configure a text-generation-capable provider
136for those actions.
137
138## Advanced configuration
139
140**Executable override** runs an existing local executable instead of the managed distribution,
141 keeping the registry-declared arguments and environment.
142**Authentication method** picks a specific method when the agent advertises more than one.
143**Custom models** adds model IDs the agent does not report.