Troubleshooting

Start with the job ID and the output streams. agent-exec keeps diagnostics separate from its machine-readable response.

Command cannot be found

Use the absolute executable path, especially for MCP clients:

AGENT_EXEC="$(command -v agent-exec)"
test -x "$AGENT_EXEC"

Job is still running

Keep its job_id, then call agent-exec wait "$JOB_ID" with a suitable deadline. The observation deadline does not end the job.

Need more output

Call agent-exec tail "$JOB_ID". Responses include bounded excerpts, byte ranges, total byte counts, and paths to retained logs.

Need diagnostics

Set RUST_LOG=debug. Diagnostics go to stderr, preserving JSON-only stdout.

RUST_LOG=debug agent-exec status "$JOB_ID"

HTTP request is unsafe

Return to the default loopback bind. Non-loopback HTTP requires explicit --insecure, a bearer token, and network-level protection for unprotected read endpoints.