docs: add SSH sandbox transport guide for local deployments

[howie]

Summary

• Add SSH config snippet to config.toml.example with inline comments explaining each flag (especially why -T is mandatory)
• Add docs/ssh-sandbox.md covering the full setup: architecture, MCP access patterns from inside a sandbox, and known limitations
• Add brief "SSH Sandbox (Local Deployments)" section to README linking to the new doc

Changes

This is a docs-only PR addressing issue #104. Zero code changes — SSH works as a transparent stdio byte pipe, which is exactly how AcpConnection::spawn() communicates with agents.

Closes #104

Test plan

• Verify config.toml.example has no syntax errors in the commented SSH block
• Verify all links in README and docs/ssh-sandbox.md resolve correctly
• Review SSH flags match the experimentally verified results from the issue

🤖 Generated with Claude Code

[chaodu-agent]

🟡 Needs Rebase — Excellent docs-only PR, all content is net-new, but stale with merge conflicts.

Baseline Check (Step 0)

Field	Value
State	OPEN
Mergeable	CONFLICTING
Created	2026-04-09 (22 days ago)
Last commit	2026-04-09
Author	@ChunHao-dev
Changes	+151 / -0, docs only
Labels	closing-soon

Main has: Zero SSH sandbox content. No docs/ssh-sandbox.md, no SSH config in config.toml.example, no SSH section in README. All 151 lines are net-new.

四問框架

1. 解決什麼問題

Users running OpenAB locally (not in K8s) need a way to sandbox agent processes on a remote host via SSH. The current docs only cover K8s pod-based deployments.

2. 怎麼解決

Adds docs/ssh-sandbox.md with full SSH transport guide (architecture, MCP access patterns, known limitations), SSH config snippet in config.toml.example, and a brief README section linking to the new doc.

3. 考慮過什麼

Explains why -T (no PTY) is mandatory (PTY corrupts JSON-RPC), BatchMode=yes for daemon context, StrictHostKeyChecking=accept-new for TOFU.

4. 最佳方案嗎

Solid approach — SSH as transparent stdio byte pipe is exactly how AcpConnection::spawn() works. The doc covers the three most common MCP access patterns (host DNS alias, SSH port forwarding, network bridge).

🟢 INFO

• The -T flag explanation table is outstanding — clearly explains why PTY corrupts JSON-RPC. Will save users hours of debugging.
• BatchMode=yes rationale is correct and important for daemon context.
• MCP access patterns cover the three most common setups cleanly.
• Known limitations section is honest and actionable (especially kill_on_drop + ControlMaster warning).
• ASCII architecture diagram is a nice touch.
• Zero code changes — pure docs, low risk.

🟡 NIT

1. TOFU security note — StrictHostKeyChecking=accept-new is trust-on-first-use. For a doc that motivates itself with "meaningful attack surface," consider noting the tradeoff and suggesting users pin the host key first: ssh-keyscan sandbox-host >> ~/.ssh/known_hosts.

2. Config snippet duplication — The SSH config appears in three places (README, config.toml.example, docs/ssh-sandbox.md). Consider having README and config.toml.example reference docs/ssh-sandbox.md as the single source of truth.

3. working_dir = "/tmp" is misleading — This sets the local cwd for the SSH process, not the remote agent's working directory. A brief inline comment would help.

🔴 SUGGESTED CHANGES

1. Merge conflict — PR status is CONFLICTING. Needs rebase onto current main before merge.

[github-actions]

⚠️ This PR is missing a Discord Discussion URL in the body.

All PRs must reference a prior Discord discussion to ensure community alignment before implementation.

Please edit the PR description to include a link like:

Discord Discussion URL: https://discord.com/channels/...

This PR will be automatically closed in 3 days if the link is not added.

[howie]

Discord Discuss: https://discord.com/channels/1491295327620169908/1499981797231169536

[chaodu-agent]

APPROVE ✅ — Rebase done, docs-only PR, 100% net-new. One small action needed to clear closing-soon label.

📋 Update from Previous Review

Previous review (2026-05-01) was Conditional Approve pending rebase. Contributor has:

• ✅ Rebased — now MERGEABLE (was CONFLICTING)
• ✅ Added Discord Discussion URL (in comment)
• ✅ working_dir comment in config.toml.example already addresses NIT #3

🧭 Four-Question Framework

1. What problem does this solve?

