Skip to content

feat(gateway): add gateway.terminal_backend sandbox override for messaging sessions#4816

Open
dsr-restyn wants to merge 2 commits into
NousResearch:mainfrom
dsr-restyn:feat/gateway-docker-sandbox
Open

feat(gateway): add gateway.terminal_backend sandbox override for messaging sessions#4816
dsr-restyn wants to merge 2 commits into
NousResearch:mainfrom
dsr-restyn:feat/gateway-docker-sandbox

Conversation

@dsr-restyn

Copy link
Copy Markdown
Contributor

Summary

  • Adds a gateway.terminal_backend config key that overrides terminal.backend for all gateway (Telegram, Discord, etc.) sessions
  • Emits a startup warning when the gateway runs with the local backend and no override is configured
  • Extends Docker sandboxing to execute_code — when TERMINAL_ENV=docker, the Python subprocess runs inside the container via a UDS socket bind-mount
  • Adds gateway.sandbox_image and gateway.sandbox_lifetime config keys

Motivation

Closes #4281.

The dangerous-command approval system explicitly skips approval checks when a container backend is active (the container is the security boundary). This means running the gateway with terminal.backend: local gives no sandbox isolation AND no approval gate. This PR makes it easy to enforce Docker sandboxing for all gateway sessions without affecting local CLI usage.

Changes

  • gateway/sandbox_config.py (new): helpers — apply_gateway_backend_to_env(), should_warn_insecure_gateway(), get_gateway_terminal_backend()
  • tools/execute_code_docker.py (new): runs the execute_code child subprocess inside Docker with UDS socket bind-mounted for tool RPC
  • gateway/run.py: apply gateway backend override at startup; emit warning when running with local backend
  • hermes_cli/config.py: add gateway.terminal_backend, gateway.sandbox_image, gateway.sandbox_lifetime defaults
  • hermes_cli/status.py: show gateway sandbox backend + image in /status output
  • tests/gateway/test_sandbox_config.py (new): 12 unit tests for sandbox config helpers
  • tests/tools/test_execute_code_docker.py (new): 14 unit tests for Docker subprocess wrapper and routing logic

Test Plan

  • 26 unit tests pass (pytest tests/tools/test_execute_code_docker.py tests/gateway/test_sandbox_config.py)
  • All syntax checks pass
  • Local path (non-docker) is unchanged — gated by TERMINAL_ENV=docker env var

Usage

# config.yaml
gateway:
  terminal_backend: docker          # docker, modal, daytona, ssh, singularity
  sandbox_image: python:3.11        # defaults to terminal.docker_image
  sandbox_lifetime: 3600            # seconds before idle cleanup

Notes for Reviewers

  • The execute_code_docker.py wrapper uses --network=host so the UDS RPC socket path is identical inside and outside the container
  • The docker path only activates when both TERMINAL_ENV=docker AND TERMINAL_DOCKER_IMAGE are set — so local CLI sessions are never affected
  • The gateway.sandbox_lifetime key is stored in config but lifetime enforcement (container cleanup) is left for a follow-up (the per-session task_id already provides isolation via existing DockerEnvironment)

dsr-restyn and others added 2 commits April 3, 2026 20:47
…aging sessions

Closes NousResearch#4281. When gateway.terminal_backend is set in config.yaml, all gateway
sessions use that backend instead of the global terminal.backend. The execute_code
tool also respects the Docker backend when TERMINAL_ENV=docker, running the Python
subprocess inside the configured container. A startup warning is emitted when the
gateway runs with the local backend and no gateway override is configured.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- execute_code_docker: use named containers for proper timeout kill (zombie fix)
- execute_code_docker: remove stale container_id variable
- execute_code_docker: document interrupt limitation in docstring
- sandbox_config: validate terminal_backend against known backends before applying
- sandbox_config: log info when gateway backend override is applied
- gateway/run.py: use module-level _gateway_raw_cfg instead of re-reading config.yaml
- tests: add assertions for named container, docker kill on timeout, invalid backend rejection

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@dsr-restyn dsr-restyn force-pushed the feat/gateway-docker-sandbox branch from e597c1b to b13061a Compare April 3, 2026 20:47
@alt-glitch alt-glitch added type/feature New feature or request P2 Medium — degraded but workaround exists comp/gateway Gateway runner, session dispatch, delivery tool/terminal Terminal execution and process management tool/code-exec execute_code sandbox backend/docker Docker container execution labels May 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backend/docker Docker container execution comp/gateway Gateway runner, session dispatch, delivery P2 Medium — degraded but workaround exists tool/code-exec execute_code sandbox tool/terminal Terminal execution and process management type/feature New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Enforce sandboxed execution for messaging platform sessions

2 participants