block / block/buzz

Custom ACP harness cannot access Docker runtime: `docker` and `/usr/bin/docker` reported as "Not found on PATH"

Open
#5,461 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
32.7k
Forks
4.3k
Avg merge
1d 13h
Merged PRs (30d)
253

Description

## Summary

I am trying to run **Hermes Agent** as a custom ACP harness in Buzz.

Hermes is deployed in Docker on the same server where Docker is available and where the
Hermes container is running. However, Buzz cannot start a Docker-based custom harness.

When I set the custom harness command to either:
```text
docker
```
or:
```text
/usr/bin/docker
```
Buzz immediately shows:
```text
Not found on PATH
```
As a result, Buzz cannot launch the Hermes ACP process inside the Docker container.

## Why this matters

The original generic Buzz error is:
```text
Turn error · error: The agent's harness reported an internal error.
For Codex agents this can mean the configured model isn't supported by your installed
codex-acp — check the model in ~/.codex/config.toml or upgrade the adapter.
```
The ACP-level response is:
```json
{
"code": -32603,
"error": "Agent reported error (code -32603): Internal error",
"outcome": "error"
}
```
However, this is not a `codex-acp` model compatibility issue in this case. The intended
harness is Hermes ACP, and the failure appears to happen before Buzz starts the configured
Hermes process.

## Environment

- Buzz version: `0.5.8`
- Hermes Agent: `v0.18.2 (2026.7.7.2)`
- Hermes deployment: Docker
- Python in Hermes container: `3.13.5`
- Model configured in Buzz:
```text
openai-codex:gpt-5.6-terra
```
- Hermes ACP validation inside the Hermes Docker environment:
```text
Hermes ACP check OK
```
- Docker host has a running Hermes container:
```text
hermes-agent-gateway
```

## Hermes ACP itself works outside Buzz

A direct stdio ACP smoke test completed successfully outside Buzz:
```text
initialize=OK
session=OK
model_switch=OK
prompt=OK
```
The configured model also resolves correctly:
```text
provider=openai-codex
model=gpt-5.6-terra
```
Therefore, Hermes ACP and the selected model are functional independently of Buzz.

## Original custom-harness configuration
```text
Command: hermes
Arguments: acp
Custom model ID: openai-codex:gpt-5.6-terra
```
A temporary credential-free trace was added to the configured `hermes` launcher.

After sending a fresh prompt from Buzz:

- the trace file remained empty;
- no new `hermes-acp` process appeared in the Hermes container;
- no corresponding new ACP failure was logged by Hermes.

This suggests Buzz did not invoke the configured launcher in the expected runtime
environment.

## Attempt to start Hermes directly through Docker

To remove host PATH ambiguity, I attempted to configure Buzz to launch the ACP process
directly in the Docker container.

### Attempt 1
```text
Command: docker
Arguments:
exec -i -e HERMES_HOME=/opt/data hermes-agent-gateway /opt/hermes/.venv/bin/hermes acp
```
Result:
```text
Not found on PATH
```

### Attempt 2
```text
Command: /usr/bin/docker
Arguments:
exec -i -e HERMES_HOME=/opt/data hermes-agent-gateway /opt/hermes/.venv/bin/hermes acp
```
Result:
```text
Not found on PATH
```

The Docker command is available on the server, but apparently not in the runtime
environment where Buzz validates or launches custom harnesses.

## Earlier, unrelated Hermes-side issue that was already resolved

Initially, Hermes had an enabled OAuth MCP server. It attempted a browser OAuth refresh
from a non-interactive ACP process and failed with:
```text
MCP OAuth requires browser authorization but no interactive session is available
```
That MCP was removed from the active Hermes configuration and the Hermes container was
restarted. Fresh Hermes logs no longer show this OAuth failure.

The remaining issue is that Buzz cannot start the intended ACP harness process.

## Expected behavior

One of the following should be possible:

1. Buzz should allow a custom harness to execute `docker` when Docker is available on
the machine running Buzz; or
2. Buzz should document the runtime in which custom harnesses execute and provide a
supported way to run a stdio ACP harness inside a Docker container; or
3. Buzz should provide a remote/custom command execution mechanism for ACP harnesses.

Additionally, if the configured command cannot be launched, the UI should report the
actual command/runtime problem rather than a generic message suggesting that the configured
Codex model is unsupported.

## Actual behavior

- Buzz reports `docker` and `/usr/bin/docker` as unavailable.
- The intended Hermes wrapper is not invoked.
- Hermes ACP does not receive a new request.
- The UI shows a generic Codex/model compatibility hint, which is misleading for this
failure mode.

## Questions

1. In which environment are Buzz custom-harness commands executed?
2. Is that environment intentionally isolated from the Docker host?
3. Is Docker access supported for custom ACP harnesses? If yes, what configuration is
required?
4. If direct Docker access is not supported, what is the recommended way to connect Buzz
to a stdio ACP server that runs inside Docker?
5. Can the error shown by Buzz distinguish command-launch failures from model or
`codex-acp` compatibility errors?

Contributor guide

Open the contributing guide

Research direction

No source file or test is named. Start by tracing custom harness command validation and launch handling, then reproduce with both `docker` and `/usr/bin/docker` while checking the runtime environment. Done means supported Docker or stdio ACP execution is documented or enabled, and command-launch failures are distinguished from model compatibility errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker
Domain
tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.