ACP Configuration Reference

Complete reference for ACP agent configuration in heyvm.

Configuration File Structure

ACP agents are configured in the heyvm configuration file (typically ~/.config/heyvm/config.toml or specified via --config flag).

# Single agent configuration
[agents.my_agent]
name = "My Agent"
transport = "stdio"
command = "/path/to/agent"

# Multiple agents (array syntax)
[[agents]]
name = "Agent 1"
transport = "stdio"
command = "/path/to/agent1"

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

Configuration Fields

Required Fields

Optional Fields

Transport-Specific Configuration

Stdio Transport

[agents.local_agent]
name = "Local Agent"
transport = "stdio"
command = "/path/to/agent-binary"
args = ["--acp-mode"]
env = { "DEBUG" = "true" }

Notes:

• Command must be executable and in PATH or use absolute path
• Args are passed to the command in order
• Environment variables are set before execution

HTTP Transport

[agents.remote_agent]
name = "Remote Agent"
transport = "http"
url = "https://agent.example.com/acp"
capabilities = ["file_access", "tool_usage"]

Notes:

• URL must be valid HTTP/HTTPS endpoint
• Supports standard HTTP authentication via URL
• HTTPS recommended for production

WebSocket Transport

[agents.ws_agent]
name = "WebSocket Agent"
transport = "websocket"
url = "wss://agent.example.com/acp-ws"
description = "Real-time agent connection"

Notes:

• URL must use ws:// or wss:// scheme
• WebSocket protocol provides bidirectional communication
• wss:// recommended for production

Capabilities Reference

Common ACP capabilities supported by heyvm:

Configuration Validation

heyvm validates configuration on startup:

• Required fields must be present
• Transport-specific fields must match transport type
• URLs must be valid (if specified)
• Commands must be executable (if specified)

Environment Variable Substitution

Configuration supports environment variable substitution:

[agents.dynamic_agent]
name = "Dynamic Agent"
transport = "stdio"
command = "${AGENT_HOME}/bin/agent"
env = { "API_KEY" = "${AGENT_API_KEY}" }

Configuration Precedence

1. Command line flags (highest priority)
2. Environment variables
3. Configuration file
4. Default values (lowest priority)

Example: Complete Configuration

# Multiple agents with different transports
[[agents]]
name = "Local Development Agent"
transport = "stdio"
command = "/usr/local/bin/goose"
args = ["acp", "--debug"]
env = { "GOOSE_CONFIG" = "/etc/goose/config.yaml" }
description = "Local Goose AI agent for development"
capabilities = ["file_access", "terminal", "tool_usage"]

[[agents]]
name = "Production Agent"
transport = "http"
url = "https://prod-agent.example.com/acp"
description = "Production-grade ACP agent"
capabilities = ["file_access", "multi_modal"]

[[agents]]
name = "Staging Agent"
transport = "websocket"
url = "wss://staging-agent.example.com/acp-ws"
description = "Staging environment agent"

Troubleshooting Configuration

Common Issues

Missing required fields:

Error: Missing required field 'command' for stdio transport

Invalid transport:

Error: Invalid transport type 'tcp' - must be one of: stdio, http, websocket

Non-executable command:

Error: Command '/path/to/agent' is not executable

Invalid URL:

Error: Invalid URL 'not-a-url' for http transport

Debugging Tips

1. Validate TOML syntax using toml-validator
2. Check file permissions for local commands
3. Verify network connectivity for remote URLs
4. Review heyvm logs for detailed error messages
5. Start with minimal configuration and add complexity gradually