verdictan acp
Use verdictan acp to discover coding agents and serve managed conversations through Agent Client Protocol (ACP) version 1.
Run these commands on the computer that executes the agent.
The desktop client owns the conversation interface. The CLI owns agent execution and saved sessions.
An ACP agent profile identifies an installed coding agent, such as codex or claude.
For control-plane agent records and gateway links, use verdictan agent.
Usage
verdictan acp agents list [--profile <name>] [--agent-config <path>] [--json] [--account-bridge]
verdictan acp agents inspect --agent <profile-id> [--profile <name>] [--agent-config <path>] [--json] [--account-bridge]
verdictan acp serve --agent <profile-id> --desktop-version <version> [--profile <name>] [--agent-config <path>] [--account-bridge] [--login-only]Options
| Option | Applies to | Effect |
|---|---|---|
--profile <name> | All | Select the local account and ACP storage profile. The default is kalkidan. |
--agent-config <path> | All | Read agent definitions from this JSON file. The default is ~/.verdictan/acp/<profile>/agents.json. |
--agent <profile-id> | inspect, serve | Required. Select a coding agent profile. Use an ID from agents list. |
--json | list, inspect | Print the discovery result as JSON. |
--desktop-version <version> | serve | Required. Supply the actual version of the supervising desktop client. |
--account-bridge | All | Use inherited private account pipes 3 and 4 when an account connection is necessary. |
--login-only | serve | Run provider sign-in in the terminal, then exit. Do not start an ACP server. |
The profile name accepts 1 through 64 ASCII letters, digits, underscores, or hyphens.
An alternate agent configuration file does not change the profile directory for sessions, discovery records, or host identity.
These commands do not accept --config, --api-url, or a provider credential flag.
The account supervisor owns API selection and account credentials.
Discover and inspect an agent
-
List the configured candidates:
verdictan acp agents list --profile kalkidan --json -
Inspect the selected candidate:
verdictan acp agents inspect --agent codex --profile kalkidan --json -
Examine
agents, includinginstallation,protocol,authentication,routing,platform,readiness, andselections. -
Select a model and access mode whose selection has
ready: truebefore starting managed work.
Both commands return schema_version, protocol_version, cli_version, execution_host, and agents in JSON mode.
Text output shows the profile ID, installation state, and version for each agent.
It does not show all readiness information.
list reads configuration and cached discovery facts. Without cached facts, installation and readiness remain unknown.
inspect examines installation and available account facts. It can update the local discovery cache.
Inspection does not create an agent session or submit a model request.
Without an account connection, installation information can remain available while authentication or model selections remain unavailable.
Built-in profile IDs include codex, claude, opencode, grok, fx, pi, muse, and antigravity.
A listed profile does not establish that its executable, managed route, platform, or selected model is ready.
User configuration can add external ACP profiles.
Connect the desktop client
The following command is a client launch template. Replace VERSION with the actual desktop version:
verdictan acp serve --agent codex --profile kalkidan --desktop-version VERSIONThe client must supply standard input and read standard output for the process lifetime.
The server exchanges newline-delimited JSON-RPC. Standard output contains protocol frames. Diagnostics use standard error.
Initialize the connection with protocol version 1 before session operations.
An initialized connection alone does not authorize execution.
The desktop account supervisor must run for the same profile.
Local processes use its private authenticated socket or named pipe.
With --account-bridge, descriptor 3 receives account responses and descriptor 4 sends account requests.
The parent client must create these private pipes before launch.
Account frames stay separate from the ACP stream.
The client selects the agent, model, provider access mode, and permitted MCP servers during session setup. Ready selections can include API access or native subscription access when the agent and account support that mode. The runtime does not silently change subscription access to API billing. Gateway readiness and per-request authorization still apply.
Provider sign-in from a terminal
For native Codex or Claude profiles, the desktop can start a separate terminal sign-in process:
verdictan acp serve --agent codex --profile kalkidan --desktop-version VERSION --login-onlyReplace VERSION with the actual desktop version.
The command runs the selected agent's provider login and exits.
It does not sign in to Verdictan or serve ACP frames.
External ACP profiles do not provide this terminal login path.
Sessions, MCP, and shutdown
| Operation | Behavior |
|---|---|
| Create a session | Create managed work with the selected agent, model, access mode, and workspace. |
| Load a session | Restore the session and replay saved updates. |
| Resume a session | Restore the session without replaying saved updates. |
| Close a session | Release active execution and preserve saved history. |
| Delete a session | Remove backend state and mark the saved session as deleted. |
| Cancel a turn | Cancel active work. Do not create a replacement prompt. |
Session records stay under ~/.verdictan/acp/<profile>/sessions/.
Saved managed choices remain part of the session. New desktop preferences do not replace its saved billing choice.
Only one process can own a writable session at a time.
Replay reads saved updates. It does not repeat prompts or tools.
MCP support depends on the agent and negotiated capabilities. Session setup can select stdio, HTTP, or SSE servers when the selected adapter supports them. MCP forwarding does not authorize independent model requests from a remote tool service. For hosted gateway MCP, use Connect an MCP client.
Keep the ACP input stream open while the client owns the connection. Loss of the directly attached transport cancels its work. Account logout stops owned runs and revokes managed runtimes. Provider subscription accounts and unrelated Verdictan profiles retain their own sign-in state.
Limits and failure behavior
| Condition | Result and action |
|---|---|
| Invalid profile name | The command stops with Invalid profile. Use the permitted characters. |
| Agent executable is missing | Install the selected agent on the execution host, then inspect it again. |
Discovery reports inspection_required | Run agents inspect for that profile. Cached listing data alone is insufficient. |
| No ready model selection | Complete account, provider, model, routing, and platform setup before execution. |
| Malformed agent configuration | Correct the JSON file selected by --agent-config. |
| Another process owns the writable session | Close that session in its owning client before restoring it elsewhere. |
| Gateway readiness fails | Repair the reported setup condition. Do not resend an uncertain prompt to recover evidence. |
Feature availability comes from discovery and the negotiated connection. ACP version 1 does not imply every optional operation, input type, or native-agent version is supported. The command reference describes the current source interface. It does not certify a particular installed agent release.
Complete command reference
Select a command for its complete input table. Default input means the value used when that option is omitted.
A value marked Not set can still come from configuration or the environment, as described above.
Set uppercase variables in example templates to your own resource IDs and paths before use.
See CLI scripting for quoting, output streams, confirmation, and exit codes.
verdictan acp agents list [OPTIONS]| Input | Required | Default input | Meaning and accepted values |
|---|---|---|---|
--profile <PROFILE> | No | kalkidan | Profile to read or write. Use the same profile for related commands. |
--agent-config <AGENT_CONFIG> | No | Not set | Agent definition JSON file. Defaults to ~/.verdictan/acp/PROFILE/agents.json. |
--json | No | false | Print structured JSON. See Result for this command's output and success conditions. This is a switch without a value. |
--account-bridge | No | false | Use inherited private account pipes 3 and 4. This is a switch without a value. |
--help (-h) prints help. The global --lang and --region options follow the shared input rules.
Use the same account profile as the desktop supervisor. Installation facts do not authorize execution.
Result: Text shows profile ID, installation, and version. JSON contains schema_version, protocol_version, cli_version, execution_host, and agents.
verdictan acp agents inspect [OPTIONS] --agent <AGENT>| Input | Required | Default input | Meaning and accepted values |
|---|---|---|---|
--profile <PROFILE> | No | kalkidan | Profile to read or write. Use the same profile for related commands. |
--agent-config <AGENT_CONFIG> | No | Not set | Agent definition JSON file. Defaults to ~/.verdictan/acp/PROFILE/agents.json. |
--agent <AGENT> | Yes | Not set | Coding-agent profile ID from acp agents list. |
--json | No | false | Print structured JSON. See Result for this command's output and success conditions. This is a switch without a value. |
--account-bridge | No | false | Use inherited private account pipes 3 and 4. This is a switch without a value. |
--help (-h) prints help. The global --lang and --region options follow the shared input rules.
Use the same account profile as the desktop supervisor. Installation facts do not authorize execution.
Result: The same discovery shape as list, with inspected installation, account, model, and readiness facts.
verdictan acp serve [OPTIONS] --agent <AGENT> --desktop-version <DESKTOP_VERSION>| Input | Required | Default input | Meaning and accepted values |
|---|---|---|---|
--profile <PROFILE> | No | kalkidan | Profile to read or write. Use the same profile for related commands. |
--agent-config <AGENT_CONFIG> | No | Not set | Agent definition JSON file. Defaults to ~/.verdictan/acp/PROFILE/agents.json. |
--agent <AGENT> | Yes | Not set | Coding-agent profile ID from acp agents list. |
--desktop-version <DESKTOP_VERSION> | Yes | Not set | Actual version of the supervising desktop client. |
--login-only | No | false | Run the native provider login in a terminal, then exit without serving ACP. This is a switch without a value. |
--account-bridge | No | false | Use inherited private account pipes 3 and 4. This is a switch without a value. |
--help (-h) prints help. The global --lang and --region options follow the shared input rules.
Use the same account profile as the desktop supervisor. Installation facts do not authorize execution.
Result: ACP JSON-RPC frames on standard output. With --login-only, the child provider login uses the terminal instead.
Next steps
- verdictan auth: connect the desktop account supervisor.
- verdictan gateway supervise: integrate desktop gateway control.
- verdictan configure: manage terminal profiles and region defaults.