Skip to content

docs(agent): note sandboxed session access #229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
skalidindi wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(agent): note sandboxed session access #229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a68ebb4
docs(agent): note sandboxed session access
skalidindi May 7, 2026
4f3dd88
docs: mention configurable session daemon port
skalidindi May 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions docs/agent-workflows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,20 @@ When a Hunk TUI starts, it registers with a local loopback daemon. `hunk session

Most users only need `hunk session ...`. Use `hunk mcp serve` only for manual startup or debugging of the local daemon.

Some agent sandboxes restrict localhost access. If an agent reports no active sessions while a
Hunk TUI is visibly running, first check whether the agent can reach the loopback daemon:

```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 set `HUNK_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.
Comment on lines +34 to +43
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps Bot May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 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.

Suggested change
```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 set HUNK_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 set HUNK_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.


## The commands you will use most

### Inspect the current review
Expand Down
20 changes: 19 additions & 1 deletion skills/hunk-review/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,24 @@ Use `--source` only for advanced reloads where the live session you want to cont

## Commands

### Sandboxed agents

`hunk session *` talks to the local Hunk daemon over loopback. Some agent sandboxes may block
those localhost requests, which can make `hunk session list` report no sessions even while a Hunk
TUI is open. If the user can see Hunk running, check whether the sandbox can reach the daemon
before assuming the session failed to register.

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"}'
```

If the direct API shows sessions, rerun the same `hunk session ...` command with the agent's
local-network or sandbox-escalation mechanism.

### Inspect

```bash
Expand Down Expand Up @@ -145,7 +163,7 @@ Guidelines:
## Common errors

- **"No visible diff file matches ..."** -- the file is not in the loaded review. Check `context`, then `reload` if needed.
- **"No active Hunk sessions"** -- ask the user to open Hunk in their terminal.
- **"No active Hunk sessions"** -- if the user can see Hunk running, first check sandbox loopback access (see [Sandboxed agents](#sandboxed-agents) above); otherwise ask the user to open Hunk in their terminal.
- **"Multiple active sessions match"** -- pass `<session-id>` explicitly.
- **"No active Hunk session matches session path ..."** -- for advanced split-path reloads, verify the live window `Path` via `hunk session get` or `list`, then use `--session-path`.
- **"Pass the replacement Hunk command after `--`"** -- include `--` before the nested `diff` / `show` command.
Expand Down