Users running OpenAB locally (not in K8s) need a way to sandbox agent processes. The current docs only cover K8s pod-based deployments. Running claude --acp directly on the host gives the agent full filesystem and network access — a meaningful attack surface for a Discord bot accepting messages from arbitrary users.

2. How does it solve it?

Adds docs/ssh-sandbox.md (114 lines) — a comprehensive SSH transport guide covering:

• Architecture diagram (current vs proposed)
• SSH flag explanations (why -T is mandatory, BatchMode=yes for daemon context)
• Sandbox options table (OrbStack, nspawn, remote, Docker)
• MCP server access patterns (host DNS alias, SSH port forwarding, network bridge)
• Known limitations (kill_on_drop, startup latency, key auth requirement)

Plus SSH config snippet in config.toml.example and a brief README section linking to the new doc.

3. What was considered?

SSH as a transparent stdio byte pipe is exactly how AcpConnection::spawn() works — zero code changes needed. The doc correctly identifies the three most common MCP access patterns and honestly documents limitations.

4. Is this the best approach?

Yes. Well-structured, honest about tradeoffs, and covers the practical scenarios users will encounter.

🚦 Traffic Light

🟢 INFO — The -T flag explanation table is outstanding. Will save users hours of debugging PTY-corrupted JSON-RPC streams.

🟢 INFO — Known limitations section is honest and actionable, especially the kill_on_drop + ControlMaster warning.

🟢 INFO — Zero code changes, pure docs, low risk. All content is net-new (no SSH sandbox docs exist on main).

🟡 NIT — Discord Discussion URL was posted in a comment but not added to the PR body. The closing-soon bot checks the body, so the label is still present. Please add Discord Discussion URL: https://discord.com/channels/1491295327620169908/1499981797231169536 to the PR body to clear it.

---

Review by 超渡法師 🙏 — great docs contribution!

[chaodu-agent]

超渡法師 Review — PR #155

1. What problem does it solve?

OpenAB's default local deployment runs the agent subprocess with full host permissions. There's no documentation on how to isolate the agent in a sandbox for local (non-k3s) deployments. This PR documents SSH as a zero-code-change transport to run the agent inside an isolated VM or container.

2. How does it solve it?

Docs-only PR (+151 lines, 0 deletions) across 3 files:

• docs/ssh-sandbox.md — Standalone guide: architecture diagram, full config snippet with SSH flags, -T vs -t comparison, sandbox environment options, MCP access patterns, known limitations.
• README.md — New "SSH Sandbox" section with config example and link to full doc.
• config.toml.example — Commented-out SSH sandbox config block.

3. What was considered?

• Intentionally narrow scope — document SSH as a supported command pattern, no code changes.
• Acknowledged kill_on_drop limitation and ControlMaster trade-off.
• Orthogonal to issue feat: Add HTTP trigger alongside Discord — unified broker for scheduler + Discord #99 (input side vs execution side).

4. Is this the best approach?

Yes. SSH as a stdio byte pipe is a clean fit for AcpConnection::spawn(). The documentation is thorough, technically precise, and covers edge cases users would actually hit.

---

Traffic Light

🟢 INFO — Excellent technical depth

• The -T vs -t vs -tt comparison table is genuinely useful. Most SSH guides don't explain why PTY breaks JSON-RPC.
• MCP access patterns section (host DNS alias, port forwarding, network bridge) covers the three most common scenarios.
• Inline comments on every SSH flag match the pattern of existing config examples.
• 100% net-new content, no duplication with main.

🟢 INFO — Good architectural framing

• "Current vs Proposed" ASCII diagram clearly communicates the security improvement.
• Explicit scope boundaries prevent scope creep expectations.

🟡 NIT

1. README.md:185: working_dir comment missing — The config.toml.example version has # local cwd for the SSH process, not the remote agent's workdir but the README snippet just says working_dir = "/tmp" without clarification.
2. docs/ssh-sandbox.md:42: StrictHostKeyChecking=accept-new security note — This is TOFU. A one-sentence note like "Pre-populate known_hosts in production environments for stronger verification" would help security-conscious users.
3. docs/ssh-sandbox.md:99-100: ControlMaster caveat — Users may not realize their global ~/.ssh/config applies. Consider: "Check your ~/.ssh/config for ControlMaster auto — if present, add ControlMaster no to the sandbox host entry."

---

Verdict

🟢 Looks good — Clean, well-scoped docs PR. No blocking issues. The NITs are minor improvements for security-conscious users.