Skip to main content

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​

OptionApplies toEffect
--profile <name>AllSelect the local account and ACP storage profile. The default is kalkidan.
--agent-config <path>AllRead agent definitions from this JSON file. The default is ~/.verdictan/acp/<profile>/agents.json.
--agent <profile-id>inspect, serveRequired. Select a coding agent profile. Use an ID from agents list.
--jsonlist, inspectPrint the discovery result as JSON.
--desktop-version <version>serveRequired. Supply the actual version of the supervising desktop client.
--account-bridgeAllUse inherited private account pipes 3 and 4 when an account connection is necessary.
--login-onlyserveRun 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​

  1. List the configured candidates:

    verdictan acp agents list --profile kalkidan --json
  2. Inspect the selected candidate:

    verdictan acp agents inspect --agent codex --profile kalkidan --json
  3. Examine agents, including installation, protocol, authentication, routing, platform, readiness, and selections.

  4. Select a model and access mode whose selection has ready: true before 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 VERSION

The 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-only

Replace 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​

OperationBehavior
Create a sessionCreate managed work with the selected agent, model, access mode, and workspace.
Load a sessionRestore the session and replay saved updates.
Resume a sessionRestore the session without replaying saved updates.
Close a sessionRelease active execution and preserve saved history.
Delete a sessionRemove backend state and mark the saved session as deleted.
Cancel a turnCancel 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​

ConditionResult and action
Invalid profile nameThe command stops with Invalid profile. Use the permitted characters.
Agent executable is missingInstall the selected agent on the execution host, then inspect it again.
Discovery reports inspection_requiredRun agents inspect for that profile. Cached listing data alone is insufficient.
No ready model selectionComplete account, provider, model, routing, and platform setup before execution.
Malformed agent configurationCorrect the JSON file selected by --agent-config.
Another process owns the writable sessionClose that session in its owning client before restoring it elsewhere.
Gateway readiness failsRepair 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.

Next steps​