Problem Statement
Agents running inside OpenShell sandboxes need a standard way to discover and invoke tools that execute outside the sandbox. These tools may depend on host-local state or host network reachability, such as OS keychain access, already-authenticated CLIs or loopback services on the user’s machine.
Today, OpenShell does not have a reserved route for this. Policy authors must expose each tool provider as an ordinary network route. That makes host-tool discovery harder, leaks backend routing details into sandbox policy, and treats host-tool execution like normal sandbox egress even though the trust boundary is different.
OpenShell needs a reserved sandbox-local route for host tools, so agents can discover and invoke approved tools while policy and audit still apply. The sandbox should call one stable OpenShell-owned route, not learn the backend route for each tool provider.
Proposed Design
Add a reserved sandbox-local route for host-tool discovery and invocation.
The reserved route should be handled by OpenShell, stay policy-aware, and forward accepted requests through the authenticated gateway path. The gateway can then relay the request to a configured tool broker. The broker owns the tool catalog, authorization, backend selection, host-side execution, result shaping, and broker-side audit.
Alternatives Considered
Use ordinary sandbox network routes for each tool provider
This keeps the current model, but it makes every host-tool provider look like normal egress. It also exposes backend route details to sandbox policy and gives agents no stable route for tool discovery.
Run host tools directly in the gateway
This would put host-tool policy, credential handling, backend routing, execution, result shaping, and audit inside the gateway. That expands gateway responsibility beyond transport validation.
Copy tools into the sandbox
This only works for tools that do not depend on host-local state or host network context. It fails for keychains, existing CLI auth, host sockets, VPN reachability and user-specific tool versions.
Agent Investigation
No response
Checklist
Problem Statement
Agents running inside OpenShell sandboxes need a standard way to discover and invoke tools that execute outside the sandbox. These tools may depend on host-local state or host network reachability, such as OS keychain access, already-authenticated CLIs or loopback services on the user’s machine.
Today, OpenShell does not have a reserved route for this. Policy authors must expose each tool provider as an ordinary network route. That makes host-tool discovery harder, leaks backend routing details into sandbox policy, and treats host-tool execution like normal sandbox egress even though the trust boundary is different.
OpenShell needs a reserved sandbox-local route for host tools, so agents can discover and invoke approved tools while policy and audit still apply. The sandbox should call one stable OpenShell-owned route, not learn the backend route for each tool provider.
Proposed Design
Add a reserved sandbox-local route for host-tool discovery and invocation.
The reserved route should be handled by OpenShell, stay policy-aware, and forward accepted requests through the authenticated gateway path. The gateway can then relay the request to a configured tool broker. The broker owns the tool catalog, authorization, backend selection, host-side execution, result shaping, and broker-side audit.
Alternatives Considered
Use ordinary sandbox network routes for each tool provider
This keeps the current model, but it makes every host-tool provider look like normal egress. It also exposes backend route details to sandbox policy and gives agents no stable route for tool discovery.
Run host tools directly in the gateway
This would put host-tool policy, credential handling, backend routing, execution, result shaping, and audit inside the gateway. That expands gateway responsibility beyond transport validation.
Copy tools into the sandbox
This only works for tools that do not depend on host-local state or host network context. It fails for keychains, existing CLI auth, host sockets, VPN reachability and user-specific tool versions.
Agent Investigation
No response
Checklist