Proxy endpoint drops query-based file API parameters in single-host bridge mode

[ulgerang]

Upstream Issue Draft

Title

OpenSandbox proxy endpoint drops query-based file API parameters in single-host bridge mode

Summary

In a single-host Docker bridge deployment, requesting an exec endpoint with use_server_proxy=true returns a proxy base that works for body-based execd routes such as POST /directories and POST /files/upload, but fails for query-based file routes such as GET /files/search?path=/workspace.

The earliest wrong transition is the move from direct execd endpoint resolution to forced server proxy mode. After that boundary change, Holon's workspace preflight fails with 400 MISSING_QUERY before the agent loop even starts.

Environment

• OpenSandbox server launched by /opt/opensandbox/bin/opensandbox-server --config /root/.opensandbox/config.toml
• Deployment model: single-host Docker bridge mode
• Server bind: 127.0.0.1:8081
• Auth: enabled with OPEN-SANDBOX-API-KEY header requirement
• Runtime image: opensandbox/execd:v1.0.6
• Egress image: opensandbox/egress:v1.0.1
• Client workload: Holon sandbox attach and workspace preflight

Expected Behavior

• If GET /v1/sandboxes/{id}/endpoints/44772?use_server_proxy=true returns a proxy endpoint, subsequent proxied execd file APIs should preserve their query parameters.
• GET /sandboxes/{id}/proxy/44772/files/search?path=/workspace should succeed the same way the non-proxied endpoint does.

Observed Behavior

• Proxied body-based execd APIs succeed.
• Proxied query-based file search fails with 400 MISSING_QUERY.
• The client-visible failure is:
  • sandbox_preflight_unreachable ... http_status=400 upstream_code=MISSING_QUERY upstream_message="missing query parameter 'path'"

Minimal Reproduction

1. Start OpenSandbox in single-host bridge mode with auth enabled and execd_image = "opensandbox/execd:v1.0.6".
2. Create a sandbox and wait for it to become available.
3. Request the proxied exec endpoint:
   • GET /v1/sandboxes/{sandbox_id}/endpoints/44772?use_server_proxy=true
4. Use the returned proxy base for execd file operations.
5. Call a body-based route such as:
   • POST /sandboxes/{sandbox_id}/proxy/44772/directories
6. Call a query-based route such as:
   • GET /sandboxes/{sandbox_id}/proxy/44772/files/search?path=/workspace

Result Matrix

• POST /sandboxes/{id}/proxy/44772/directories -> 200
• POST /sandboxes/{id}/proxy/44772/files/upload -> 200
• GET /sandboxes/{id}/proxy/44772/files/search?path=/workspace -> 400 MISSING_QUERY

Evidence

• OpenSandbox access log for sandbox 867e72b5-9a4f-48d6-9948-1426b6c14938:
  • GET /v1/sandboxes/867e72b5-9a4f-48d6-9948-1426b6c14938/endpoints/44772?use_server_proxy=true HTTP/1.1 -> 200
  • POST /sandboxes/867e72b5-9a4f-48d6-9948-1426b6c14938/proxy/44772/directories HTTP/1.1 -> 200
  • POST /sandboxes/867e72b5-9a4f-48d6-9948-1426b6c14938/proxy/44772/files/upload HTTP/1.1 -> 200
  • GET /sandboxes/867e72b5-9a4f-48d6-9948-1426b6c14938/proxy/44772/files/search?path=%2Fworkspace HTTP/1.1 -> 400
• Holon failure run:
  • run_0ff971197f781f3c
  • terminal error: sandbox_preflight_unreachable layer=runtime_preflight ... http_status=400 upstream_code=MISSING_QUERY
• Control run after rollback to non-forced proxy resolution:
  • run_f1d47aa6d109b4e4
  • attach succeeded at 2026-03-12 19:30:40 KST
  • first shell succeeded at 2026-03-12 19:31:14 KST
  • run status: completed

Impact

• Clients following the documented bridge-mode proxy path can fail during initial workspace verification even when sandbox creation and body-based execd routes are healthy.
• This makes a global use_server_proxy=true rollout unsafe for Holon on the current OpenSandbox server/runtime combination.

Suspected Root Cause

The proxy forwarding layer appears to mishandle query strings for proxied GET file routes, while preserving body-based POST routes. This looks like a boundary bug in proxy request translation rather than an execd runtime failure.

Requested Upstream Follow-up

• Confirm whether proxied execd GET routes are expected to support query strings in single-host bridge mode.
• Add an integration test that covers:
  • endpoint resolution with use_server_proxy=true
  • at least one body-based proxied execd route
  • at least one query-based proxied execd route such as /files/search?path=...
• Clarify the docs if mixed direct/proxy behavior is currently required.