ACP in the TUI

The heyvm TUI provides built-in support for connecting to and interacting with ACP agents. This guide explains how to configure and use ACP integration in the TUI.

Prerequisites

  • heyvm installed and running
  • At least one ACP-compatible agent available (local or remote)
  • Basic understanding of the heyvm TUI navigation

Configuration

ACP agents can be configured in the heyvm configuration file. Each agent requires:

  • Name: A friendly name for the agent
  • Transport: How to communicate with the agent (stdio, http, or websocket)
  • Command/URL: Either a local command to run or a remote URL to connect to
  • Optional: Description, capabilities, environment variables

Example Configuration

[[agents]]
name = "Local Goose Agent"
transport = "stdio"
command = "/path/to/goose"
args = ["acp"]
description = "Local Goose AI agent"
capabilities = ["file_access", "terminal", "tool_usage"]

[[agents]]
name = "Remote Agent"
transport = "http"
url = "https://agent.example.com/acp"
description = "Remote ACP agent"

Using ACP in the TUI

  1. Launch heyvm: heyvm
  2. Navigate to the Agents tab using the tab keys or designated shortcut
  3. Use j/k or arrow keys to browse available agents

Connecting to an Agent

  1. Select a sandbox using s to cycle through available sandboxes
  2. Select an agent from the list
  3. Press Enter or c to initiate the connection

Interacting with the Agent

Once connected:

  • Prompt input: Press Tab to focus the prompt, type your message, and press Enter to send
  • Conversation scroll: Use ↑/↓ arrows to scroll through the conversation
  • Fast scroll: Use PgUp/PgDn for faster navigation
  • Switch mode: Press Shift+M to switch between available session modes (if supported by the agent)

Managing the Session

  • Disconnect: Press d to stop the ACP session and disconnect from the agent
  • View status: The connection status is displayed in the UI
  • Error handling: If connection fails, error messages will be shown

File System Integration

ACP agents can access files through the heyvm file system adapter:

  • Local files: Agents can read/write files in sandbox mounts
  • Mount management: Configure mounts in the Mounts tab before connecting
  • File operations: All file access is logged and mediated through the ACP protocol

File Access Example

  1. Add a mount in the Mounts tab: ./project:/app
  2. Connect to an agent
  3. The agent can now access files in /app which maps to ./project on your host

Transport Types

Stdio Transport

For local agents that communicate via standard input/output:

[agents.local_agent]
transport = "stdio"
command = "/path/to/agent-binary"
args = ["--acp-mode"]

HTTP Transport

For remote agents accessible via HTTP:

[agents.remote_agent]
transport = "http"
url = "https://agent.example.com/acp-endpoint"

WebSocket Transport

For real-time bidirectional communication:

[agents.websocket_agent]
transport = "websocket"
url = "wss://agent.example.com/acp-ws"

Troubleshooting

Connection Issues

  • Verify the agent command/URL is correct
  • Check network connectivity for remote agents
  • Ensure the agent supports the specified transport type
  • Review the CLI log at ~/.heyo/cli.log for detailed error messages

Permission Errors

  • Ensure the agent has proper permissions for requested operations
  • Check sandbox mount configurations
  • Verify file system access rights

Protocol Errors

  • Ensure both client and agent support the same ACP protocol version
  • Check agent compatibility with heyvm's ACP implementation
  • Review agent capabilities and supported features

Advanced Configuration

Environment Variables

[agents.custom_agent]
transport = "stdio"
command = "/path/to/agent"
env = { "AGENT_TOKEN" = "your-token-here", "DEBUG" = "true" }

Multiple Agents

Configure multiple agents and switch between them in the TUI:

[[agents]]
name = "Agent 1"
transport = "stdio"
command = "/path/to/agent1"

[[agents]]
name = "Agent 2"
transport = "http"
url = "https://agent2.example.com"

Security Considerations

  • Use HTTPS/WSS for remote agent connections
  • Validate agent URLs and commands
  • Review agent capabilities before connecting
  • Monitor file system access through mounts
  • Regularly update agents to latest secure versions

Learning More

For more details about the ACP protocol and heyvm's implementation: