docs(agent): note sandboxed session access#229
docs(agent): note sandboxed session access#229skalidindi wants to merge 2 commits intomodem-dev:mainfrom
Conversation
Greptile SummaryThis PR adds a short troubleshooting section to both
Confidence Score: 4/5Documentation-only change; no production code paths are touched and the prose is accurate for default configurations. The curl probe hardcodes port 47657, which is the default but overrideable via HUNK_MCP_PORT. Users with a custom port will get a silent failure from the probe and draw the wrong conclusion. The Common Errors section in SKILL.md also still sends agents straight to 'ask the user to open Hunk' without first trying the sandbox diagnostic. Both gaps are in documentation, not runtime logic, so they carry low risk, but they reduce the reliability of the troubleshooting guidance the PR is specifically trying to add. skills/hunk-review/SKILL.md — the Common Errors section's 'No active Hunk sessions' entry should cross-reference the new sandbox guidance. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Agent runs hunk session list] --> B{Sessions returned?}
B -- Yes --> C[Proceed normally]
B -- No --> D[Hunk TUI visibly running?]
D -- No --> E[Ask user to open Hunk]
D -- Yes --> F["Probe daemon directly:\ncurl POST /session-api {action:list}"]
F --> G{Probe returns sessions?}
G -- No --> H[Daemon unreachable / not running\nAsk user to restart Hunk]
G -- Yes --> I[Sandbox is blocking loopback\nRerun hunk session * with\nsandbox-escalation mechanism]
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| A useful probe is: | ||
|
|
||
| ```bash | ||
| curl -s -X POST http://127.0.0.1:47657/session-api \ | ||
| -H 'content-type: application/json' \ | ||
| --data '{"action":"list"}' | ||
| ``` |
There was a problem hiding this comment.
47657, but the daemon port is configurable via HUNK_MCP_PORT. A user who has set that env var will get a silent failure from the probe and may incorrectly conclude the daemon is unreachable. A short note here keeps the example accurate for the common case while flagging the override.
| A useful probe is: | |
| ```bash | |
| curl -s -X POST http://127.0.0.1:47657/session-api \ | |
| -H 'content-type: application/json' \ | |
| --data '{"action":"list"}' | |
| ``` | |
| A useful probe is (port defaults to `47657`; use `$HUNK_MCP_PORT` if you have overridden it): | |
| ```bash | |
| curl -s -X POST http://127.0.0.1:47657/session-api \ | |
| -H 'content-type: application/json' \ | |
| --data '{"action":"list"}' |
<details><summary>Prompt To Fix With AI</summary>
`````markdown
This is a comment left during a code review.
Path: skills/hunk-review/SKILL.md
Line: 50-56
Comment:
The curl probe hardcodes port `47657`, but the daemon port is configurable via `HUNK_MCP_PORT`. A user who has set that env var will get a silent failure from the probe and may incorrectly conclude the daemon is unreachable. A short note here keeps the example accurate for the common case while flagging the override.
```suggestion
A useful probe is (port defaults to `47657`; use `$HUNK_MCP_PORT` if you have overridden it):
```bash
curl -s -X POST http://127.0.0.1:47657/session-api \
-H 'content-type: application/json' \
--data '{"action":"list"}'
How can I resolve this? If you propose a fix, please make it concise.
| ```bash | ||
| curl -s -X POST http://127.0.0.1:47657/session-api \ | ||
| -H 'content-type: application/json' \ | ||
| --data '{"action":"list"}' | ||
| ``` | ||
|
|
||
| If that direct API call shows sessions, rerun the same `hunk session ...` command with the | ||
| agent's local-network or sandbox-escalation mechanism instead of restarting Hunk. |
There was a problem hiding this comment.
HUNK_MCP_PORT is set, the probe will silently fail and lead users down the wrong troubleshooting path.
| ```bash | |
| curl -s -X POST http://127.0.0.1:47657/session-api \ | |
| -H 'content-type: application/json' \ | |
| --data '{"action":"list"}' | |
| ``` | |
| If that direct API call shows sessions, rerun the same `hunk session ...` command with the | |
| agent's local-network or sandbox-escalation mechanism instead of restarting Hunk. | |
| ```bash | |
| curl -s -X POST http://127.0.0.1:47657/session-api \ | |
| -H 'content-type: application/json' \ | |
| --data '{"action":"list"}' |
Note: the default port is
47657. If you have setHUNK_MCP_PORT, substitute that value in the URL above.
If that direct API call shows sessions, rerun the same hunk session ... command with the
agent's local-network or sandbox-escalation mechanism instead of restarting Hunk.
<details><summary>Prompt To Fix With AI</summary>
`````markdown
This is a comment left during a code review.
Path: docs/agent-workflows.md
Line: 34-41
Comment:
Same hardcoded port concern as in the SKILL file — if `HUNK_MCP_PORT` is set, the probe will silently fail and lead users down the wrong troubleshooting path.
```suggestion
```bash
curl -s -X POST http://127.0.0.1:47657/session-api \
-H 'content-type: application/json' \
--data '{"action":"list"}'
Note: the default port is
47657. If you have setHUNK_MCP_PORT, substitute that value in the URL above.
If that direct API call shows sessions, rerun the same hunk session ... command with the
agent's local-network or sandbox-escalation mechanism instead of restarting Hunk.
How can I resolve this? If you propose a fix, please make it concise.
|
I feel like I just want to abandon the HTTP server and move to a socket instead. Would that solve the sandbox issue? |
|
Yes, I think that is the cleaner direction and should avoid the specific Codex failure mode because the agent would no longer need loopback TCP access. Note that the Unix-domain socket would also still need to live somewhere visible to both processes like the existing runtime dir and have sensible per-user permissions for the agent to see it in sandbox mode. If you want to replace the transport soon, I’m happy to either close this or keep it as a temporary solution until then. Fine either way. |
2 participants
Adds a short troubleshooting note for agent workflows where
hunk session *cannot reach the local loopback daemon from inside a sandbox.I hit this specifically with Codex sandbox mode:
hunk session listreported no active sessions even though a Hunk TUI was running and the daemon's/session-apiendpoint showed aregistered session. This can make the normal "No active Hunk sessions" guidance misleading.
The docs now suggest probing
/session-apidirectly and rerunning session commands with the agent's local-network or sandbox-escalation mechanism when the daemon does have registeredsessions.
I’d avoid mentioning Claude unless someone confirms it has the same behavior.