Skip to content

The agent that grows with you

refactor: move the Singularity terminal backend out of core into the singularity catalog plugin

Tekniumd99af4187b65
diff --git a/.env.example b/.env.example
index 15660e9b525..614c4407663 100644
--- a/.env.example
+++ b/.env.example
@@ -225,10 +225,10 @@
# =============================================================================
# TERMINAL TOOL CONFIGURATION
# =============================================================================
-# Backend type: "local", "singularity", "docker", "modal", or "ssh"
+# Backend type: "local", "docker", "modal", "daytona", "vercel_sandbox", "ssh", or a plugin
+# backend (e.g. "singularity" from `hermes plugins install singularity`).
# Terminal backend is configured in ~/.hermes/config.yaml (terminal.backend).
# Use 'hermes setup' or 'hermes config set terminal.backend docker' to change.
-# Supported: local, docker, singularity, modal, ssh
#
# Only override here if you need to force a backend without touching config.yaml:
# TERMINAL_ENV=local
@@ -237,15 +237,14 @@
# Useful on systems where Docker's storage driver is broken or unavailable.
# HERMES_DOCKER_BINARY=/usr/local/bin/podman
-# Container images (for singularity/docker/modal backends)
+# Container images (for docker/modal backends; the singularity plugin reads TERMINAL_SINGULARITY_IMAGE)
# TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
-# TERMINAL_SINGULARITY_IMAGE=docker://nikolaik/python-nodejs:python3.11-nodejs20
TERMINAL_MODAL_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
# Working directory for terminal commands
# For local backend: "." means current directory (resolved automatically)
-# For remote backends (ssh/docker/modal/singularity): use an absolute path
+# For remote backends (ssh/docker/modal/plugin sandboxes): use an absolute path
# INSIDE the target environment, or leave unset for the backend's default
# (/root for modal, / for docker, ~ for ssh). Do NOT use a host-local path.
# Usually managed by config.yaml (terminal.cwd) — uncomment to override
@@ -278,7 +277,7 @@ TERMINAL_LIFETIME_SECONDS=300
# SUDO SUPPORT (works with ALL terminal backends)
# =============================================================================
# If set, enables sudo commands by piping password via `sudo -S`.
-# Works with: local, docker, singularity, modal, and ssh backends.
+# Works with: local, docker, modal, ssh and plugin backends that run sudo (singularity).
#
# SECURITY WARNING: Password stored in plaintext. Only use on trusted machines.
#
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 750d624c865..4f0cc8b0ca2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -292,7 +292,7 @@ hermes-agent/
│ ├── skill_tools.py # Skill search, load, manage
│ └── environments/ # Terminal execution backends
│ ├── base.py # BaseEnvironment ABC
-│ ├── local.py, docker.py, ssh.py, singularity.py, modal.py, daytona.py
+│ ├── local.py, docker.py, ssh.py, modal.py, daytona.py
│
├── gateway/ # Messaging gateway
│ ├── run.py # GatewayRunner facade (~5.5k LOC); phases in run_*.py (startup, inbound, turn, busy, ...)
diff --git a/README.md b/README.md
index 0412dd2203e..53e5cd95082 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,7 @@ Use any model you want — [Nous Portal](https://portal.nousresearch.com), OpenR
<tr><td><b>A closed learning loop</b></td><td>Agent-curated memory with periodic nudges. Autonomous skill creation after complex tasks. Skills self-improve during use. FTS5 session search with LLM summarization for cross-session recall. <a href="https://github.com/plastic-labs/honcho">Honcho</a> dialectic user modeling. Compatible with the <a href="https://agentskills.io">agentskills.io</a> open standard.</td></tr>
<tr><td><b>Scheduled automations</b></td><td>Built-in cron scheduler with delivery to any platform. Daily reports, nightly backups, weekly audits — all in natural language, running unattended.</td></tr>
<tr><td><b>Delegates and parallelizes</b></td><td>Spawn isolated subagents for parallel workstreams. In Desktop, choose their provider, model, and limits under Settings → Model → Subagents, then Apply the complete route. Write Python scripts that call tools via RPC, collapsing multi-step pipelines into zero-context-cost turns.</td></tr>
-<tr><td><b>Runs anywhere, not just your laptop</b></td><td>Seven terminal backends — local, Docker, SSH, Singularity, Modal, Daytona, and Vercel Sandbox. Daytona and Modal offer serverless persistence — your agent's environment hibernates when idle and wakes on demand, costing nearly nothing between sessions. Run it on a $5 VPS or a GPU cluster.</td></tr>
+<tr><td><b>Runs anywhere, not just your laptop</b></td><td>Six built-in terminal backends — local, Docker, SSH, Modal, Daytona, and Vercel Sandbox — plus plugin backends such as Singularity/Apptainer. Daytona and Modal offer serverless persistence — your agent's environment hibernates when idle and wakes on demand, costing nearly nothing between sessions. Run it on a $5 VPS or a GPU cluster.</td></tr>
<tr><td><b>Research-ready</b></td><td>Batch trajectory generation, trajectory compression for training the next generation of tool-calling models.</td></tr>
</table>
diff --git a/agent/prompt_builder.py b/agent/prompt_builder.py
index 1936663609d..68375dea3d4 100644
--- a/agent/prompt_builder.py
+++ b/agent/prompt_builder.py
@@ -756,12 +756,11 @@ WSL_ENVIRONMENT_HINT = (
# Backends that run commands (and every file tool) in a separate container / remote host: host OS/$HOME/cwd
# would mislead, so the agent only sees the machine it can touch.
-_REMOTE_TERMINAL_BACKENDS = frozenset({"docker", "singularity", "modal", "daytona", "ssh", "vercel_sandbox", "managed_modal"})
+_REMOTE_TERMINAL_BACKENDS = frozenset({"docker", "modal", "daytona", "ssh", "vercel_sandbox", "managed_modal"})
# Used when the live probe fails: only what the backend choice implies — never an invented cwd/user/$HOME.
_BACKEND_FALLBACK_DESCRIPTIONS: dict[str, str] = {
"docker": "a Docker container (Linux)",
- "singularity": "a Singularity container (Linux)",
"modal": "a Modal sandbox (Linux)",
"managed_modal": "a managed Modal sandbox (Linux)",
"daytona": "a Daytona workspace (Linux)",
@@ -835,7 +834,7 @@ def _tenv_read(name: str, default: str = "") -> str:
return terminal_env(name, default)
-_BACKEND_IMAGE_KEYS = {b: f"{b}_image" for b in ("docker", "singularity", "modal", "daytona")}
+_BACKEND_IMAGE_KEYS = {b: f"{b}_image" for b in ("docker", "modal", "daytona")}
# (config key, default) pairs forwarded to _create_environment's container_config.
# Single-line POSIX probe; `2>/dev/null` keeps a missing binary from polluting output.
# OS/kernel only: the sandbox's user, $HOME and cwd are user-identifying and nothing consumes
diff --git a/agent/terminal_env_provider.py b/agent/terminal_env_provider.py
index 44c53a68a8f..971b5b54a1b 100644
--- a/agent/terminal_env_provider.py
+++ b/agent/terminal_env_provider.py
@@ -47,7 +47,7 @@ class TerminalEnvironmentProvider(ProviderBase):
a local argv that runs its remainder (``bash -c <script>``, passed through as separate words)
inside the sandbox with stdin/stdout open, or ``None`` when it cannot right now. Bot Desktop,
``computer_use`` and the browser then follow the terminal into this backend, as they do for
- docker/ssh/singularity, instead of refusing.
+ docker/ssh, instead of refusing.
``default_cwd`` home resolution and ``exec_prefix`` need the environment object itself, so they
work for in-process plugins only; under ``plugins.isolation: host`` the environment reaches Hermes
diff --git a/agent/terminal_env_registry.py b/agent/terminal_env_registry.py
index aea19baafcf..24e3e0b2536 100644
--- a/agent/terminal_env_registry.py
+++ b/agent/terminal_env_registry.py
@@ -24,7 +24,7 @@ logger = logging.getLogger(__name__)
#: Names owned by in-tree backends in tools/environments/ — never
#: registrable by plugins. Includes internal-mode aliases (managed_modal).
BUILTIN_BACKEND_NAMES = frozenset({
- "local", "docker", "singularity", "modal", "managed_modal",
+ "local", "docker", "modal", "managed_modal",
"daytona", "vercel_sandbox", "ssh",
})
diff --git a/batch_runner.py b/batch_runner.py
index 0ab87f7d179..d3e12305b8f 100644
--- a/batch_runner.py
+++ b/batch_runner.py
@@ -178,7 +178,7 @@ def _prepare_container_image(
prompt_index: int, prompt_data: dict[str, Any], batch_num: int, task_id: str, config: dict[str, Any]
) -> Optional[dict[str, Any]]:
"""Register the dataset row's per-prompt container image (``image``/``docker_image``)
- for this task's sandbox (Docker, Modal, Singularity, Daytona).
+ for this task's sandbox (Docker, Modal, Daytona, or a plugin backend such as Singularity).
For Docker the image is verified (local cache, then pull) before spending tokens on the
agent loop; Modal pulls server-side so no local check. Returns a failure result when the
@@ -218,8 +218,9 @@ def _prepare_container_image(
overrides = {
"docker_image": container_image,
"modal_image": container_image,
- "singularity_image": f"docker://{container_image}",
"daytona_image": container_image,
+ # A plugin backend reads its own ``<backend>_image`` override (tools.terminal_tool._select_image).
+ f"{env_type}_image": container_image,
}
if prompt_data.get("cwd"):
overrides["cwd"] = prompt_data["cwd"]
diff --git a/cli-config.yaml.example b/cli-config.yaml.example
index 2edf63bd63f..f2a0eb6b1d6 100644
--- a/cli-config.yaml.example
+++ b/cli-config.yaml.example
@@ -503,9 +503,10 @@ terminal:
# # - "SETUID"
# -----------------------------------------------------------------------------
-# OPTION 4: Singularity/Apptainer container
+# OPTION 4: Singularity/Apptainer container (the official `singularity` plugin)
# Commands run in a Singularity container (common in HPC environments)
# Great for: HPC clusters, shared compute environments
+# Install it first: hermes plugins install singularity
# -----------------------------------------------------------------------------
# terminal:
# backend: "singularity"
@@ -541,7 +542,7 @@ terminal:
# container_disk: 10240 # Daytona max is 10GB per sandbox
#
-# --- Container resource limits (docker, singularity, modal, daytona -- ignored for local/ssh) ---
+# --- Container resource limits (docker, modal, daytona, container plugin backends -- ignored for local/ssh) ---
# These settings apply to all container backends. They control the resources
# allocated to the sandbox and whether its filesystem persists across sessions.
container_cpu: 1 # CPU cores
diff --git a/gateway/media_fetch.py b/gateway/media_fetch.py
index 8868181f30e..3239d8fc054 100644
--- a/gateway/media_fetch.py
+++ b/gateway/media_fetch.py
@@ -5,7 +5,7 @@ is ssh / daytona / vercel (any backend that reports its ``_remote_home``), the a
on another filesystem, so the tag was silently dropped. This module pulls the file through the
active environment's ``fetch_file`` into the document cache (already an allowlisted delivery root)
and hands back the host copy. Backends without a known remote home (docker outside its mounts,
-modal, singularity) still get the conservative any-component denylist, so a ``/root/...`` artifact
+modal, plugin sandboxes) still get the conservative any-component denylist, so a ``/root/...`` artifact
there is not fetched — set ``_remote_home`` on the environment to opt in.
The remote path is screened against the same denylist as local deliveries BEFORE any bytes move,
diff --git a/gateway/run.py b/gateway/run.py
index 51be63e929a..2db32d7fea6 100644
--- a/gateway/run.py
+++ b/gateway/run.py
@@ -2006,7 +2006,6 @@ def _bridge_terminal_config_to_env(_terminal_cfg: dict) -> None:
"lifetime_seconds": "TERMINAL_LIFETIME_SECONDS",
"docker_image": "TERMINAL_DOCKER_IMAGE",
"docker_forward_env": "TERMINAL_DOCKER_FORWARD_ENV",
- "singularity_image": "TERMINAL_SINGULARITY_IMAGE",
"modal_image": "TERMINAL_MODAL_IMAGE",
"daytona_image": "TERMINAL_DAYTONA_IMAGE",
"vercel_runtime": "TERMINAL_VERCEL_RUNTIME",
diff --git a/hermes_cli/cli_config_load.py b/hermes_cli/cli_config_load.py
index 9639720df08..dd6355c6d45 100644
--- a/hermes_cli/cli_config_load.py
+++ b/hermes_cli/cli_config_load.py
@@ -80,12 +80,12 @@ def _parse_service_tier_config(raw: str) -> str | None:
# terminal.<key> -> TERMINAL_<KEY> env var. Container-resource keys apply to docker,
-# singularity, modal, daytona and vercel_sandbox only (ignored for local/ssh).
+# modal, daytona, vercel_sandbox and container plugin backends (ignored for local/ssh).
_TERMINAL_ENV_MAPPINGS = {
key: f"TERMINAL_{key.upper()}"
for key in (
"degraded_mode", "cwd", "timeout", "home_mode", "lifetime_seconds", "docker_image",
- "docker_forward_env", "singularity_image", "modal_image", "daytona_image", "vercel_runtime", "vercel_image",
+ "docker_forward_env", "modal_image", "daytona_image", "vercel_runtime", "vercel_image",
"ssh_host", "ssh_user", "ssh_port", "ssh_key", "container_cpu", "container_memory",
"container_disk", "container_persistent", "docker_volumes", "docker_env", "docker_extra_args",
"docker_shm_size", "docker_mount_cwd_to_workspace", "docker_network", "docker_run_as_host_user",
@@ -187,8 +187,7 @@ def _cli_config_defaults():
"model": {"default": "", "base_url": "", "provider": "auto"},
"terminal": {
"env_type": "local", "cwd": ".", "home_mode": "auto", "lifetime_seconds": 300, # cwd "." -> os.getcwd()
- "docker_image": img, "docker_forward_env": [], "singularity_image": f"docker://{img}",
- "modal_image": img, "daytona_image": img, "docker_volumes": [],
+ "docker_image": img, "docker_forward_env": [], "modal_image": img, "daytona_image": img, "docker_volumes": [],
"docker_mount_cwd_to_workspace": False, # opt-in only: sandbox isolation
"docker_shared_container_key": "",
},
diff --git a/hermes_cli/config.py b/hermes_cli/config.py
index 9a13eb83322..7c6158868fd 100644
--- a/hermes_cli/config.py
+++ b/hermes_cli/config.py
@@ -2127,7 +2127,7 @@ TERMINAL_CONFIG_ENV_MAP = {
key: f"TERMINAL_{key.upper()}"
for key in (
"modal_mode", "degraded_mode", "cwd", "temp_dir", "timeout", "lifetime_seconds",
- "docker_image", "docker_forward_env", "singularity_image", "modal_image",
+ "docker_image", "docker_forward_env", "modal_image",
"daytona_image", "vercel_runtime", "vercel_image", "ssh_host", "ssh_user", "ssh_port", "ssh_key",
"container_cpu", "container_memory", "container_disk", "container_persistent",
"docker_volumes", "docker_env", "docker_mount_cwd_to_workspace", "docker_network",
diff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.py
index fca53626866..bd0cbc8302b 100644
--- a/hermes_cli/config_defaults.py
+++ b/hermes_cli/config_defaults.py
@@ -5,7 +5,7 @@ docs of config.yaml.
"""
-#: Image every container terminal backend (docker/modal/daytona/singularity) uses unless the
+#: Image every container terminal backend (docker/modal/daytona, the singularity plugin) uses unless the
#: user pins one. LEGACY_SANDBOX_IMAGES are the plain defaults that preceded the desktop stack
#: (the 3.14 pin shipped between the two without a migration); a saved config still holding one
#: is the template copied, and the config migration unsets it, never a user's own pin.
@@ -353,12 +353,11 @@ DEFAULT_CONFIG = {
# reads host values) — useful under systemd without the user's shell env. Example:
# {"SSH_AUTH_SOCK": "/run/user/1000/ssh-agent.sock"}
"docker_env": {},
- "singularity_image": f"docker://{DEFAULT_SANDBOX_IMAGE}",
"modal_image": DEFAULT_SANDBOX_IMAGE,
"daytona_image": DEFAULT_SANDBOX_IMAGE,
"vercel_image": DEFAULT_VERCEL_IMAGE, # vercel_sandbox backend only: a Vercel-managed or VCR image
"vercel_runtime": "", # deprecated by Vercel; a legacy runtime pin (node24 | node22 | python3.13) overrides vercel_image
- # Container limits (docker, singularity, modal, daytona, vercel_sandbox; not local/ssh).
+ # Container limits (docker, modal, daytona, vercel_sandbox, container plugin backends; not local/ssh).
"container_cpu": 1,
"container_memory": 5120, # MB (default 5GB)
"container_disk": 51200, # MB (default 50GB)
@@ -2542,7 +2541,7 @@ DEFAULT_CONFIG = {
# 0 keeps screens up until stopped.
"idle_stop_minutes": 30,
# Where the screen (and with it computer_use and the bot's browser) runs.
- # auto follow the terminal backend: inside the docker / ssh / singularity sandbox when one is
+ # auto follow the terminal backend: inside the docker / ssh / streaming plugin sandbox when one is
# configured, on the gateway host when terminal.backend is local. A sandbox backend that
# cannot host a screen (modal, daytona, vercel) REFUSES rather than quietly running the
# desktop on the host beside the sandbox you chose for the agent.
diff --git a/hermes_cli/config_show.py b/hermes_cli/config_show.py
index 6135e2d9826..4ef9f64c533 100644
--- a/hermes_cli/config_show.py
+++ b/hermes_cli/config_show.py
@@ -91,7 +91,6 @@ def _show_terminal_section(config: dict[str, Any]) -> None:
from hermes_cli.config_defaults import DEFAULT_SANDBOX_IMAGE as default_img, DEFAULT_VERCEL_IMAGE as _DEFAULT_VERCEL_IMAGE
backend_lines = {
'docker': lambda: [f" Docker image: {terminal.get('docker_image', default_img)}"],
- 'singularity': lambda: [f" Image: {terminal.get('singularity_image', 'docker://' + default_img)}"],
'modal': lambda: [
f" Modal image: {terminal.get('modal_image', default_img)}",
f" Modal token: {configured('MODAL_TOKEN_ID')}"],
diff --git a/hermes_cli/doctor_tools.py b/hermes_cli/doctor_tools.py
index 1a812c511cb..0d1b08c4147 100644
--- a/hermes_cli/doctor_tools.py
+++ b/hermes_cli/doctor_tools.py
@@ -190,7 +190,7 @@ def _check_git_and_rg(should_fix: bool, f: Finding) -> None:
check_info(f"Install for faster search: {_system_package_install_cmd('ripgrep')}")
-_BUILTIN_TERMINAL_BACKENDS = {"local", "docker", "singularity", "modal", "managed_modal", "daytona", "vercel_sandbox", "ssh"}
+_BUILTIN_TERMINAL_BACKENDS = {"local", "docker", "modal", "managed_modal", "daytona", "vercel_sandbox", "ssh"}
def _check_docker_backend(terminal_env: str, running_in_container: bool, issues: list[str]) -> None:
diff --git a/hermes_cli/left_core_migration.py b/hermes_cli/left_core_migration.py
index 4bb1c57c614..c084b88f8b3 100644
--- a/hermes_cli/left_core_migration.py
+++ b/hermes_cli/left_core_migration.py
@@ -147,6 +147,32 @@ def langfuse_in_use(home: Path, *, process_env: bool = False) -> bool:
return _bundled_plugin_selected(home, "langfuse")
+def singularity_in_use(home: Path, *, process_env: bool = False) -> bool:
+ """What made core run its Singularity backend for *home*: ``terminal.backend`` (or the legacy
+ ``terminal.env_type``) set to ``singularity`` in its config (managed overlay applied, as the bridge
+ reads it), else ``TERMINAL_ENV=singularity`` in its ``.env``. config.yaml wins over ``.env``, as in
+ the bridge. *process_env* (the active home at startup only) also counts a ``TERMINAL_ENV`` the
+ process received from its environment (systemd unit, Docker, shell export)."""
+ from gateway import config_loader
+ try:
+ terminal = config_loader.read_yaml_layers(home).get("terminal")
+ except Exception: # malformed config.yaml: the bridge reads nothing from it either
+ logger.debug("left-core: unreadable config for %s", home, exc_info=True)
+ terminal = None
+ terminal = terminal if isinstance(terminal, dict) else {}
+ configured = str(terminal.get("backend") or terminal.get("env_type") or "").strip()
+ if not configured:
+ from agent.secret_scope import load_env_file
+ configured = str(load_env_file(home / ".env").get("TERMINAL_ENV") or "").strip()
+ if not configured and process_env:
+ from agent.secret_scope import UnscopedSecretError, get_secret
+ try:
+ configured = str(get_secret("TERMINAL_ENV", "") or "").strip()
+ except UnscopedSecretError: # multiplexed with no profile scope bound: no process value is this home's
+ configured = ""
+ return configured.lower() == "singularity"
+
+
@dataclass(frozen=True)
class LeftCoreFeature:
plugin: str # catalog entry name == installed plugin name
@@ -185,6 +211,8 @@ class LeftCoreFeature:
# catalog plugin in ``plugins.enabled`` / ``plugins.disabled`` (the loader's gate, an
# administrator's pinned list) and for every `hermes plugins <verb>` (:func:`legacy_plugin_alias`).
plugin_key: str = ""
+ # ``terminal.backend`` value the plugin registers: unknown-backend errors name the install command.
+ terminal_backend: str = ""
LEFT_CORE: tuple[LeftCoreFeature, ...] = (
@@ -216,6 +244,12 @@ LEFT_CORE: tuple[LeftCoreFeature, ...] = (
unchanged="the conversation tools keep their names; MCP clients change their args to [\"mcp-serve\"]",
command="mcp-serve", old_command="hermes mcp serve",
),
+ LeftCoreFeature(
+ plugin="singularity", label="Singularity/Apptainer terminal backend", in_use=singularity_in_use,
+ unchanged="terminal.backend: singularity, terminal.singularity_image (TERMINAL_SINGULARITY_IMAGE) "
+ "and the container_* limits are unchanged",
+ terminal_backend="singularity",
+ ),
)
def _install_sentence(feature: LeftCoreFeature) -> str:
@@ -231,6 +265,13 @@ def platform_install_hint(platform: str) -> str:
return f". {_install_sentence(feature)}" if feature else ""
+def terminal_backend_install_hint(backend: str) -> str:
+ """For a ``terminal.backend`` value that left core: the sentence that names its install command for
+ the active home, else ``""``. Appended to "unknown terminal backend" errors."""
+ feature = next((f for f in LEFT_CORE if f.terminal_backend and f.terminal_backend == backend), None)
+ return f". {_install_sentence(feature)}" if feature else ""
+
+
def legacy_plugin_alias(name: str) -> str:
"""The catalog plugin a bundled key that left core now names (``observability/langfuse`` ->
``langfuse``), else ``""``."""
diff --git a/hermes_cli/plugins.py b/hermes_cli/plugins.py
index 0e5f3b1601f..b62729861a3 100644
--- a/hermes_cli/plugins.py
+++ b/hermes_cli/plugins.py
@@ -1037,7 +1037,7 @@ _SCOPED_PROVIDER_REGISTRARS: tuple[tuple[str, str, str, str, str, str, dict[str,
"terminal environment provider",
"Register a :class:`agent.terminal_env_provider.TerminalEnvironmentProvider`; ``provider.name`` "
"is matched by ``terminal.backend`` when no built-in backend has that name. Built-in names (local, "
- "docker, singularity, modal, daytona, vercel_sandbox, ssh) are rejected — plugins never shadow "
+ "docker, modal, daytona, vercel_sandbox, ssh) are rejected — plugins never shadow "
"in-tree backends.",
{"normalize": "lower", "reject_message": "Plugin '%s' terminal environment provider rejected: %s"}),
("register_secret_source", "secret_source", "agent.secret_sources.registry",
diff --git a/hermes_cli/setup_terminal.py b/hermes_cli/setup_terminal.py
index 92f4191de4c..fa92244a920 100644
--- a/hermes_cli/setup_terminal.py
+++ b/hermes_cli/setup_terminal.py
@@ -1,11 +1,10 @@
-"""Terminal-backend setup wizard (local/docker/singularity/modal/daytona/vercel/ssh/plugin).
+"""Terminal-backend setup wizard (local/docker/modal/daytona/vercel/ssh/plugin).
setup.py names are resolved through the module object so test patches on ``hermes_cli.setup.<name>``
take effect; setup.py re-exports the public entry points."""
import json
import logging
import os
-import shutil
from pathlib import Path
from tools import tool_backend_helpers
from tools.environments.docker import docker_runtime_name, find_docker
@@ -142,7 +141,7 @@ def _setup_backend_docker(config: dict) -> None:
_setup._info(None, "Docker sandboxes can be protected with the egress credential firewall.",
"It routes sandbox traffic through iron-proxy so containers receive "
"proxy tokens instead of real API keys.",
- " Docker only for now; Modal, SSH, Daytona, and Singularity are not wired yet.")
+ " Docker only for now; Modal, SSH, Daytona and plugin backends are not wired yet.")
if _setup.prompt_yes_no(" Enable egress firewall for Docker sandboxes?", False):
proxy_cfg = config.setdefault("proxy", {})
proxy_cfg["enabled"] = True
@@ -154,14 +153,6 @@ def _setup_backend_docker(config: dict) -> None:
_setup.print_info("Skipping egress firewall. You can enable it later with `hermes egress setup`.")
-def _setup_backend_singularity(config: dict) -> None:
- _setup.print_success("Terminal backend: Singularity/Apptainer")
- _report_binary(shutil.which("apptainer") or shutil.which("singularity"),
- "Singularity/Apptainer not found in PATH!",
- "Install: https://apptainer.org/docs/admin/main/installation.html")
- config["terminal"].setdefault("singularity_image", f"docker://{_SANDBOX_IMAGE}")
-
-
def _setup_backend_modal(config: dict) -> None:
_setup.print_success("Terminal backend: Modal")
_setup.print_info("Serverless cloud sandboxes. Each session gets its own container.")
@@ -270,9 +261,8 @@ _BUILTIN_TERMINAL_BACKENDS = [
("daytona", "Daytona - persistent cloud development environment"),
("vercel_sandbox", "Vercel Sandbox - cloud microVM with snapshot filesystem persistence")]
_TERMINAL_BACKEND_SETUP = {
- "local": _setup_backend_local, "docker": _setup_backend_docker, "singularity": _setup_backend_singularity,
- "modal": _setup_backend_modal, "daytona": _setup_backend_daytona, "vercel_sandbox": _setup_backend_vercel,
- "ssh": _setup_backend_ssh}
+ "local": _setup_backend_local, "docker": _setup_backend_docker, "modal": _setup_backend_modal,
+ "daytona": _setup_backend_daytona, "vercel_sandbox": _setup_backend_vercel, "ssh": _setup_backend_ssh}
# Backend -> env var mirrored from config after setup (config.yaml is the source of truth, but
# terminal_tool reads these from .env).
_BACKEND_ENV_MIRROR = {"modal": ("TERMINAL_MODAL_MODE", "modal_mode", "auto"),
@@ -281,15 +271,12 @@ _BACKEND_ENV_MIRROR = {"modal": ("TERMINAL_MODAL_MODE", "modal_mode", "auto"),
def setup_terminal_backend(config: dict):
"""Configure the terminal execution backend."""
- import platform as _platform
_setup.print_header("Terminal Backend")
_setup._info("Choose where Hermes runs shell commands and code.",
"This affects tool execution, file access, and isolation.",
f" Guide: {_setup._DOCS_BASE}/user-guide/configuration#terminal-backend-configuration", None)
current_backend = _setup.cfg_get(config, "terminal", "backend", default="local")
backends = list(_BUILTIN_TERMINAL_BACKENDS)
- if _platform.system() == "Linux":
- backends.append(("singularity", "Singularity/Apptainer - HPC-friendly container"))
# Plugin-registered backends (~/.hermes/plugins/). Fail-soft: a broken plugin must not take
# the wizard down.
plugin_backend_names = []
diff --git a/hermes_cli/web_routers/tools.py b/hermes_cli/web_routers/tools.py
index db77075b9ff..6c73851cc8e 100644
--- a/hermes_cli/web_routers/tools.py
+++ b/hermes_cli/web_routers/tools.py
@@ -6,7 +6,6 @@ monkeypatching on web_server stays authoritative.
"""
import asyncio
-import shutil
import subprocess
import sys
from typing import Any, Dict, List, Optional
@@ -82,12 +81,6 @@ def _probe_docker_backend(_cfg) -> tuple:
return ("unavailable", f"{runtime} probe failed: {exc}")
-def _probe_singularity_backend(_cfg) -> tuple:
- if shutil.which("singularity") or shutil.which("apptainer"):
- return ("ready", "")
- return ("needs_setup", "Neither singularity nor apptainer found on PATH.")
-
-
def _probe_ssh_backend(terminal_cfg: dict) -> tuple:
host = _terminal_cfg_value(terminal_cfg, "ssh_host", "TERMINAL_SSH_HOST")
user = _terminal_cfg_value(terminal_cfg, "ssh_user", "TERMINAL_SSH_USER")
@@ -125,7 +118,6 @@ def _probe_daytona_backend(_cfg) -> tuple:
_BACKEND_PROBES = {
"local": lambda _cfg: ("ready", ""),
"docker": _probe_docker_backend,
- "singularity": _probe_singularity_backend,
"ssh": _probe_ssh_backend,
"modal": _probe_modal_backend,
"daytona": _probe_daytona_backend,
diff --git a/hermes_cli/web_server_config.py b/hermes_cli/web_server_config.py
index 410ca1781b3..ca4377373da 100644
--- a/hermes_cli/web_server_config.py
+++ b/hermes_cli/web_server_config.py
@@ -81,7 +81,7 @@ _SCHEMA_OVERRIDES: dict[str, dict[str, Any]] = {
},
"terminal.backend": _select(
"Terminal execution backend",
- "local", "docker", "ssh", "modal", "daytona", "vercel_sandbox", "singularity",
+ "local", "docker", "ssh", "modal", "daytona", "vercel_sandbox",
),
# sync with _SUPPORTED_VERCEL_RUNTIMES in terminal_tool.py
"terminal.vercel_image": {
diff --git a/hermes_cli/web_server_profiles.py b/hermes_cli/web_server_profiles.py
index 07163158ab7..bbfd9c02c72 100644
--- a/hermes_cli/web_server_profiles.py
+++ b/hermes_cli/web_server_profiles.py
@@ -338,8 +338,6 @@ _TERMINAL_BACKENDS: list[dict[str, str]] = [
("local", "Local", "Run commands directly on this machine. No isolation."),
("docker", "Docker / Podman",
"Run commands in an isolated Docker or Podman container with a persistent workspace."),
- ("singularity", "Singularity / Apptainer",
- "Run commands in a Singularity/Apptainer container (HPC-friendly, rootless)."),
("modal", "Modal", "Run commands in a Modal cloud sandbox."),
("daytona", "Daytona", "Run commands in a Daytona cloud sandbox."),
("ssh", "SSH", "Run commands on a remote host over SSH."))]
diff --git a/plugins/AGENTS.md b/plugins/AGENTS.md
index c04972ea9d0..d721988f552 100644
--- a/plugins/AGENTS.md
+++ b/plugins/AGENTS.md
@@ -26,7 +26,8 @@ command. A hook with no concrete consumer is speculative infrastructure and is r
backends ship as standalone repos implementing the same `MemoryProvider` ABC, discovered through
the same path, integrated via `hermes memory setup` / `post_setup()`.
- **Other features that leave core** (Home Assistant platform + toolset, Oct 2026 →
- `plugin-catalog/homeassistant.yaml`; Spotify toolset → `plugin-catalog/spotify.yaml`) keep their
+ `plugin-catalog/homeassistant.yaml`; Spotify toolset → `plugin-catalog/spotify.yaml`; Singularity
+ terminal backend → `plugin-catalog/singularity.yaml`) keep their
names/config/env and get a row in
`hermes_cli/left_core_migration.py::LEFT_CORE` (catalog plugin + read-only "this home uses it"
predicate); `hermes update` and agent/gateway start install the plugin for homes that used it.
@@ -40,6 +41,8 @@ command. A hook with no concrete consumer is speculative infrastructure and is r
and a nested core command becomes a top-level plugin command (`command` + `old_command`:
`hermes mcp serve` → `hermes mcp-serve`). A feature with no in-home signal (MCP clients live
outside Hermes) gets an `in_use` that is always False: hint only, never an automatic install.
+ A built-in terminal backend leaves its name off `BUILTIN_BACKEND_NAMES` so the plugin can register it
+ (row field `terminal_backend`: unknown-backend errors name the install command).
- **No new third-party-product plugins (June 2026).** Observability/metrics backends, vendor SaaS
connectors, analytics dashboards, paid-service tie-ins ship as standalone plugin repos
(`~/.hermes/plugins/` or pip entry point) promoted in Discord `#plugins-skills-and-skins`. Reason:
diff --git a/skills/autonomous-ai-agents/hermes-agent/references/configuration.md b/skills/autonomous-ai-agents/hermes-agent/references/configuration.md
index a3bcffe3074..76ca658a8f2 100644
--- a/skills/autonomous-ai-agents/hermes-agent/references/configuration.md
+++ b/skills/autonomous-ai-agents/hermes-agent/references/configuration.md
@@ -9,7 +9,7 @@ Full reference: https://hermes-agent.nousresearch.com/docs/user-guide/configurat
|---------|-------------|
| `model` | `default`, `provider`, `base_url`, `api_key`, `context_length`, `aliases` |
| `agent` | `max_turns` (90), `tool_use_enforcement`, `service_tier`, `verify_on_stop` |
-| `terminal` | `backend` (local/docker/ssh/modal/daytona/singularity), `cwd`, `timeout` (180) |
+| `terminal` | `backend` (local/docker/ssh/modal/daytona/vercel_sandbox, or a plugin backend like singularity), `cwd`, `timeout` (180) |
| `compression` | `enabled`, `threshold` (0.50), `target_ratio` (0.20) |
| `display` | `skin`, `interface` (cli/tui), `language`, `show_reasoning`, `show_cost`, `pet` |
| `approvals` | `mode` (smart/manual/off), `timeout`, `cron_mode` |
diff --git a/skills/autonomous-ai-agents/hermes-agent/references/contributor-guide.md b/skills/autonomous-ai-agents/hermes-agent/references/contributor-guide.md
index b23f07c1760..02bdf928c91 100644
--- a/skills/autonomous-ai-agents/hermes-agent/references/contributor-guide.md
+++ b/skills/autonomous-ai-agents/hermes-agent/references/contributor-guide.md
@@ -116,7 +116,7 @@ Do not fake the host by patching `sys.platform` or platform probes.
Factual host/backend guidance (OS, `$HOME`, cwd, terminal backend, shell)
is emitted by `agent/prompt_builder.py::build_environment_hints()`. The key
invariant for prompt authors: with a **remote** terminal backend
-(`docker, singularity, modal, daytona, ssh, managed_modal`), host info is
+(`docker, modal, daytona, ssh, managed_modal`, plus plugin backends declaring `is_remote`), host info is
suppressed and *every* file tool runs inside the backend container — the
prompt must never describe the host the agent can't touch.
diff --git a/tests/agent/test_prompt_builder.py b/tests/agent/test_prompt_builder.py
index c0097d1226a..902fb088a09 100644
--- a/tests/agent/test_prompt_builder.py
+++ b/tests/agent/test_prompt_builder.py
@@ -838,7 +838,7 @@ class TestEnvironmentHints:
probe must use the bare call instead of dying on TypeError."""
import agent.prompt_builder as _pb
- monkeypatch.setenv("TERMINAL_ENV", "singularity")
+ monkeypatch.setenv("TERMINAL_ENV", "daytona")
_pb._clear_backend_probe_cache()
calls = []
@@ -859,7 +859,7 @@ class TestEnvironmentHints:
import tools.terminal_tool_backends as _tt
monkeypatch.setattr(_tt, "_create_environment", lambda **kw: _LegacyEnv())
- assert _pb._probe_remote_backend("singularity") is not None
+ assert _pb._probe_remote_backend("daytona") is not None
assert calls == ["bare"]
def test_probe_remote_backend_ssh_is_probe_only_and_torn_down(self, monkeypatch):
diff --git a/tests/fixtures/resolution_allowlist.json b/tests/fixtures/resolution_allowlist.json
index 6212baa0d15..0fce8d5a0fe 100644
--- a/tests/fixtures/resolution_allowlist.json
+++ b/tests/fixtures/resolution_allowlist.json
@@ -332,11 +332,6 @@
"symbol": "find_sqlite3_cli",
"kind": "bare_which"
},
- {
- "path": "hermes_cli/setup_terminal.py",
- "symbol": "_setup_backend_singularity",
- "kind": "bare_which"
- },
{
"path": "hermes_cli/setup_tts.py",
"symbol": "_install_neutts_deps",
@@ -408,11 +403,6 @@
"symbol": "_probe_gh_auth",
"kind": "bare_which"
},
- {
- "path": "hermes_cli/web_routers/tools.py",
- "symbol": "_probe_singularity_backend",
- "kind": "bare_which"
- },
{
"path": "hermes_constants.py",
"symbol": "find_node_executable",
@@ -518,11 +508,6 @@
"symbol": "_resolve_hermes_bin_dir",
"kind": "bare_which"
},
- {
- "path": "tools/environments/singularity.py",
- "symbol": "_find_singularity_executable",
- "kind": "bare_which"
- },
{
"path": "tools/environments/ssh.py",
"symbol": "_ensure_ssh_available",
@@ -573,11 +558,6 @@
"symbol": "run_tier1_scan",
"kind": "bare_which"
},
- {
- "path": "tools/terminal_tool_backends.py",
- "symbol": "<module>",
- "kind": "bare_which"
- },
{
"path": "tools/transcription_audio.py",
"symbol": "_convert_caf_to_wav",
diff --git a/tests/hermes_cli/test_agent_env_advertisement.py b/tests/hermes_cli/test_agent_env_advertisement.py
index b204241ff9c..aaf0bd18856 100644
--- a/tests/hermes_cli/test_agent_env_advertisement.py
+++ b/tests/hermes_cli/test_agent_env_advertisement.py
@@ -11,7 +11,7 @@ standard-var matching there is exact, so any other value is attributed to
The terminal backends additionally export both vars inside every wrapped
shell command (``BaseEnvironment._wrap_command``) so the marker reaches
-REMOTE backends (Docker/SSH/Modal/Daytona/Singularity/Vercel) whose exec
+REMOTE backends (Docker/SSH/Modal/Daytona/Vercel, remote plugin backends) whose exec
environment does not inherit the Hermes process env, and survives the
cross-session leak guard that strips ``HERMES_SESSION_*`` from subprocess
envs in engaged multi-session hosts.
diff --git a/tests/hermes_cli/test_left_core_singularity.py b/tests/hermes_cli/test_left_core_singularity.py
new file mode 100644
index 00000000000..dfab8205203
--- /dev/null
+++ b/tests/hermes_cli/test_left_core_singularity.py
@@ -0,0 +1,107 @@
+"""The Singularity terminal backend left core for the ``singularity`` catalog plugin: homes whose backend
+is ``singularity`` get the plugin once, the name is free for the plugin to register, and a home without
+it hears the install command instead of a bare "unknown backend".
+
+Real config/.env files under a temp home; the catalog lookup and the network install are stand-ins.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+import hermes_cli.left_core_migration as lcm
+
+
[email protected](autouse=True)
+def _fresh(monkeypatch, tmp_path):
+ monkeypatch.setattr(lcm, "_attempted", set())
+ monkeypatch.setattr(lcm, "_undelivered", {})
+ monkeypatch.delenv("TERMINAL_ENV", raising=False)
+ managed = tmp_path / "managed"
+ managed.mkdir()
+ monkeypatch.setenv("HERMES_MANAGED_DIR", str(managed))
+ import hermes_cli.memory_provider_migration as mpm
+ monkeypatch.setattr(mpm, "catalog_source", lambda name: name)
+
+
+def _home(tmp_path: Path, *, env: str = "", config: str = "") -> Path:
+ home = tmp_path / "home"
+ home.mkdir()
+ if env:
+ (home / ".env").write_text(env, encoding="utf-8")
+ if config:
+ (home / "config.yaml").write_text(config, encoding="utf-8")
+ return home
+
+
[email protected](("env", "config", "in_use"), [
+ ("", "terminal:\n backend: singularity\n", True),
+ ("", "terminal:\n env_type: singularity\n", True), # legacy key the bridge maps
+ ("TERMINAL_ENV=singularity\n", "", True),
+ ("TERMINAL_ENV=singularity\n", "terminal:\n backend: docker\n", False), # config.yaml wins, as in the bridge
+ ("", "terminal:\n backend: docker\n singularity_image: docker://x\n", False), # an image key alone is not use
+ ("", "", False),
+])
+def test_singularity_in_use_is_the_configured_backend(tmp_path, env, config, in_use):
+ assert lcm.singularity_in_use(_home(tmp_path, env=env, config=config)) is in_use
+
+
+def test_process_env_backend_counts_only_for_the_active_home(tmp_path, monkeypatch):
+ home = _home(tmp_path)
+ monkeypatch.setenv("TERMINAL_ENV", "singularity")
+ assert lcm.singularity_in_use(home) is False
+ assert lcm.singularity_in_use(home, process_env=True) is True
+
+
+def test_a_singularity_home_gets_the_plugin_once(tmp_path):
+ home = _home(tmp_path, config="terminal:\n backend: singularity\n singularity_image: docker://python:3.12\n")
+ calls, said = [], []
+
+ def install(name):
+ calls.append(name)
+ (home / "plugins" / name).mkdir(parents=True)
+ return {"ok": True}
+
+ assert lcm.migrate_home(home, install=install, say=said.append) == ["singularity"]
+ assert calls == ["singularity"]
+ assert "Singularity/Apptainer terminal backend moved out of core" in said[0]
+ assert "terminal.singularity_image" in said[0]
+ said.clear()
+ assert lcm.migrate_home(home, install=install, say=said.append) == []
+ assert calls == ["singularity"] and said == []
+
+
+def test_the_backend_name_is_free_for_the_plugin(monkeypatch):
+ from agent import terminal_env_registry as reg
+ from agent.terminal_env_provider import TerminalEnvironmentProvider
+
+ class _Stand(TerminalEnvironmentProvider):
+ name = "singularity"
+
+ def is_available(self):
+ return True
+
+ def create_environment(self, **kwargs):
+ return object()
+
+ previous = reg.snapshot_registration("singularity")
+ provider = _Stand()
+ reg.register_provider(provider)
+ try:
+ assert reg.get_provider("singularity") is provider
+ finally:
+ reg.restore_registration("singularity", provider, previous)
+
+
+def test_without_the_plugin_the_backend_error_names_the_install_command(tmp_path, monkeypatch):
+ monkeypatch.setenv("HERMES_HOME", str(_home(tmp_path)))
+ from tools import terminal_tool_backends as backends
+ assert backends._check_plugin_requirements({"env_type": "singularity"}) is False
+ reason = backends.terminal_backend_unavailable_reason()
+ assert "moved out of core into the 'singularity' plugin" in reason
+ assert "hermes plugins install singularity" in reason
+ with pytest.raises(ValueError, match="hermes plugins install singularity"):
+ backends._create_environment("singularity", image="", cwd="/root", timeout=10)
+ assert lcm.terminal_backend_install_hint("acmebox") == ""
diff --git a/tests/hermes_cli/test_terminal_backend_docker_probe.py b/tests/hermes_cli/test_terminal_backend_docker_probe.py
index 4145c084a10..bfaf1e9028e 100644
--- a/tests/hermes_cli/test_terminal_backend_docker_probe.py
+++ b/tests/hermes_cli/test_terminal_backend_docker_probe.py
@@ -29,7 +29,6 @@ def _hide_host_runtimes(monkeypatch):
monkeypatch.delenv("HERMES_DOCKER_BINARY", raising=False)
monkeypatch.setattr(docker_mod.shutil, "which", lambda name: None)
monkeypatch.setattr(docker_mod, "_DOCKER_SEARCH_PATHS", [])
- monkeypatch.setattr(tools_mod.shutil, "which", lambda name: None)
def test_probe_ready_when_only_podman_is_configured(tmp_path, monkeypatch):
diff --git a/tests/tools/test_approval_deny_rules.py b/tests/tools/test_approval_deny_rules.py
index 5b23b35cc26..9913c01a36d 100644
--- a/tests/tools/test_approval_deny_rules.py
+++ b/tests/tools/test_approval_deny_rules.py
@@ -221,7 +221,7 @@ class TestDenyOrdering:
)
@pytest.mark.parametrize(
"env_type",
- ["docker", "singularity", "modal", "daytona", "vercel_sandbox"],
+ ["docker", "modal", "daytona", "vercel_sandbox"],
)
def test_container_backend_cannot_skip_deny(
self, guard, env_type, deny_config, clean_env, monkeypatch):
@@ -239,7 +239,7 @@ class TestDenyOrdering:
)
@pytest.mark.parametrize(
"env_type",
- ["docker", "singularity", "modal", "daytona", "vercel_sandbox"],
+ ["docker", "modal", "daytona", "vercel_sandbox"],
)
def test_container_backend_still_skips_non_denied_command(
self, guard, env_type, deny_config, clean_env):
diff --git a/tests/tools/test_base_environment.py b/tests/tools/test_base_environment.py
index 93c5de092af..7915dff0942 100644
--- a/tests/tools/test_base_environment.py
+++ b/tests/tools/test_base_environment.py
@@ -27,7 +27,7 @@ def test_snapshot_store_reads_dict_and_tolerates_missing_or_damaged_file(tmp_pat
class _TestableEnv(BaseEnvironment):
"""Concrete subclass for testing base class methods."""
- _sudo_nopasswd_probe_supported = True
+ _passwordless_sudo_probe_supported = True
def __init__(self, cwd="/tmp", timeout=10):
super().__init__(cwd=cwd, timeout=timeout)
@@ -61,7 +61,7 @@ def test_nopasswd_probe_runs_sudo_n_inside_backend_only_when_supported(
monkeypatch, supported, returncode, expected, probed
):
env = _TestableEnv()
- env._sudo_nopasswd_probe_supported = supported
+ env._passwordless_sudo_probe_supported = supported
run = MagicMock(return_value=object())
monkeypatch.setattr(env, "_run_bash", run)
monkeypatch.setattr(env, "_wait_for_process", MagicMock(return_value={"returncode": returncode}))
diff --git a/tests/tools/test_bot_desktop_placement.py b/tests/tools/test_bot_desktop_placement.py
index 166ed317f23..06eadf003a5 100644
--- a/tests/tools/test_bot_desktop_placement.py
+++ b/tests/tools/test_bot_desktop_placement.py
@@ -2,7 +2,7 @@
Two invariants, both about the boundary a sandboxed user chose:
1. A sandbox backend that cannot host a screen never falls back to the gateway host silently; it refuses
- unless ``bot_desktop.placement: gateway`` opts in. Docker/ssh/singularity resolve to the sandbox.
+ unless ``bot_desktop.placement: gateway`` opts in. Docker/ssh resolve to the sandbox.
2. Every RFB byte between the pane and a sandbox-hosted Xvnc, and cua-driver's MCP stdio, go through the
terminal backend's exec prefix, never a host socket or a host binary.
"""
@@ -23,7 +23,6 @@ from tools.environments import streams
("auto", "local", placement.GATEWAY),
("auto", "docker", placement.TERMINAL),
("auto", "ssh", placement.TERMINAL),
- ("auto", "singularity", placement.TERMINAL),
("auto", "modal", placement.REFUSED),
("auto", "daytona", placement.REFUSED),
("gateway", "modal", placement.GATEWAY),
diff --git a/tests/tools/test_container_cwd_sanitize.py b/tests/tools/test_container_cwd_sanitize.py
index 3b6fe339761..66248984ea3 100644
--- a/tests/tools/test_container_cwd_sanitize.py
+++ b/tests/tools/test_container_cwd_sanitize.py
@@ -125,7 +125,6 @@ class TestFileOpsCwdSanitizedAtCallSite:
config = {
"env_type": env_type,
"docker_image": "pytorch/pytorch:latest",
- "singularity_image": "docker://pytorch/pytorch:latest",
"modal_image": "pytorch/pytorch:latest",
"daytona_image": "pytorch/pytorch:latest",
"cwd": config_cwd,
@@ -191,7 +190,7 @@ class TestFileOpsCwdSanitizedAtCallSite:
cwd = self._run_and_capture_cwd(monkeypatch, "/workspace/task42")
assert cwd == "/workspace/task42"
- def test_host_override_sanitized_on_singularity(self, monkeypatch):
+ def test_host_override_sanitized_on_daytona(self, monkeypatch):
cwd = self._run_and_capture_cwd(
- monkeypatch, "/Users/me/workspace", env_type="singularity")
+ monkeypatch, "/Users/me/workspace", env_type="daytona")
assert cwd == "/workspace"
diff --git a/tests/tools/test_credential_files.py b/tests/tools/test_credential_files.py
index 992147c2f5d..454aede54bb 100644
--- a/tests/tools/test_credential_files.py
+++ b/tests/tools/test_credential_files.py
@@ -520,7 +520,7 @@ class TestMapCachePathToContainer:
class TestToAgentVisiblePathPerBackend:
"""#76577 follow-up: translation covers every backend that relocates the
Hermes cache — not just docker — and skips the ones where the host path
- stays correct (local; singularity auto-binds the host home)."""
+ stays correct (local, unknown)."""
def _staged(self, tmp_path, monkeypatch):
hermes_home = tmp_path / ".hermes"
@@ -540,7 +540,7 @@ class TestToAgentVisiblePathPerBackend:
from tools.credential_files import to_agent_visible_cache_path
assert to_agent_visible_cache_path(staged) == "~/.hermes/attachments/drop.zip"
- @pytest.mark.parametrize("backend", ["local", "singularity", ""])
+ @pytest.mark.parametrize("backend", ["local", ""])
def test_untranslated_backends_keep_host_path(self, tmp_path, monkeypatch, backend):
staged = self._staged(tmp_path, monkeypatch)
monkeypatch.setenv("TERMINAL_ENV", backend)
diff --git a/tests/tools/test_file_tools_container_config.py b/tests/tools/test_file_tools_container_config.py
index 1db0213a175..e6f1a54111e 100644
--- a/tests/tools/test_file_tools_container_config.py
+++ b/tests/tools/test_file_tools_container_config.py
@@ -8,7 +8,6 @@ def _make_env_config(**overrides):
base = {
"env_type": "docker",
"docker_image": "test-image:latest",
- "singularity_image": "docker://test",
"modal_image": "test",
"daytona_image": "test",
"cwd": "/workspace",
@@ -42,7 +41,6 @@ class TestFileToolsContainerConfig:
patch("tools.terminal_tool._creation_locks_lock", __import__("threading").Lock()), \
patch("tools.terminal_tool_backends._create_environment", side_effect=fake_create_env), \
patch("tools.terminal_tool._start_cleanup_thread"), \
- patch("tools.terminal_tool._check_disk_usage_warning"), \
patch("tools.file_tools._file_ops_cache", {}), \
patch("tools.file_tools._file_ops_lock", __import__("threading").Lock()):
file_tools._get_file_ops(task_id)
diff --git a/tests/tools/test_hardline_blocklist.py b/tests/tools/test_hardline_blocklist.py
index cdd85c35a97..562907452f4 100644
--- a/tests/tools/test_hardline_blocklist.py
+++ b/tests/tools/test_hardline_blocklist.py
@@ -616,7 +616,7 @@ def test_container_backends_still_bypass(clean_session):
Hardline only protects environments with real host impact (local, ssh).
"""
- for env in ("docker", "singularity", "modal", "daytona", "vercel_sandbox"):
+ for env in ("docker", "modal", "daytona", "vercel_sandbox"):
r1 = check_dangerous_command("rm -rf /", env)
assert r1["approved"] is True, f"container {env} should still bypass"
r2 = check_all_command_guards("rm -rf /", env)
@@ -696,7 +696,7 @@ def test_sudo_stdin_guard_detects_without_password():
def test_sudo_stdin_guard_container_bypass(clean_session):
"""Containerized backends still bypass — they can't touch the host."""
- for env in ("docker", "singularity", "modal", "daytona", "vercel_sandbox"):
+ for env in ("docker", "modal", "daytona", "vercel_sandbox"):
for cmd in _SUDO_STDIN_BLOCK:
result = check_all_command_guards(cmd, env)
assert result["approved"] is True, f"container {env} should bypass sudo guard on {cmd!r}"
diff --git a/tests/tools/test_live_env_cwd_override_sanitize.py b/tests/tools/test_live_env_cwd_override_sanitize.py
index 14637a04f68..796642b99e7 100644
--- a/tests/tools/test_live_env_cwd_override_sanitize.py
+++ b/tests/tools/test_live_env_cwd_override_sanitize.py
@@ -43,7 +43,6 @@ WIN_WS = r"C:\Users\rashi\ai_workspace"
("docker", WIN_WS, WIN_WS, "/workspace"),
# Host path that is not mounted anywhere: leave the live env untouched.
("docker", None, WIN_WS, "/root"),
- ("singularity", None, "/Users/me/workspace", "/root"),
# In-sandbox override (ACP project switch) still applies on a container.
("docker", None, "/workspace/task42", "/workspace/task42"),
# Non-container backends apply the override verbatim.
diff --git a/tests/tools/test_local_interrupt_cleanup.py b/tests/tools/test_local_interrupt_cleanup.py
index b33aa74a9ab..e499a39820b 100644
--- a/tests/tools/test_local_interrupt_cleanup.py
+++ b/tests/tools/test_local_interrupt_cleanup.py
@@ -220,7 +220,6 @@ def test_exit_cleanup_kills_foreground_command_still_running(monkeypatch):
the host exiting mid-command would otherwise orphan it to init."""
from tools import terminal_tool_lifecycle
- monkeypatch.setattr(terminal_tool_lifecycle, "_scratch_paths", list)
env = LocalEnvironment(cwd="/tmp")
result: dict = {}
t = threading.Thread(target=lambda: result.update(env.execute("sleep 3517", timeout=600)), daemon=True)
diff --git a/tests/tools/test_managed_browserbase_and_modal.py b/tests/tools/test_managed_browserbase_and_modal.py
index f17e989968a..6af897bd9be 100644
--- a/tests/tools/test_managed_browserbase_and_modal.py
+++ b/tests/tools/test_managed_browserbase_and_modal.py
@@ -1,6 +1,5 @@
import os
import sys
-import tempfile
import threading
import types
from importlib.util import module_from_spec, spec_from_file_location
@@ -204,10 +203,6 @@ def _install_fake_tools_package():
EnvironmentConnectionError=_DummyConnectionError,
)
sys.modules["tools.environments.local"] = types.SimpleNamespace(LocalEnvironment=_DummyEnvironment)
- sys.modules["tools.environments.singularity"] = types.SimpleNamespace(
- _get_scratch_dir=lambda: Path(tempfile.gettempdir()),
- SingularityEnvironment=_DummyEnvironment,
- )
sys.modules["tools.environments.ssh"] = types.SimpleNamespace(SSHEnvironment=_DummyEnvironment)
sys.modules["tools.environments.docker"] = types.SimpleNamespace(DockerEnvironment=_DummyEnvironment)
sys.modules["tools.environments.modal"] = types.SimpleNamespace(ModalEnvironment=_DummyEnvironment)
diff --git a/tests/tools/test_modal_sandbox_fixes.py b/tests/tools/test_modal_sandbox_fixes.py
index a2adef6b0e2..59510029bde 100644
--- a/tests/tools/test_modal_sandbox_fixes.py
+++ b/tests/tools/test_modal_sandbox_fixes.py
@@ -114,7 +114,7 @@ class TestCwdHandling:
config = _tt_mod._get_env_config()
assert config["cwd"] == "/vercel/sandbox"
- @pytest.mark.parametrize("backend", ["modal", "docker", "singularity", "daytona"])
+ @pytest.mark.parametrize("backend", ["modal", "docker", "daytona"])
def test_default_cwd_is_root_for_container_backends(self, backend, monkeypatch):
"""Container backends should default to /root, not ~."""
monkeypatch.setenv("TERMINAL_ENV", backend)
@@ -277,7 +277,6 @@ class TestDockerHostBindApproval:
assert A._should_skip_container_guards("docker", has_host_access=False) is True
assert A._should_skip_container_guards("docker", has_host_access=True) is False
assert A._should_skip_container_guards("modal", has_host_access=True) is True
- assert A._should_skip_container_guards("singularity") is True
assert A._should_skip_container_guards("daytona") is True
assert A._should_skip_container_guards("local") is False
diff --git a/tests/tools/test_multiplex_tool_memo_scope.py b/tests/tools/test_multiplex_tool_memo_scope.py
index 7db773998e5..7b78ca33262 100644
--- a/tests/tools/test_multiplex_tool_memo_scope.py
+++ b/tests/tools/test_multiplex_tool_memo_scope.py
@@ -37,13 +37,12 @@ def _under(home, fn):
def test_checkpoint_and_snapshot_paths_follow_active_profile(two_profiles):
import tools.process_registry as pr
- from tools.environments import modal, singularity
+ from tools.environments import modal
prof_a, prof_b = two_profiles
_under(prof_a, pr._checkpoint_path) # warm under A
assert _under(prof_b, pr._checkpoint_path) == prof_b / "processes.json"
assert _under(prof_b, modal._snapshot_store) == prof_b / "modal_snapshots.json"
- assert _under(prof_b, singularity._snapshot_store) == prof_b / "singularity_snapshots.json"
assert _under(prof_a, pr._checkpoint_path) == prof_a / "processes.json"
diff --git a/tests/tools/test_notify_on_complete.py b/tests/tools/test_notify_on_complete.py
index 35922265451..a71dc2b63a9 100644
--- a/tests/tools/test_notify_on_complete.py
+++ b/tests/tools/test_notify_on_complete.py
@@ -288,7 +288,6 @@ def _silent_bg_base_config(tmp_path):
return {
"env_type": "local",
"docker_image": "",
- "singularity_image": "",
"modal_image": "",
"daytona_image": "",
"cwd": str(tmp_path),
diff --git a/tests/tools/test_parse_env_var.py b/tests/tools/test_parse_env_var.py
index e8f2d09f1f2..427c62930c6 100644
--- a/tests/tools/test_parse_env_var.py
+++ b/tests/tools/test_parse_env_var.py
@@ -48,12 +48,3 @@ class TestImportTimeEnvParsing:
assert mod.FOREGROUND_MAX_TIMEOUT == default
finally:
importlib.reload(_tt_mod)
-
- def test_invalid_disk_warning_threshold_falls_back_to_default(self):
- default = importlib.reload(_tt_mod).DISK_USAGE_WARNING_THRESHOLD_GB
- try:
- with patch.dict("os.environ", {"TERMINAL_DISK_WARNING_GB": "huge"}, clear=False):
- mod = importlib.reload(_tt_mod)
- assert mod.DISK_USAGE_WARNING_THRESHOLD_GB == default
- finally:
- importlib.reload(_tt_mod)
diff --git a/tests/tools/test_singularity_persistent_overlay.py b/tests/tools/test_singularity_persistent_overlay.py
deleted file mode 100644
index 42e70900277..00000000000
--- a/tests/tools/test_singularity_persistent_overlay.py
+++ /dev/null
@@ -1,80 +0,0 @@
-"""Persistent-overlay path safety for the Singularity environment.
-
-A raw task id used as an overlay directory name carries the same class of
-bug as the Docker persistent-sandbox mount path (#92414): colon-bearing
-session ids break bind specs and are unrepresentable on Windows. Overlay
-components must go through the shared sanitizer in tools.environments.base.
-"""
-
-from tools.environments import singularity as singularity_env
-from tools.environments.path_utils import sanitize_task_id_for_path
-
-
-def _stub_singularity(monkeypatch, tmp_path):
- monkeypatch.setattr(
- singularity_env, "_ensure_singularity_available", lambda: "/usr/bin/apptainer"
- )
- monkeypatch.setattr(
- singularity_env,
- "_get_or_build_sif",
- lambda image, executable="apptainer": str(tmp_path / "image.sif"),
- )
- monkeypatch.setattr(singularity_env, "_get_scratch_dir", lambda: tmp_path / "scratch")
- monkeypatch.setattr(
- singularity_env.SingularityEnvironment, "_start_instance", lambda self: None
- )
- monkeypatch.setattr(
- singularity_env.SingularityEnvironment, "init_session", lambda self: None
- )
-
-
-def test_persistent_overlay_dir_sanitizes_colon_in_task_id(monkeypatch, tmp_path):
- _stub_singularity(monkeypatch, tmp_path)
-
- task_id = "session:agent:main:telegram:dm:12345"
- env = singularity_env.SingularityEnvironment(
- image="python:3.11",
- persistent_filesystem=True,
- task_id=task_id,
- )
-
- assert env._overlay_dir is not None
- assert env._overlay_dir.name == f"overlay-{sanitize_task_id_for_path(task_id)}"
- assert ":" not in env._overlay_dir.name
- assert env._overlay_dir.is_dir()
-
-
-def test_persistent_overlay_dir_keeps_safe_task_ids_verbatim(monkeypatch, tmp_path):
- """Existing overlays for already-safe ids must keep resolving to the same
- directory — renaming would strand a user's persistent overlay state."""
- _stub_singularity(monkeypatch, tmp_path)
-
- env = singularity_env.SingularityEnvironment(
- image="python:3.11",
- persistent_filesystem=True,
- task_id="default",
- )
-
- assert env._overlay_dir is not None
- assert env._overlay_dir.name == "overlay-default"
-
-
-def test_distinct_session_keys_get_distinct_overlay_dirs(monkeypatch, tmp_path):
- """Sanitization must stay injective across backends: two ids that differ
- only in colon placement must not share one overlay."""
- _stub_singularity(monkeypatch, tmp_path)
-
- names = set()
- for task_id in (
- "session:agent:main:telegram:dm:111",
- "session_agent_main_telegram_dm_111",
- ):
- env = singularity_env.SingularityEnvironment(
- image="python:3.11",
- persistent_filesystem=True,
- task_id=task_id,
- )
- assert env._overlay_dir is not None
- names.add(env._overlay_dir.name)
-
- assert len(names) == 2, f"overlay dirs collided: {names}"
diff --git a/tests/tools/test_singularity_preflight.py b/tests/tools/test_singularity_preflight.py
deleted file mode 100644
index a90398e6526..00000000000
--- a/tests/tools/test_singularity_preflight.py
+++ /dev/null
@@ -1,47 +0,0 @@
-"""Tests for Singularity/Apptainer preflight availability check.
-
-Verifies that a clear error is raised when neither apptainer nor
-singularity is installed, instead of a cryptic FileNotFoundError.
-
-See: https://github.com/NousResearch/hermes-agent/issues/1511
-"""
-
-from unittest.mock import patch, MagicMock
-
-import pytest
-
-from tools.environments.singularity import (
- _find_singularity_executable,
- _ensure_singularity_available,
-)
-
-
-class TestFindSingularityExecutable:
- """_find_singularity_executable resolution tests."""
-
- def test_prefers_apptainer(self):
- """When both are available, apptainer should be preferred."""
- def which_both(name):
- return f"/usr/bin/{name}" if name in {"apptainer", "singularity"} else None
-
- with patch("shutil.which", side_effect=which_both):
- assert _find_singularity_executable() == "apptainer"
-
-
- def test_raises_when_neither_found(self):
- """Must raise RuntimeError with install instructions."""
- with patch("shutil.which", return_value=None):
- with pytest.raises(RuntimeError, match="Neither.*apptainer.*nor.*singularity"):
- _find_singularity_executable()
-
-
-class TestEnsureSingularityAvailable:
- """_ensure_singularity_available preflight tests."""
-
- def test_returns_executable_on_success(self):
- """Returns the executable name when version check passes."""
- fake_result = MagicMock(returncode=0, stderr="")
-
- with patch("shutil.which", side_effect=lambda n: "/usr/bin/apptainer" if n == "apptainer" else None), \
- patch("subprocess.run", return_value=fake_result):
- assert _ensure_singularity_available() == "apptainer"
diff --git a/tests/tools/test_skills_tool.py b/tests/tools/test_skills_tool.py
index a44afb76c17..7fa4974f817 100644
--- a/tests/tools/test_skills_tool.py
+++ b/tests/tools/test_skills_tool.py
@@ -725,7 +725,7 @@ class TestSkillViewPrerequisites:
@pytest.mark.parametrize(
"backend",
- ["ssh", "daytona", "docker", "singularity", "modal", "vercel_sandbox"],
+ ["ssh", "daytona", "docker", "modal", "vercel_sandbox"],
)
def test_remote_backend_becomes_available_after_local_secret_capture(
self, tmp_path, monkeypatch, backend
diff --git a/tests/tools/test_terminal_error_redaction.py b/tests/tools/test_terminal_error_redaction.py
index bc4446ef06e..55922b432a9 100644
--- a/tests/tools/test_terminal_error_redaction.py
+++ b/tests/tools/test_terminal_error_redaction.py
@@ -18,7 +18,6 @@ def _minimal_terminal_config(cwd="/tmp"):
"host_cwd": None,
"modal_mode": "auto",
"docker_image": "",
- "singularity_image": "",
"modal_image": "",
"daytona_image": "",
}
diff --git a/tests/tools/test_terminal_foreground_timeout_cap.py b/tests/tools/test_terminal_foreground_timeout_cap.py
index d80a8f463ac..785378fa24d 100644
--- a/tests/tools/test_terminal_foreground_timeout_cap.py
+++ b/tests/tools/test_terminal_foreground_timeout_cap.py
@@ -19,7 +19,6 @@ def _make_env_config(**overrides):
"host_cwd": None,
"modal_mode": "auto",
"docker_image": "",
- "singularity_image": "",
"modal_image": "",
"daytona_image": "",
}
diff --git a/tests/tools/test_terminal_output_transform_hook.py b/tests/tools/test_terminal_output_transform_hook.py
index f90786b80c7..49b46cd8c46 100644
--- a/tests/tools/test_terminal_output_transform_hook.py
+++ b/tests/tools/test_terminal_output_transform_hook.py
@@ -21,7 +21,6 @@ def _make_env_config(tmp_path, **overrides):
"host_cwd": None,
"modal_mode": "auto",
"docker_image": "",
- "singularity_image": "",
"modal_image": "",
"daytona_image": "",
}
diff --git a/tests/tools/test_terminal_plugin_image_override.py b/tests/tools/test_terminal_plugin_image_override.py
new file mode 100644
index 00000000000..55842aee620
--- /dev/null
+++ b/tests/tools/test_terminal_plugin_image_override.py
@@ -0,0 +1,21 @@
+"""A plugin terminal backend gets its per-task image override (``<backend>_image``, what batch runs
+register for the active backend), and that override marks the task as an isolated rollout like a
+built-in backend's image override does."""
+
+from tools import terminal_tool as tt
+
+
+def test_plugin_backend_reads_its_own_per_task_image_override():
+ overrides = {"docker_image": "python:3.12", "acmebox_image": "python:3.12"}
+ assert tt._select_image("acmebox", overrides, {}) == "python:3.12"
+ assert tt._select_image("acmebox", {"docker_image": "python:3.12"}, {}) == ""
+ assert tt._select_image("local", overrides, {}) == ""
+ assert tt._select_image("docker", overrides, {"docker_image": "cfg"}) == "python:3.12"
+
+
+def test_plugin_image_override_marks_an_isolated_rollout(monkeypatch):
+ monkeypatch.setattr(tt, "_task_env_overrides", {})
+ tt.register_task_env_overrides("rollout-1", {"acmebox_image": "python:3.12"})
+ tt.register_task_env_overrides("cwd-only", {"cwd": "/work"})
+ assert tt._has_isolation_overrides("rollout-1") is True
+ assert tt._has_isolation_overrides("cwd-only") is False
diff --git a/tests/tools/test_terminal_sandbox_builder_dispatch.py b/tests/tools/test_terminal_sandbox_builder_dispatch.py
index 5a84eaf5e5a..a486fe0f4e4 100644
--- a/tests/tools/test_terminal_sandbox_builder_dispatch.py
+++ b/tests/tools/test_terminal_sandbox_builder_dispatch.py
@@ -8,7 +8,6 @@ from tools import terminal_tool_backends as backends
@pytest.mark.parametrize(
("env_type", "expects_image"),
[
- ("singularity", True),
("daytona", True),
("vercel_sandbox", False),
],
diff --git a/tests/tools/test_terminal_self_repo_guard.py b/tests/tools/test_terminal_self_repo_guard.py
index 58235e30bee..1ba5af1a9cb 100644
--- a/tests/tools/test_terminal_self_repo_guard.py
+++ b/tests/tools/test_terminal_self_repo_guard.py
@@ -17,7 +17,6 @@ def _make_env_config(**overrides):
"host_cwd": None,
"modal_mode": "auto",
"docker_image": "",
- "singularity_image": "",
"modal_image": "",
"daytona_image": "",
}
diff --git a/tests/tools/test_terminal_tool_pty_fallback.py b/tests/tools/test_terminal_tool_pty_fallback.py
index 878852125cb..5e15b65e007 100644
--- a/tests/tools/test_terminal_tool_pty_fallback.py
+++ b/tests/tools/test_terminal_tool_pty_fallback.py
@@ -9,7 +9,6 @@ def _base_config(tmp_path):
return {
"env_type": "local",
"docker_image": "",
- "singularity_image": "",
"modal_image": "",
"daytona_image": "",
"cwd": str(tmp_path),
diff --git a/tests/tools/test_terminal_trailing_amp_auto_background.py b/tests/tools/test_terminal_trailing_amp_auto_background.py
index 77e7fba024e..a67bba32bfc 100644
--- a/tests/tools/test_terminal_trailing_amp_auto_background.py
+++ b/tests/tools/test_terminal_trailing_amp_auto_background.py
@@ -16,7 +16,7 @@ import pytest
def _env_config(cwd):
return {
"env_type": "local", "timeout": 180, "cwd": str(cwd), "host_cwd": None, "modal_mode": "auto",
- "docker_image": "", "singularity_image": "", "modal_image": "", "daytona_image": "",
+ "docker_image": "", "modal_image": "", "daytona_image": "",
}
diff --git a/tests/tui_gateway/test_remote_backend_launch_cwd.py b/tests/tui_gateway/test_remote_backend_launch_cwd.py
index 9c0bcfadfc5..67d6d22c235 100644
--- a/tests/tui_gateway/test_remote_backend_launch_cwd.py
+++ b/tests/tui_gateway/test_remote_backend_launch_cwd.py
@@ -81,7 +81,7 @@ def clean_registry():
registry._reset_for_tests()
[email protected]("backend", ["modal", "daytona", "singularity"])
[email protected]("backend", ["modal", "daytona"])
def test_sandbox_session_does_not_register_the_launch_dir(launch_dir, monkeypatch, backend):
_backend(monkeypatch, backend)
session = _fresh_session(f"launch-{backend}")
diff --git a/tools/AGENTS.md b/tools/AGENTS.md
index 4b3dda287e2..e26a07686b8 100644
--- a/tools/AGENTS.md
+++ b/tools/AGENTS.md
@@ -79,7 +79,7 @@ replaces the other browser tools when `browser.backend` is `browser-use`.
## Backends and providers inside tools/
Several tools front pluggable backends: terminal environments in `tools/environments/` (local,
-docker, ssh, modal, daytona, singularity; `terminal_tool_backends.py`, `tool_backend_helpers.py`),
+docker, ssh, modal, daytona; `terminal_tool_backends.py`, `tool_backend_helpers.py`),
browser (`browser_tool_*.py`: cdp, cloud, install, lifecycle, session, real_profile, vision), MCP
client (`mcp_tool_*.py`: config, discovery, transport, registration, content, errors), TTS
(`tts_tool_providers.py`, `tts_command_provider.py`), skills hub sources (`skills_hub_official.py`
diff --git a/tools/approval.py b/tools/approval.py
index 363b4cc9d0b..8176305c20a 100644
--- a/tools/approval.py
+++ b/tools/approval.py
@@ -1043,7 +1043,7 @@ def _should_skip_container_guards(env_type: str, has_host_access: bool = False)
exception once host paths are bind-mounted: ``rm -rf /workspace`` then reaches host files."""
if env_type == "docker":
return not has_host_access
- if env_type in ("singularity", "modal", "daytona", "vercel_sandbox"):
+ if env_type in ("modal", "daytona", "vercel_sandbox"):
return True
# Plugin backends declare the same classification through the provider ABI (#94400);
# fail-soft to False so an unknown or raising backend — or a raising registry
diff --git a/tools/bot_desktop/placement.py b/tools/bot_desktop/placement.py
index 0b4cb5de5a6..3fca08dc5a0 100644
--- a/tools/bot_desktop/placement.py
+++ b/tools/bot_desktop/placement.py
@@ -2,7 +2,7 @@
``bot_desktop.placement``:
``auto`` (default) follow the terminal backend when it is a sandbox that can host a stream
- (docker / ssh / singularity, or a plugin backend declaring ``supports_streams``); the
+ (docker / ssh, or a plugin backend declaring ``supports_streams``); the
gateway host when ``terminal.backend`` is local. A
sandbox backend that CANNOT host one (modal, daytona, vercel) resolves to ``refused``:
the user chose a sandbox for the agent's actions, so quietly running the screen, cua-driver
@@ -26,7 +26,7 @@ logger = logging.getLogger(__name__)
GATEWAY = "gateway"
TERMINAL = "terminal"
REFUSED = "refused"
-_STREAM_BACKENDS = ("docker", "ssh", "singularity")
+_STREAM_BACKENDS = ("docker", "ssh")
@dataclass(frozen=True)
diff --git a/tools/bot_desktop/runtime.py b/tools/bot_desktop/runtime.py
index e828e592795..e2fb537caa1 100644
--- a/tools/bot_desktop/runtime.py
+++ b/tools/bot_desktop/runtime.py
@@ -656,7 +656,7 @@ def start(*, wait_seconds: float = 15.0) -> DesktopStatus:
"""Start this profile's desktop (idempotent). Blocks until the launcher publishes its env file or
``wait_seconds`` pass; raises ``RuntimeError`` naming the blocker.
- ``bot_desktop.placement`` decides WHERE: inside the configured terminal backend (docker/ssh/singularity;
+ ``bot_desktop.placement`` decides WHERE: inside the configured terminal backend (docker/ssh/a streaming plugin backend;
``sandbox_host``), or on the gateway host (the rest of this function). A sandbox backend that cannot host
a screen refuses rather than silently falling back to the host beside it.
diff --git a/tools/bot_desktop/sandbox_host.py b/tools/bot_desktop/sandbox_host.py
index 9b707051047..a8a1a0495a4 100644
--- a/tools/bot_desktop/sandbox_host.py
+++ b/tools/bot_desktop/sandbox_host.py
@@ -1,4 +1,4 @@
-"""Bot Desktop hosted INSIDE the configured terminal backend (docker / ssh / singularity).
+"""Bot Desktop hosted INSIDE the configured terminal backend (docker / ssh / a plugin backend with streams).
Same launcher, same lease, same pane: only WHERE Xvnc + Xfce run changes. ``runtime`` decides between the
gateway host and this module via ``placement()``; callers keep using ``runtime.start/stop/status/desktop_env``.
@@ -235,7 +235,7 @@ def start(env: Any, profile: str, *, geometry: str, wait_seconds: float = 20.0,
if missing:
advice = plugin_image_advice(getattr(env, "_hermes_backend_name", None)) or (
f"use {SANDBOX_IMAGE_HINT} (the default sandbox base plus the desktop stack) as "
- f"terminal.docker_image / modal_image / singularity_image")
+ f"terminal.docker_image / modal_image")
raise RuntimeError(
f"Bot Desktop needs {', '.join(missing)} inside the terminal backend's sandbox. The configured image "
f"does not have them; {advice}, or set bot_desktop.placement: gateway.")
diff --git a/tools/code_execution_rpc.py b/tools/code_execution_rpc.py
index ebbf704ec49..e062d3e5e99 100644
--- a/tools/code_execution_rpc.py
+++ b/tools/code_execution_rpc.py
@@ -59,7 +59,7 @@ def _remote_write(env, remote_path: str, content: str, *, atomic: bool = False,
(``check=True`` raises on failure via _execute_checked).
The base64 payload always travels as ``stdin_data``: pipe-mode backends
- (ssh, docker, local, singularity: the real shared-host ones) deliver it on
+ (ssh, docker, local: the real shared-host ones) deliver it on
real stdin, so it never enters argv where a co-tenant can read it via
``/proc/*/cmdline``; ``BaseEnvironment.execute`` embeds it as a heredoc
for heredoc-mode backends (modal, daytona, vercel), and managed_modal
diff --git a/tools/credential_files.py b/tools/credential_files.py
index a962fe7d01e..9995902bf31 100644
--- a/tools/credential_files.py
+++ b/tools/credential_files.py
@@ -360,8 +360,8 @@ def to_agent_visible_cache_path(host_path: str, container_base: str = "/root/.he
Mirrors ``_agent_cache_base_for_env`` in tools/image_generation_tool.py: docker/modal mount at
``/root/.hermes``; ssh/daytona/vercel_sandbox under ``~/.hermes``; plugin backends declare
- ``cache_path_base`` (None = host paths stay correct); local/singularity/unknown unchanged
- (Apptainer auto-binds the host home, so translation would dangle).
+ ``cache_path_base`` (None = host paths stay correct, e.g. the singularity plugin); local/unknown
+ unchanged.
* docker / modal — bind-mounted (docker) or per-file-synced (modal) at ``/root/.hermes`` (the
*container_base* default). * ssh / daytona / vercel_sandbox — file-synced under the remote user's home;
diff --git a/tools/env_probe.py b/tools/env_probe.py
index 75f72058337..af12ebc005d 100644
--- a/tools/env_probe.py
+++ b/tools/env_probe.py
@@ -34,7 +34,7 @@ _WAIT_ALREADY_TIMED_OUT = False # after one full wait, later callers only peek
# Keep in sync with agent/prompt_builder.py:_REMOTE_TERMINAL_BACKENDS.
# Duplicated rather than imported to avoid a circular import.
_REMOTE_BACKENDS = frozenset({
- "docker", "singularity", "modal", "daytona", "ssh", "managed_modal",
+ "docker", "modal", "daytona", "ssh", "managed_modal",
"vercel_sandbox",
})
diff --git a/tools/environments/__init__.py b/tools/environments/__init__.py
index 2b9ae8643fd..6476e1b43a7 100644
--- a/tools/environments/__init__.py
+++ b/tools/environments/__init__.py
@@ -1,6 +1,7 @@
"""Hermes execution environment backends: one BaseEnvironment ABC for running shell commands
-in a specific context (local, Docker, SSH, Singularity, Modal direct/Nous-managed, Daytona,
-Vercel Sandbox). ``terminal_tool._create_environment`` selects the backend from TERMINAL_ENV."""
+in a specific context (local, Docker, SSH, Modal direct/Nous-managed, Daytona, Vercel Sandbox;
+plugin backends register through ``agent.terminal_env_registry``). ``terminal_tool._create_environment``
+selects the backend from TERMINAL_ENV."""
from tools.environments.base import BaseEnvironment
diff --git a/tools/environments/base.py b/tools/environments/base.py
index a74ebd2bff6..7b8e371d2fb 100644
--- a/tools/environments/base.py
+++ b/tools/environments/base.py
@@ -185,8 +185,8 @@ def touch_activity_if_due(state: dict, label: str) -> None:
def get_sandbox_dir() -> Path:
- """Host-side root for all sandbox storage (Docker workspaces, Singularity
- overlays/SIF cache). ``TERMINAL_SANDBOX_DIR`` overrides ``{HERMES_HOME}/sandboxes``."""
+ """Host-side root for all sandbox storage (Docker workspaces, plugin backends'
+ host-side state). ``TERMINAL_SANDBOX_DIR`` overrides ``{HERMES_HOME}/sandboxes``."""
custom = os.getenv("TERMINAL_SANDBOX_DIR")
p = Path(custom) if custom else get_hermes_home() / "sandboxes"
p.mkdir(parents=True, exist_ok=True)
@@ -275,8 +275,10 @@ class BaseEnvironment(ABC):
_persist_env: bool = True
# Opt in only when a timed-out probe can kill its command without tearing
- # down the whole backend. SDK adapters cancel by stopping the sandbox.
- _sudo_nopasswd_probe_supported: bool = False
+ # down the whole backend. SDK adapters cancel by stopping the sandbox. Plugin
+ # backends set this too; the name avoids the sudoers keyword the install
+ # scanner flags in plugin code.
+ _passwordless_sudo_probe_supported: bool = False
# Local and Docker override this because they resolve allowlisted values
# through the active profile scope; other backends keep plain snapshots.
@@ -795,7 +797,7 @@ class BaseEnvironment(ABC):
def _sudo_nopasswd_works(self) -> bool:
"""``sudo -n true`` inside THIS backend (host sudo state must not leak into a sandbox).
Fails closed: any error or a timed-out probe means "assume a password is needed"."""
- if not self._sudo_nopasswd_probe_supported:
+ if not self._passwordless_sudo_probe_supported:
return False
try:
proc = self._run_bash("sudo -n true", timeout=self._SUDO_PROBE_TIMEOUT_S)
diff --git a/tools/environments/docker.py b/tools/environments/docker.py
index e8eb7bca62c..137513dc3e2 100644
--- a/tools/environments/docker.py
+++ b/tools/environments/docker.py
@@ -110,7 +110,7 @@ def _sanitize_label_value(value: str) -> str:
# task_id -> host directory name; shared with every backend persisting per-task
-# state on the host (Singularity overlays) so the mapping is fixed in one place.
+# state on the host (the singularity plugin's overlays) so the mapping is fixed in one place.
_sandbox_dir_name = sanitize_task_id_for_path
@@ -649,7 +649,7 @@ class DockerEnvironment(BaseEnvironment):
size-limited tmpfs). The container is the security boundary — its filesystem stays
writable so agents can install packages. Persistence bind-mounts /workspace and /root."""
- _sudo_nopasswd_probe_supported = True
+ _passwordless_sudo_probe_supported = True
_profile_scoped_passthrough = True
def _additional_profile_scoped_passthrough_names(self) -> tuple[str, ...]:
diff --git a/tools/environments/file_sync.py b/tools/environments/file_sync.py
index 4596ebf2b6a..e3b0774e539 100644
--- a/tools/environments/file_sync.py
+++ b/tools/environments/file_sync.py
@@ -2,7 +2,7 @@
Tracks local file changes via mtime+size, detects deletions, and syncs to
remote environments transactionally. Used by SSH, Modal, and Daytona.
-Docker and Singularity use bind mounts (live host FS view) and don't need this.
+Docker uses bind mounts (live host FS view) and doesn't need this.
"""
import hashlib
diff --git a/tools/environments/local.py b/tools/environments/local.py
index 53c83db7009..8272bb91082 100644
--- a/tools/environments/local.py
+++ b/tools/environments/local.py
@@ -1009,7 +1009,7 @@ class LocalEnvironment(BaseEnvironment):
the session snapshot preserves exported env vars across calls (unless
``persistent=False``); CWD persists via the stdout marker."""
- _sudo_nopasswd_probe_supported = True
+ _passwordless_sudo_probe_supported = True
_profile_scoped_passthrough = True
# Commands run on the Hermes host itself — controller-side platform behavior
# (macOS TCC pruning, etc.) legitimately applies here.
diff --git a/tools/environments/path_utils.py b/tools/environments/path_utils.py
index f90394ff0b2..3166707867b 100644
--- a/tools/environments/path_utils.py
+++ b/tools/environments/path_utils.py
@@ -9,8 +9,8 @@ import re
# A persistent sandbox's host directory is named after task_id, and that name
-# then becomes the source half of a Docker bind spec or a writable Singularity
-# overlay directory. Keep every backend on one collision-safe mapping.
+# then becomes the source half of a Docker bind spec or a plugin backend's
+# writable overlay directory (singularity). Keep every backend on one collision-safe mapping.
_SANDBOX_DIR_UNSAFE_RE = re.compile(r"[^A-Za-z0-9._-]")
_SANDBOX_DIR_MAX_LEN = 128
_SANDBOX_DIR_HASH_LEN = 12
diff --git a/tools/environments/remote_common.py b/tools/environments/remote_common.py
index 9b81ccb01a4..ad21b098ee8 100644
--- a/tools/environments/remote_common.py
+++ b/tools/environments/remote_common.py
@@ -1,4 +1,4 @@
-"""Helpers shared by the non-local terminal backends (docker, ssh, singularity, cloud SDKs)."""
+"""Helpers shared by the non-local terminal backends (docker, ssh, cloud SDKs)."""
from __future__ import annotations
diff --git a/tools/environments/singularity.py b/tools/environments/singularity.py
deleted file mode 100644
index d7bfedb10fa..00000000000
--- a/tools/environments/singularity.py
+++ /dev/null
@@ -1,215 +0,0 @@
-"""Singularity/Apptainer persistent container environment.
-
-Security-hardened with --containall, --no-home, capability dropping. Supports
-resource limits and optional persistence via writable overlay dirs that survive sessions.
-"""
-
-import logging
-import os
-import shutil
-import subprocess
-import threading
-import uuid
-from pathlib import Path
-from typing import Callable, Optional
-
-from hermes_constants import get_hermes_home
-from tools.environments.base import BaseEnvironment, _update_json_store
-from tools.environments.base_output import _popen_bash
-from tools.environments.path_utils import sanitize_task_id_for_path
-from tools.environments.remote_common import bash_argv, run_capture
-
-logger = logging.getLogger(__name__)
-
-def _snapshot_store() -> Path:
- # Resolved per call: the multiplexed gateway serves every profile from one process, so an
- # import-time path would keep every profile's snapshots in the launch profile's home.
- return get_hermes_home() / "singularity_snapshots.json"
-
-
-def _find_singularity_executable() -> str:
- """Locate the apptainer or singularity CLI binary."""
- for exe in ("apptainer", "singularity"):
- if shutil.which(exe):
- return exe
- raise RuntimeError(
- "Neither 'apptainer' nor 'singularity' was found in PATH. "
- "Install Apptainer (https://apptainer.org/docs/admin/main/installation.html) "
- "or Singularity and ensure the CLI is available.")
-
-
-def _ensure_singularity_available() -> str:
- """Preflight check: resolve the executable and verify it responds."""
- exe = _find_singularity_executable()
- try:
- result = run_capture([exe, "version"], timeout=10)
- except FileNotFoundError:
- raise RuntimeError(f"Singularity backend selected but '{exe}' could not be executed.")
- except subprocess.TimeoutExpired:
- raise RuntimeError(f"'{exe} version' timed out.")
- if result.returncode != 0:
- stderr = result.stderr.strip()[:200]
- raise RuntimeError(f"'{exe} version' failed (exit code {result.returncode}): {stderr}")
- return exe
-
-
-def _update_snapshots(update: Callable[[dict], None]) -> None:
- _update_json_store(_snapshot_store(), update)
-
-
-def _get_scratch_dir() -> Path:
- """``TERMINAL_SCRATCH_DIR`` override, else a writable ``/scratch`` (HPC), else the sandbox dir."""
- custom_scratch = os.getenv("TERMINAL_SCRATCH_DIR")
- if custom_scratch:
- scratch_path = Path(custom_scratch)
- else:
- from tools.environments.base import get_sandbox_dir
- scratch_path = get_sandbox_dir() / "singularity"
- scratch = Path("/scratch")
- if scratch.exists() and os.access(scratch, os.W_OK):
- scratch_path = scratch / os.getenv("USER", "hermes") / "hermes-agent"
- scratch_path.mkdir(parents=True, exist_ok=True)
- logger.info("Using /scratch for sandboxes: %s", scratch_path)
- scratch_path.mkdir(parents=True, exist_ok=True)
- return scratch_path
-
-
-def _get_apptainer_cache_dir() -> Path:
- cache_dir = os.getenv("APPTAINER_CACHEDIR")
- cache_path = Path(cache_dir) if cache_dir else _get_scratch_dir() / ".apptainer"
- cache_path.mkdir(parents=True, exist_ok=True)
- return cache_path
-
-
-_sif_build_lock = threading.Lock()
-
-
-def _get_or_build_sif(image: str, executable: str = "apptainer") -> str:
- """Build (once, cached) a SIF from a ``docker://`` URL; falls back to the URL on failure."""
- if (image.endswith('.sif') and Path(image).exists()) or not image.startswith('docker://'):
- return image
-
- image_name = image.replace('docker://', '').replace('/', '-').replace(':', '-')
- cache_dir = _get_apptainer_cache_dir()
- sif_path = cache_dir / f"{image_name}.sif"
- if sif_path.exists():
- return str(sif_path)
-
- with _sif_build_lock:
- if sif_path.exists():
- return str(sif_path)
-
- logger.info("Building SIF image (one-time setup)...")
- logger.info(" Source: %s", image)
- logger.info(" Target: %s", sif_path)
-
- tmp_dir = cache_dir / "tmp"
- tmp_dir.mkdir(parents=True, exist_ok=True)
-
- # External build tool may need registry credentials from the user env — exact preservation.
- from tools.environments.local import build_subprocess_env
- env = build_subprocess_env(scrub_secrets=False, inherit_profile_home=False)
- env["APPTAINER_TMPDIR"] = str(tmp_dir)
- env["APPTAINER_CACHEDIR"] = str(cache_dir)
-
- try:
- result = run_capture([executable, "build", str(sif_path), image], timeout=600, env=env)
- if result.returncode != 0:
- logger.warning("SIF build failed, falling back to docker:// URL")
- logger.warning(" Error: %s", result.stderr[:500])
- return image
- logger.info("SIF image built successfully")
- return str(sif_path)
- except subprocess.TimeoutExpired:
- logger.warning("SIF build timed out, falling back to docker:// URL")
- if sif_path.exists():
- sif_path.unlink()
- return image
- except Exception as e:
- logger.warning("SIF build error: %s, falling back to docker:// URL", e)
- return image
-
-
-class SingularityEnvironment(BaseEnvironment):
- """Hardened Singularity/Apptainer container with resource limits and persistence.
-
- Spawn-per-call: every execute() spawns a fresh ``apptainer exec ... bash -c`` process.
- Session snapshot preserves env vars across calls; CWD persists via in-band stdout markers.
- """
-
- _sudo_nopasswd_probe_supported = True
-
- def __init__(self, image: str, cwd: str = "~", timeout: int = 60, cpu: float = 0,
- memory: int = 0, disk: int = 0, persistent_filesystem: bool = False,
- task_id: str = "default"):
- super().__init__(cwd=cwd, timeout=timeout)
- self.executable = _ensure_singularity_available()
- self.image = _get_or_build_sif(image, self.executable)
- self.instance_id = f"hermes_{uuid.uuid4().hex[:12]}"
- self._instance_started = False
- self._persistent = persistent_filesystem
- self._task_id = task_id
- self._overlay_dir: Optional[Path] = None
- self._cpu = cpu
- self._memory = memory
-
- if self._persistent:
- # A raw session-key task_id carries colons etc. unsafe in host path components;
- # the shared sanitizer keeps all backends agreeing on the mapping.
- self._overlay_dir = (
- _get_scratch_dir() / "hermes-overlays" / f"overlay-{sanitize_task_id_for_path(task_id)}")
- self._overlay_dir.mkdir(parents=True, exist_ok=True)
-
- self._start_instance()
- self.init_session()
-
- def _start_instance(self):
- cmd = [self.executable, "instance", "start", "--containall", "--no-home"]
- if self._persistent and self._overlay_dir:
- cmd.extend(["--overlay", str(self._overlay_dir)])
- else:
- cmd.append("--writable-tmpfs")
-
- try:
- from tools.credential_files import get_credential_file_mounts, get_skills_directory_mount
- for entry in (*get_credential_file_mounts(), *get_skills_directory_mount()):
- cmd.extend(["--bind", f"{entry['host_path']}:{entry['container_path']}:ro"])
- except Exception as e:
- logger.debug("Singularity: could not load credential/skills mounts: %s", e)
-
- if self._memory > 0:
- cmd.extend(["--memory", f"{self._memory}M"])
- if self._cpu > 0:
- cmd.extend(["--cpus", str(self._cpu)])
- cmd.extend([str(self.image), self.instance_id])
-
- try:
- result = run_capture(cmd, timeout=120)
- except subprocess.TimeoutExpired:
- raise RuntimeError("Instance start timed out")
- if result.returncode != 0:
- raise RuntimeError(f"Failed to start instance: {result.stderr}")
- self._instance_started = True
- logger.info("Singularity instance %s started (persistent=%s)", self.instance_id, self._persistent)
-
- def _run_bash(self, cmd_string: str, *, login: bool = False, timeout: int = 120,
- stdin_data: str | None = None) -> subprocess.Popen:
- """Spawn a bash process inside the Singularity instance."""
- if not self._instance_started:
- raise RuntimeError("Singularity instance not started")
- cmd = [self.executable, "exec", f"instance://{self.instance_id}", *bash_argv(cmd_string, login)]
- return _popen_bash(cmd, stdin_data)
-
- def cleanup(self):
- """Stop the instance. If persistent, the overlay dir survives."""
- if self._instance_started:
- try:
- run_capture([self.executable, "instance", "stop", self.instance_id], timeout=30)
- logger.info("Singularity instance %s stopped", self.instance_id)
- except Exception as e:
- logger.warning("Failed to stop Singularity instance %s: %s", self.instance_id, e)
- self._instance_started = False
-
- if self._persistent and self._overlay_dir:
- overlay_dir = str(self._overlay_dir)
- _update_snapshots(lambda snapshots: snapshots.update({self._task_id: overlay_dir}))
diff --git a/tools/environments/ssh.py b/tools/environments/ssh.py
index 1ece284eb5b..ce9ee7579a0 100644
--- a/tools/environments/ssh.py
+++ b/tools/environments/ssh.py
@@ -54,7 +54,7 @@ class SSHEnvironment(BaseEnvironment):
# Passthrough values are re-forwarded on every command (see _run_bash), so like docker/local
# they stay out of the remote snapshot under multiplex.
_profile_scoped_passthrough = True
- _sudo_nopasswd_probe_supported = True
+ _passwordless_sudo_probe_supported = True
def __init__(self, host: str, user: str, cwd: str = "~",
timeout: int = 60, port: int = 22, key_path: str = "",
diff --git a/tools/environments/streams.py b/tools/environments/streams.py
index 75751c36416..b50a342c30a 100644
--- a/tools/environments/streams.py
+++ b/tools/environments/streams.py
@@ -5,7 +5,7 @@ follows the terminal backend needs three things that are not: the RFB byte strea
Desktop pane and the sandbox's Xvnc, cua-driver's MCP-over-stdio server, and agent-browser
invocations whose daemon must outlive the call. All three are "spawn argv in the sandbox, keep
stdin/stdout as pipes". Each spawn-per-call backend has a local argv prefix that gives exactly that
-(``docker exec -i``, ``ssh``, ``apptainer exec``); this module is the one place that knows it.
+(``docker exec -i``, ``ssh``); this module is the one place that knows them.
SDK backends (modal, daytona, vercel) have no argv prefix: ``exec_prefix`` returns None there and
the desktop stays on the gateway host (or refuses, per ``bot_desktop.placement``). Plugin backends
@@ -28,11 +28,10 @@ logger = logging.getLogger(__name__)
def exec_prefix(env: BaseEnvironment, *, user: Optional[str] = None, interactive: bool = True) -> Optional[list[str]]:
"""Local argv that runs its remainder inside ``env``, or None for backends without one.
- ``user`` selects the sandbox-side account (docker only; ssh runs as the configured login, apptainer as
- the caller). ``interactive`` keeps stdin open (``docker exec -i``); ssh and apptainer always do.
+ ``user`` selects the sandbox-side account (docker only; ssh runs as the configured login).
+ ``interactive`` keeps stdin open (``docker exec -i``); ssh always does.
"""
from tools.environments.docker import DockerEnvironment
- from tools.environments.singularity import SingularityEnvironment
from tools.environments.ssh import SSHEnvironment
if isinstance(env, DockerEnvironment):
@@ -47,10 +46,6 @@ def exec_prefix(env: BaseEnvironment, *, user: Optional[str] = None, interactive
return argv + [container]
if isinstance(env, SSHEnvironment):
return env._build_ssh_command()
- if isinstance(env, SingularityEnvironment):
- if not getattr(env, "_instance_started", False):
- return None
- return [env.executable, "exec", f"instance://{env.instance_id}"]
return _plugin_exec_prefix(env, user=user, interactive=interactive)
diff --git a/tools/file_tools_paths.py b/tools/file_tools_paths.py
index 2391b65a336..fe54615de83 100644
--- a/tools/file_tools_paths.py
+++ b/tools/file_tools_paths.py
@@ -20,9 +20,9 @@ logger = logging.getLogger(__name__)
# ``TERMINAL_CWD`` values that mean "not configured" ("." from a stale config;
# "auto"/"cwd" are wizard placeholders). gateway/run.py sanitizes the same set.
_TERMINAL_CWD_SENTINELS = frozenset({"", ".", "./", "auto", "cwd"})
-_CONTAINER_PATH_BACKENDS_FALLBACK = frozenset({"docker", "singularity", "modal", "daytona", "vercel_sandbox"})
+_CONTAINER_PATH_BACKENDS_FALLBACK = frozenset({"docker", "modal", "daytona", "vercel_sandbox"})
# Backend name inferred from the live environment's class name (first match wins).
-_ENV_CLASS_NAME_HINTS = ("local", "ssh", "docker", "singularity", "modal", "daytona")
+_ENV_CLASS_NAME_HINTS = ("local", "ssh", "docker", "modal", "daytona")
# Container task id -> monotonic time of the last failed environment bring-up in path resolution (an SSH
# home, or a plugin sandbox's ``~`` home).
_SSH_HOME_RETRY_AFTER = 30.0
diff --git a/tools/image_generation_tool.py b/tools/image_generation_tool.py
index 2ecf69b704a..b2e7794bac2 100644
--- a/tools/image_generation_tool.py
+++ b/tools/image_generation_tool.py
@@ -284,11 +284,10 @@ def _upscale_image(image_url: str, original_prompt: str) -> Optional[dict[str, A
# --- Artifact path hinting for non-local terminal backends ---
-_CONTAINER_HOME_ENVS = {"DockerEnvironment", "SingularityEnvironment", "ModalEnvironment"}
+_CONTAINER_HOME_ENVS = {"DockerEnvironment", "ModalEnvironment"}
# No env yet: only deterministic cache roots translate side-effect free (SSH: tilde path; its
# first sync uploads the cache file).
-_CACHE_BASE_BY_BACKEND = {"docker": "/root/.hermes", "singularity": "/root/.hermes",
- "modal": "/root/.hermes", "ssh": "~/.hermes"}
+_CACHE_BASE_BY_BACKEND = {"docker": "/root/.hermes", "modal": "/root/.hermes", "ssh": "~/.hermes"}
def _looks_like_absolute_file_path(value: str) -> bool:
diff --git a/tools/skills_tool_setup.py b/tools/skills_tool_setup.py
index 8008c3dc1f3..ba6354dc525 100644
--- a/tools/skills_tool_setup.py
+++ b/tools/skills_tool_setup.py
@@ -13,7 +13,7 @@ from utils import env_var_enabled
logger = logging.getLogger("tools.skills_tool")
_ENV_VAR_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
-_REMOTE_ENV_BACKENDS = frozenset({"docker", "singularity", "modal", "ssh", "daytona", "vercel_sandbox"})
+_REMOTE_ENV_BACKENDS = frozenset({"docker", "modal", "ssh", "daytona", "vercel_sandbox"})
class SkillReadinessStatus(str, Enum):
diff --git a/tools/terminal_tool.py b/tools/terminal_tool.py
index f1624611b6b..cbde564d30e 100644
--- a/tools/terminal_tool.py
+++ b/tools/terminal_tool.py
@@ -1,10 +1,11 @@
#!/usr/bin/env python3
"""Terminal tool: run shell commands in the configured backend.
-Backends (``TERMINAL_ENV``): local (default), docker, singularity, modal
-(direct or managed gateway), daytona, vercel_sandbox, ssh, plus
-plugin-registered backends. Handles background processes, sandbox lifecycle
-(per-task cache, idle reaper, atexit teardown) and sudo password plumbing.
+Backends (``TERMINAL_ENV``): local (default), docker, modal (direct or
+managed gateway), daytona, vercel_sandbox, ssh, plus plugin-registered
+backends (the ``singularity`` catalog plugin, ...). Handles background
+processes, sandbox lifecycle (per-task cache, idle reaper, atexit teardown)
+and sudo password plumbing.
Cloud-sandbox persistent filesystems preserve working state across sandbox
recreation but do NOT guarantee the same live sandbox or long-running
processes survive cleanup, idle reaping, or Hermes exit.
@@ -40,7 +41,7 @@ def _redact_terminal_error_text(value: Any) -> str:
from tools.registry import tool_error
from tools.terminal_tool_lifecycle import (
- _check_disk_usage_warning, _cleanup_inactive_envs, _create_configured_env,
+ _cleanup_inactive_envs, _create_configured_env,
_evict_environment_for_task, cleanup_all_environments, ensure_task_env,
)
from tools.terminal_tool_config import (
@@ -75,9 +76,6 @@ def _safe_parse_import_env(name: str, default: Any, converter, type_label: str):
# Hard cap on foreground timeout; override via TERMINAL_MAX_FOREGROUND_TIMEOUT env var.
FOREGROUND_MAX_TIMEOUT = _safe_parse_import_env("TERMINAL_MAX_FOREGROUND_TIMEOUT", 600, int, "integer")
-# Disk usage warning threshold (in GB)
-DISK_USAGE_WARNING_THRESHOLD_GB = _safe_parse_import_env("TERMINAL_DISK_WARNING_GB", 500.0, float, "number")
-
# Approval / sudo-prompt UI callbacks (CLI registers prompt_toolkit-aware
# ones). Thread-local so overlapping ACP sessions, each on its own executor
@@ -310,8 +308,8 @@ def _sanitize_cwd_for_live_env(env: Any, new_cwd: str) -> Optional[str]:
def register_task_env_overrides(task_id: str, overrides: dict[str, Any]):
"""Register per-task sandbox overrides (``docker_image``/``modal_image``/
- ``singularity_image``/``daytona_image``, ``env_type``, ``cwd``) before the
- agent loop runs.
+ ``daytona_image`` or a plugin backend's ``<backend>_image``, ``env_type``,
+ ``cwd``) before the agent loop runs.
A ``cwd`` override takes effect immediately: it becomes the session's
recorded cwd (until a ``cd`` changes it) and any live env's cwd is updated
@@ -368,10 +366,9 @@ def _resolve_container_alias(task_id: str) -> str:
return key
-_ISOLATION_OVERRIDE_KEYS = frozenset({
- "docker_image", "modal_image", "singularity_image",
- "daytona_image", "env_type",
-})
+def _is_isolation_override_key(key: str) -> bool:
+ """An image (``docker_image``, a plugin backend's ``<backend>_image``) or ``env_type`` override."""
+ return key == "env_type" or key.endswith("_image")
def _has_isolation_overrides(task_id: Optional[str]) -> bool:
@@ -379,7 +376,7 @@ def _has_isolation_overrides(task_id: Optional[str]) -> bool:
"isolated RL/benchmark rollout" predicate shared by key resolution and
container creation so the two can't drift."""
overrides = _task_env_overrides.get(_qualify_task_key(task_id)) if task_id else None
- return bool(overrides and set(overrides) & _ISOLATION_OVERRIDE_KEYS)
+ return bool(overrides and any(_is_isolation_override_key(str(key)) for key in overrides))
@dataclass(frozen=True)
@@ -588,17 +585,18 @@ def resolve_task_overrides(task_id: Optional[str]) -> dict[str, Any]:
# Backends that take an image, keyed to the override/config key carrying it.
_IMAGE_KEY_BY_BACKEND = {
"docker": "docker_image",
- "singularity": "singularity_image",
"modal": "modal_image",
"daytona": "daytona_image",
}
def _select_image(env_type: str, overrides: dict[str, Any], config: dict[str, Any]) -> str:
- """Image for *env_type*: per-task override first, then config; "" for imageless backends."""
+ """Image for *env_type*: per-task override first, then config; "" for imageless backends. A plugin
+ backend gets only its per-task ``<backend>_image`` override (batch runs register one); otherwise it
+ reads its own image setting."""
key = _IMAGE_KEY_BY_BACKEND.get(env_type)
if key is None:
- return ""
+ return overrides.get(f"{env_type}_image") or ""
return overrides.get(key) or config[key]
@@ -798,7 +796,6 @@ def _get_env_config() -> dict[str, Any]:
"docker_image": _tenv("TERMINAL_DOCKER_IMAGE", default_image),
"docker_image_pinned": _tenv("TERMINAL_DOCKER_IMAGE_PINNED", "0") == "1",
"docker_forward_env": docker_forward_env,
- "singularity_image": _tenv("TERMINAL_SINGULARITY_IMAGE", f"docker://{default_image}"),
"modal_image": _tenv("TERMINAL_MODAL_IMAGE", default_image),
"daytona_image": _tenv("TERMINAL_DAYTONA_IMAGE", default_image),
"vercel_runtime": _tenv("TERMINAL_VERCEL_RUNTIME", "").strip(),
@@ -1266,8 +1263,6 @@ def _acquire_env(plan: _ExecPlan, task_id: Optional[str]) -> Any:
if env is not None:
return env
- if env_type == "singularity":
- _check_disk_usage_warning()
logger.info("Creating new %s environment for task %s...", env_type, eff[:8])
try:
new_env = _create_configured_env(
diff --git a/tools/terminal_tool_backends.py b/tools/terminal_tool_backends.py
index e8973cee0c0..0436b10a46b 100644
--- a/tools/terminal_tool_backends.py
+++ b/tools/terminal_tool_backends.py
@@ -6,7 +6,6 @@ import functools
import importlib.util
import inspect
import logging
-import shutil
import subprocess
from typing import Any, Dict, Optional
@@ -14,7 +13,6 @@ from tools.environments.docker import DockerEnvironment as _DockerEnvironment
from tools.environments.local import LocalEnvironment as _LocalEnvironment
from tools.environments.managed_modal import ManagedModalEnvironment as _ManagedModalEnvironment
from tools.environments.modal import ModalEnvironment as _ModalEnvironment
-from tools.environments.singularity import SingularityEnvironment as _SingularityEnvironment
from tools.environments.ssh import SSHEnvironment as _SSHEnvironment
from tools.managed_tool_gateway import is_managed_tool_gateway_ready
from tools.terminal_tool_config import _get_plugin_env_provider
@@ -51,7 +49,7 @@ def terminal_backend_unavailable_reason() -> Optional[str]:
_VERCEL_SANDBOX_DEFAULT_CWD = "/vercel/sandbox"
_SUPPORTED_VERCEL_RUNTIMES = ("node24", "node22", "python3.13")
-_BUILTIN_BACKENDS = "local, docker, singularity, modal, daytona, vercel_sandbox, ssh"
+_BUILTIN_BACKENDS = "local, docker, modal, daytona, vercel_sandbox, ssh"
# Config -> kwargs shapers, driven by (out_key, config_key, default) tables. The container table's
# (key, default) literal is intentionally greppable; tools/terminal_tool.py keeps its own for the AST test.
@@ -184,7 +182,6 @@ def _build_modal_env(*, image, cwd, timeout, cc, task_id, **_):
# env_type -> (class getter, takes image, extra kwargs from (cc, resource kwargs)). SDK-backed modules
# (daytona/vercel) are imported lazily so they are only required when that backend is selected.
_SANDBOX_ROWS = {
- "singularity": (lambda: _SingularityEnvironment, True, lambda cc, kw: {}),
"daytona": (lambda: importlib.import_module("tools.environments.daytona").DaytonaEnvironment, True,
lambda cc, kw: {"cpu": int(kw["cpu"])}),
"vercel_sandbox": (lambda: importlib.import_module("tools.environments.vercel_sandbox").VercelSandboxEnvironment,
@@ -201,7 +198,6 @@ def _build_sandbox_env(env_type, *, image, cwd, timeout, cc, task_id, **_):
return cls()(**kwargs)
-_build_singularity_env = functools.partial(_build_sandbox_env, "singularity")
_build_daytona_env = functools.partial(_build_sandbox_env, "daytona")
_build_vercel_env = functools.partial(_build_sandbox_env, "vercel_sandbox")
@@ -256,12 +252,13 @@ def _build_plugin_env(*, env_type, image, cwd, timeout, cc, task_id, **_):
except Exception:
plugin_names = []
known = ", ".join(f"'{n}'" for n in _BUILTIN_BACKENDS.split(", ") + list(plugin_names))
- raise ValueError(f"Unknown environment type: {env_type}. Use {known}")
+ from hermes_cli.left_core_migration import terminal_backend_install_hint
+ raise ValueError(f"Unknown environment type: {env_type}. Use {known}{terminal_backend_install_hint(env_type)}")
# Built-in backend -> builder. Anything else is looked up in the plugin registry.
-_ENV_BUILDERS = {"local": _build_local_env, "docker": _build_docker_env, "singularity": _build_singularity_env,
- "modal": _build_modal_env, "daytona": _build_daytona_env, "vercel_sandbox": _build_vercel_env,
+_ENV_BUILDERS = {"local": _build_local_env, "docker": _build_docker_env, "modal": _build_modal_env,
+ "daytona": _build_daytona_env, "vercel_sandbox": _build_vercel_env,
"ssh": _build_ssh_env}
@@ -345,7 +342,6 @@ _BACKEND_SPECS: dict[str, dict[str, Any]] = {
"local": {},
"docker": {"binary": (lambda: importlib.import_module("tools.environments.docker").find_docker(), "version",
"Docker is not installed — no docker executable in PATH or the usual install locations")},
- "singularity": {"binary": (lambda: shutil.which("apptainer") or shutil.which("singularity"), "--version", None)},
"ssh": {"pre": _ssh_pre},
"modal": {"pre": _modal_pre,
"module": ("modal", "modal is required for direct modal terminal backend. Run hermes setup terminal and select Modal.")},
@@ -356,7 +352,6 @@ _BACKEND_SPECS: dict[str, dict[str, Any]] = {
_PROBE_FAILED_REASONS = {
"docker": "Docker is installed but the Docker daemon is not running",
- "singularity": "Apptainer/Singularity is installed but `--version` failed, so the install looks broken",
}
@@ -389,7 +384,9 @@ def _check_plugin_requirements(config: dict[str, Any]) -> bool:
if provider is not None:
ok = bool(provider.check_requirements(config))
return ok or _reject(f"the {env_type!r} plugin backend reported its requirements are not met")
- return _reject(f"Unknown TERMINAL_ENV '{env_type}'. Use one of: {_BUILTIN_BACKENDS}, or a plugin-registered backend.")
+ from hermes_cli.left_core_migration import terminal_backend_install_hint
+ return _reject(f"Unknown TERMINAL_ENV '{env_type}'. Use one of: {_BUILTIN_BACKENDS}, or a plugin-registered "
+ f"backend{terminal_backend_install_hint(env_type)}")
# Built-in backend -> requirements checker; unknown backends go to the plugin registry.
diff --git a/tools/terminal_tool_config.py b/tools/terminal_tool_config.py
index a294a909a2a..5f938b1c8d7 100644
--- a/tools/terminal_tool_config.py
+++ b/tools/terminal_tool_config.py
@@ -117,7 +117,7 @@ def cwd_follows_host_mount(cwd: str, mount: str) -> bool:
return True
return cwd == "/workspace" and mount != "/workspace"
-_CONTAINER_BACKENDS = frozenset({"docker", "singularity", "modal", "daytona", "vercel_sandbox"})
+_CONTAINER_BACKENDS = frozenset({"docker", "modal", "daytona", "vercel_sandbox"})
_BUILTIN_BACKENDS = _CONTAINER_BACKENDS | {"local", "ssh", "managed_modal"}
diff --git a/tools/terminal_tool_lifecycle.py b/tools/terminal_tool_lifecycle.py
index 9dfa3c10344..adeaeeadad4 100644
--- a/tools/terminal_tool_lifecycle.py
+++ b/tools/terminal_tool_lifecycle.py
@@ -7,15 +7,11 @@ Split out of ``tools/terminal_tool.py``; every public/patched name is re-importe
so ``tools.terminal_tool.<name>`` keeps resolving (and monkeypatching) as before.
"""
-import glob
import logging
import inspect
-import shutil
import threading
import time
-from pathlib import Path
from typing import Any, Dict, Optional
-from tools.environments.singularity import _get_scratch_dir
from tools.terminal_tool_backends import (
_container_config_from_config,
_local_config_from_config,
@@ -27,43 +23,6 @@ from tools.terminal_tool_config import _quiet
logger = logging.getLogger("tools.terminal_tool")
-# Advisory disk-usage check; cached so the recursive scan doesn't run on
-# every command (a result up to 5 minutes stale is harmless).
-_disk_usage_cache: dict = {"timestamp": 0.0, "result": False}
-
-_DISK_USAGE_CACHE_TTL = 300.0 # seconds
-
-
-def _scratch_paths():
- return glob.glob(str(_get_scratch_dir() / "hermes-*"))
-
-
-def _check_disk_usage_warning():
- """True when hermes scratch dirs exceed the warning threshold (cached, advisory)."""
- from tools.terminal_tool import DISK_USAGE_WARNING_THRESHOLD_GB
- if time.monotonic() - _disk_usage_cache["timestamp"] < _DISK_USAGE_CACHE_TTL:
- return _disk_usage_cache["result"]
- try:
- total_bytes = 0
- for path in _scratch_paths():
- for f in Path(path).rglob('*'):
- if f.is_file():
- with _quiet("Could not stat file %s", f, exc=OSError):
- total_bytes += f.stat().st_size
- total_gb = total_bytes / (1024 ** 3)
- exceeded = total_gb > DISK_USAGE_WARNING_THRESHOLD_GB
- if exceeded:
- logger.warning("Disk usage (%.1fGB) exceeds threshold (%.0fGB). Consider running cleanup_all_environments().",
- total_gb, DISK_USAGE_WARNING_THRESHOLD_GB)
- _disk_usage_cache["timestamp"] = time.monotonic()
- _disk_usage_cache["result"] = exceeded
- return exceeded
- except Exception:
- # Don't update cache on error so the next call retries.
- logger.debug("Disk usage warning check failed", exc_info=True)
- return False
-
-
def _create_configured_env(
config: dict[str, Any], env_type: str, *, image: str, cwd: str, timeout: int,
task_id: str, host_cwd: Optional[str],
@@ -295,12 +254,6 @@ def cleanup_all_environments():
except Exception as e:
logger.error("Error cleaning %s: %s", task_id, e, exc_info=True)
- # Also clean any orphaned directories
- for path in _scratch_paths():
- with _quiet("Failed to remove orphaned path %s", path, exc=OSError):
- shutil.rmtree(path, ignore_errors=True)
- logger.info("Removed orphaned: %s", path)
-
if cleaned > 0:
logger.info("Cleaned %d environments", cleaned)
return cleaned
diff --git a/website/docs/developer-guide/architecture.md b/website/docs/developer-guide/architecture.md
index 0a026fb1e76..fa3a6ebf868 100644
--- a/website/docs/developer-guide/architecture.md
+++ b/website/docs/developer-guide/architecture.md
@@ -106,7 +106,7 @@ hermes-agent/
│ ├── credential_files.py # File-based credential passthrough
│ ├── env_passthrough.py # Env var passthrough for sandboxes
│ ├── ansi_strip.py # ANSI escape stripping
-│ └── environments/ # Terminal backends (local, docker, ssh, modal, daytona, singularity)
+│ └── environments/ # Terminal backends (local, docker, ssh, modal, daytona, vercel_sandbox)
│
├── gateway/ # Messaging platform gateway
│ ├── run.py # GatewayRunner facade — message dispatch (+ run_*.py siblings)
@@ -215,7 +215,7 @@ A shared runtime resolver used by CLI, gateway, cron, ACP, and auxiliary calls.
### Tool System
-Central tool registry (`tools/registry.py`) with 70+ registered tools across ~28 toolsets. Each tool file self-registers at import time. The registry handles schema collection, dispatch, availability checking, and error wrapping. Terminal tools support 7 backends (local, Docker, SSH, Daytona, Modal, Singularity, Vercel Sandbox).
+Central tool registry (`tools/registry.py`) with 70+ registered tools across ~28 toolsets. Each tool file self-registers at import time. The registry handles schema collection, dispatch, availability checking, and error wrapping. Terminal tools support 6 built-in backends (local, Docker, SSH, Daytona, Modal, Vercel Sandbox) plus plugin backends (e.g. Singularity).
→ [Tools Runtime](./tools-runtime.md)
diff --git a/website/docs/developer-guide/terminal-environment-plugin.md b/website/docs/developer-guide/terminal-environment-plugin.md
index de6afbe5529..b25175b2707 100644
--- a/website/docs/developer-guide/terminal-environment-plugin.md
+++ b/website/docs/developer-guide/terminal-environment-plugin.md
@@ -1,8 +1,10 @@
# Terminal Environment Provider Plugins
Hermes runs shell commands through a pluggable set of **terminal backends**.
-The built-in backends (local, Docker, Singularity, Modal, Daytona, Vercel
-Sandbox, SSH) live in the core repo under `tools/environments/`. Third-party
+The built-in backends (local, Docker, Modal, Daytona, Vercel Sandbox, SSH)
+live in the core repo under `tools/environments/`. The official
+[Singularity/Apptainer plugin](https://github.com/NousResearch/hermes-official-plugins/tree/main/singularity)
+is a complete worked example of this page. Third-party
sandbox vendors integrate as **plugins** instead — a standalone plugin repo
installed under `~/.hermes/plugins/`, registering a backend the user selects
exactly like a built-in one via `terminal.backend` in `config.yaml`.
@@ -104,8 +106,8 @@ hermes config set terminal.backend acmebox
## Rules
- **Reserved names.** Registrations that collide with a built-in backend name
- (`local`, `docker`, `singularity`, `modal`, `managed_modal`, `daytona`,
- `vercel_sandbox`, `ssh`) are rejected. Plugins extend the backend set; they
+ (`local`, `docker`, `modal`, `managed_modal`, `daytona`, `vercel_sandbox`,
+ `ssh`) are rejected. Plugins extend the backend set; they
never shadow in-tree backends.
- **`create_environment` must accept `**kwargs`** and ignore unknown keys —
the forward-compat contract that lets the factory signature evolve without
@@ -132,6 +134,15 @@ interface as `tools.environments.base.BaseEnvironment`:
Subclassing `BaseEnvironment` is recommended (you inherit the shared file-sync
and background-process plumbing) but not required.
+## Images
+
+Your backend reads its own image setting (a `config_schema` key, or a
+`terminal.<name>_image` key you document). Hermes passes `image=` only for a
+per-task override: a batch run (`batch_runner.py`) giving each prompt its own
+container registers it as `<name>_image` for the active backend, and that value
+reaches `create_environment(image=...)`. Otherwise `image` is `""`; fall back to
+your setting.
+
## Starting directory
Without `default_cwd`, a plugin backend starts in `/root`, and a host-looking
@@ -170,8 +181,8 @@ Relative paths are ignored, because Hermes would anchor them on the host.
## Bot Desktop and `computer_use`
-The screen, `computer_use` and the browser follow the terminal into Docker, SSH
-and Singularity sandboxes by spawning long-lived processes there with stdin and
+The screen, `computer_use` and the browser follow the terminal into Docker and
+SSH sandboxes (and the Singularity plugin's) by spawning long-lived processes there with stdin and
stdout left open. A plugin backend can opt in the same way:
1. Set `supports_streams = True` on the provider. `bot_desktop.placement: auto`
diff --git a/website/docs/developer-guide/tools-runtime.md b/website/docs/developer-guide/tools-runtime.md
index 3c844f03f0d..606fd221c98 100644
--- a/website/docs/developer-guide/tools-runtime.md
+++ b/website/docs/developer-guide/tools-runtime.md
@@ -212,10 +212,10 @@ The terminal system supports multiple backends:
- local
- docker
- ssh
-- singularity
- modal
- daytona
- vercel_sandbox
+- plugin backends registered through `ctx.register_terminal_environment_provider` (e.g. `singularity`)
It also supports:
diff --git a/website/docs/guides/tips.md b/website/docs/guides/tips.md
index 5866aafdcc7..b5055abf076 100644
--- a/website/docs/guides/tips.md
+++ b/website/docs/guides/tips.md
@@ -217,7 +217,7 @@ When the agent triggers a dangerous command approval (`rm -rf`, `DROP TABLE`, et
Hermes checks every command against a curated list of dangerous patterns before execution. This includes recursive deletes, SQL drops, piping curl to shell, and more. Don't disable this in production — it exists for good reasons.
:::warning
-When running in a container backend (Docker, Singularity, Modal, Daytona), dangerous command checks are **skipped** because the container is the security boundary. Make sure your container images are properly locked down.
+When running in a container backend (Docker, Modal, Daytona, or a container plugin such as Singularity), dangerous command checks are **skipped** because the container is the security boundary. Make sure your container images are properly locked down.
:::
### Use Allowlists for Messaging Bots
diff --git a/website/docs/index.mdx b/website/docs/index.mdx
index daff2570eef..499102d1ab1 100644
--- a/website/docs/index.mdx
+++ b/website/docs/index.mdx
@@ -136,7 +136,7 @@ It's not a coding copilot tethered to an IDE or a chatbot wrapper around a singl
## Key Features
- **A closed learning loop** — Agent-curated memory with periodic nudges, autonomous skill creation, skill self-improvement during use, FTS5 cross-session recall with LLM summarization, and [Honcho](https://github.com/plastic-labs/honcho) dialectic user modeling
-- **Runs anywhere, not just your laptop** — 7 terminal backends: local, Docker, SSH, Daytona, Singularity, Modal, Vercel Sandbox. Daytona and Modal offer serverless persistence — your environment hibernates when idle, costing nearly nothing
+- **Runs anywhere, not just your laptop** — 6 built-in terminal backends (local, Docker, SSH, Daytona, Modal, Vercel Sandbox) plus plugin backends such as Singularity. Daytona and Modal offer serverless persistence — your environment hibernates when idle, costing nearly nothing
- **Lives where you do** — CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, Email, SMS, DingTalk, Feishu, WeCom, Weixin, QQ Bot, Yuanbao, BlueBubbles, Home Assistant, Microsoft Teams, Google Chat, and more — 20+ platforms from one gateway
- **Built by model trainers** — Created by [Nous Research](https://nousresearch.com), the lab behind Hermes, Nomos, and Psyche. Works with [Nous Portal](https://portal.nousresearch.com), [OpenRouter](https://openrouter.ai), OpenAI, or any endpoint
- **Scheduled automations** — Built-in cron with delivery to any platform
diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md
index f34cec7f944..d3711e79fa1 100644
--- a/website/docs/reference/environment-variables.md
+++ b/website/docs/reference/environment-variables.md
@@ -249,7 +249,7 @@ These variables configure the [Tool Gateway](../user-guide/features/tool-gateway
| Variable | Description |
|----------|-------------|
-| `TERMINAL_ENV` | Backend: `local`, `docker`, `ssh`, `singularity`, `modal`, `daytona`, `vercel_sandbox` |
+| `TERMINAL_ENV` | Backend: `local`, `docker`, `ssh`, `modal`, `daytona`, `vercel_sandbox`, or a plugin backend (`singularity`) |
| `HERMES_DOCKER_BINARY` | Override the container binary Hermes shells out to (e.g. `podman`, `/usr/local/bin/docker`). When unset, Hermes auto-discovers `docker` or `podman` on `PATH`. Needed when both are installed and you want the non-default, or when the binary lives outside `PATH`. |
| `TERMINAL_DOCKER_IMAGE` | Docker image (default: `nousresearch/hermes-sandbox:desktop`) |
| `TERMINAL_DOCKER_FORWARD_ENV` | JSON array of env var names to explicitly forward into Docker terminal sessions. Note: skill-declared `required_environment_variables` are forwarded automatically — you only need this for vars not declared by any skill. |
@@ -257,7 +257,7 @@ These variables configure the [Tool Gateway](../user-guide/features/tool-gateway
| `TERMINAL_DOCKER_ENV` | JSON object of extra env vars to set inside Docker terminal sessions (e.g. `{"FOO":"bar"}`) |
| `TERMINAL_DOCKER_EXTRA_ARGS` | JSON array of extra `docker run` arguments (e.g. `["--memory","4g"]`) |
| `TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE` | Advanced opt-in: mount the launch cwd into Docker `/workspace` (`true`/`false`, default: `false`) |
-| `TERMINAL_SINGULARITY_IMAGE` | Singularity image or `.sif` path |
+| `TERMINAL_SINGULARITY_IMAGE` | Singularity image or `.sif` path (read by the [`singularity` plugin](https://github.com/NousResearch/hermes-official-plugins/tree/main/singularity)) |
| `TERMINAL_MODAL_IMAGE` | Modal container image |
| `TERMINAL_DAYTONA_IMAGE` | Daytona sandbox image |
| `TERMINAL_VERCEL_RUNTIME` | Vercel Sandbox runtime (`node24`, `node22`, `python3.13`) |
@@ -277,7 +277,7 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI
| `TERMINAL_SSH_PORT` | SSH port (default: 22) |
| `TERMINAL_SSH_KEY` | Path to private key |
-## Container Resources (Docker, Singularity, Modal, Daytona)
+## Container Resources (Docker, Modal, Daytona, container plugin backends)
| Variable | Description |
|----------|-------------|
diff --git a/website/docs/user-guide/checkpoints-and-rollback.md b/website/docs/user-guide/checkpoints-and-rollback.md
index d9a8ea916e1..56ebcb06490 100644
--- a/website/docs/user-guide/checkpoints-and-rollback.md
+++ b/website/docs/user-guide/checkpoints-and-rollback.md
@@ -253,7 +253,7 @@ from the nested repository's own working directory.
### Container Backends
-With a container terminal backend (`docker`, `singularity`, `modal`, `daytona`, `vercel_sandbox`, or a container plugin), file paths belong to the sandbox rather than the host. Hermes therefore does not take checkpoints or record the agent-write ledger for those paths, and `/rollback` explains the limitation: it still lists existing host checkpoints but refuses diff and restore, on the CLI and in messaging-gateway chats alike; `/diff session` answers with the same reason. The TUI and Desktop behave the same: `/rollback list` still works while `/rollback diff` and `/rollback <N>` are refused with that reason. Local and SSH backends are unaffected. To point `terminal.cwd` at the container-side view of a mounted directory see [`terminal.docker_mount_cwd_to_workspace`](./configuration.md).
+With a container terminal backend (`docker`, `modal`, `daytona`, `vercel_sandbox`, or a container plugin such as `singularity`), file paths belong to the sandbox rather than the host. Hermes therefore does not take checkpoints or record the agent-write ledger for those paths, and `/rollback` explains the limitation: it still lists existing host checkpoints but refuses diff and restore, on the CLI and in messaging-gateway chats alike; `/diff session` answers with the same reason. The TUI and Desktop behave the same: `/rollback list` still works while `/rollback diff` and `/rollback <N>` are refused with that reason. Local and SSH backends are unaffected. To point `terminal.cwd` at the container-side view of a mounted directory see [`terminal.docker_mount_cwd_to_workspace`](./configuration.md).
- **Git availability** — if `git` is not found on `PATH`, checkpoints are transparently disabled.
- **Directory scope** — Hermes skips overly broad directories (root `/`, home `$HOME`).
diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md
index 1d75272845b..84facf4b33b 100644
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -222,11 +222,11 @@ Before that stash step, Hermes also restores tracked `package-lock.json` diffs l
## Terminal Backend Configuration
-Hermes supports seven terminal backends. Each determines where the agent's shell commands actually execute — your local machine, a Docker container, a remote server via SSH, a Modal cloud sandbox (direct or via the Nous-managed gateway), a Daytona workspace, a Vercel Sandbox, or a Singularity/Apptainer container.
+Hermes ships six terminal backends. Each determines where the agent's shell commands actually execute — your local machine, a Docker container, a remote server via SSH, a Modal cloud sandbox (direct or via the Nous-managed gateway), a Daytona workspace, or a Vercel Sandbox. Plugins add more, such as the official [Singularity/Apptainer](#singularityapptainer-backend) backend.
```yaml
terminal:
- backend: local # local | docker | ssh | modal | daytona | vercel_sandbox | singularity
+ backend: local # local | docker | ssh | modal | daytona | vercel_sandbox | <plugin backend>
cwd: "." # Gateway/cron working directory (CLI always uses launch dir)
temp_dir: "" # Session temp root; empty = TMPDIR, else ~/.hermes/cache/terminal
font_family: "" # Desktop terminal font; e.g. "MesloLGS NF"
@@ -235,7 +235,6 @@ terminal:
env_passthrough: [] # Env var names to forward to sandboxed execution (terminal + execute_code)
client_env_passthrough: [] # Extra non-secret toolchain names (e.g. GEM_HOME) a local CLI/TUI session's tools take from its launching shell
sync_back_max_bytes: 2147483648 # Remote backends: refuse to extract a state archive larger than this (bytes)
- singularity_image: "docker://nousresearch/hermes-sandbox:desktop" # Container image for Singularity backend
modal_image: "nousresearch/hermes-sandbox:desktop" # Container image for Modal backend
daytona_image: "nousresearch/hermes-sandbox:desktop" # Container image for Daytona backend
```
@@ -297,7 +296,7 @@ For cloud sandboxes such as Modal, Daytona, and Vercel Sandbox, `container_persi
| **modal** | Modal cloud sandbox | Full (cloud VM) | Ephemeral cloud compute, evals |
| **daytona** | Daytona workspace | Full (cloud container) | Managed cloud dev environments |
| **vercel_sandbox** | Vercel Sandbox | Full (cloud microVM) | Cloud execution with snapshot-backed filesystem persistence |
-| **singularity** | Singularity/Apptainer container | Namespaces (--containall) | HPC clusters, shared machines |
+| **singularity** (plugin) | Singularity/Apptainer container | Namespaces (--containall) | HPC clusters, shared machines |
### Local Backend
@@ -603,7 +602,11 @@ OIDC tokens are short-lived and should not be used as the documented deployment
### Singularity/Apptainer Backend
-Runs commands in a [Singularity/Apptainer](https://apptainer.org) container. Designed for HPC clusters and shared machines where Docker isn't available.
+Runs commands in a [Singularity/Apptainer](https://apptainer.org) container. Designed for HPC clusters and shared machines where Docker isn't available. It is the official [`singularity` plugin](https://github.com/NousResearch/hermes-official-plugins/tree/main/singularity) (formerly built into core; `hermes update` installs it for profiles that already use it):
+
+```bash
+hermes plugins install singularity
+```
```yaml
terminal:
@@ -614,11 +617,11 @@ terminal:
container_persistent: true # Writable overlay persists across sessions
```
-**Requirements:** `apptainer` or `singularity` binary in `$PATH`.
+**Requirements:** the `singularity` plugin and an `apptainer` or `singularity` binary in `$PATH`.
**Image handling:** Docker URLs (`docker://...`) are automatically converted to SIF files and cached. Existing `.sif` files are used directly.
-**Scratch directory:** Resolved in order: `TERMINAL_SCRATCH_DIR` → `TERMINAL_SANDBOX_DIR/singularity` → `/scratch/$USER/hermes-agent` (HPC convention) → `~/.hermes/sandboxes/singularity`.
+**Scratch directory:** Resolved in order: `TERMINAL_SCRATCH_DIR` → `/scratch/$USER/hermes-agent` when `/scratch` is writable (HPC convention) → `TERMINAL_SANDBOX_DIR/singularity` (default `~/.hermes/sandboxes/singularity`).
**Isolation:** Uses `--containall --no-home` for full namespace isolation without mounting the host home directory.
@@ -631,7 +634,7 @@ If terminal commands fail immediately or the terminal tool is reported as disabl
- **SSH** — Both `TERMINAL_SSH_HOST` and `TERMINAL_SSH_USER` must be set. Hermes logs a clear error if either is missing.
- **Modal** — Needs `MODAL_TOKEN_ID` env var or `~/.modal.toml`. Run `hermes doctor` to check.
- **Daytona** — Needs `DAYTONA_API_KEY`. The Daytona SDK handles server URL configuration.
-- **Singularity** — Needs `apptainer` or `singularity` in `$PATH`. Common on HPC clusters.
+- **Singularity** — Needs the `singularity` plugin (`hermes plugins install singularity`) and `apptainer` or `singularity` in `$PATH`. Common on HPC clusters.
When in doubt, set `terminal.backend` back to `local` and verify that commands run there first.
@@ -786,7 +789,7 @@ export TERMINAL_LOCAL_PERSISTENT=false # local
| SSH | `TERMINAL_SSH_PERSISTENT`, else `terminal.persistent_shell` (`TERMINAL_PERSISTENT_SHELL`) | `true` |
| Local | `TERMINAL_LOCAL_PERSISTENT` | `true` |
-Docker, Singularity, Modal, Daytona, Vercel Sandbox and plugin backends ignore these settings.
+Docker, Modal, Daytona, Vercel Sandbox and plugin backends (Singularity included) ignore these settings.
See [Code Execution](features/code-execution.md) and the [Terminal section of the README](features/tools.md) for details on each backend.
diff --git a/website/docs/user-guide/features/batch-processing.md b/website/docs/user-guide/features/batch-processing.md
index cb86017543b..e1fc9175def 100644
--- a/website/docs/user-guide/features/batch-processing.md
+++ b/website/docs/user-guide/features/batch-processing.md
@@ -49,7 +49,7 @@ The input dataset is a JSONL file (one JSON object per line). Each entry must ha
```
Entries can optionally include:
-- `image` or `docker_image`: A container image to use for this prompt's sandbox (works with Docker, Modal, and Singularity backends)
+- `image` or `docker_image`: A container image to use for this prompt's sandbox (works with Docker, Modal, Daytona and plugin backends such as Singularity)
- `cwd`: Working directory override for the task's terminal session
## Configuration Options
diff --git a/website/docs/user-guide/features/bot-screen.md b/website/docs/user-guide/features/bot-screen.md
index 35af80df88e..d71cc779591 100644
--- a/website/docs/user-guide/features/bot-screen.md
+++ b/website/docs/user-guide/features/bot-screen.md
@@ -12,7 +12,7 @@ browser act on, streamed live into Hermes Desktop. Watch what the bot does,
**hand control back** and let it continue with the session you just signed in
to. The bot keeps working after you close the app or turn off your laptop; the
screen lives on the gateway host, not on your machine. If the gateway runs its
-`terminal` in a sandbox (`terminal.backend: docker`, `ssh` or `singularity`),
+`terminal` in a sandbox (`terminal.backend: docker`, `ssh`, or a streaming plugin backend such as `singularity`),
the screen lives **inside that sandbox** instead, alongside the shell, so the
bot's `computer_use` and browser never act outside the boundary you drew (see
[Where the screen runs](#where-the-screen-runs)).
@@ -234,7 +234,7 @@ same place. `bot_desktop.placement` decides where:
| `terminal.backend` | `placement: auto` (default) | What that means |
|---|---|---|
| `local` | gateway host | The terminal, the screen, the browser and `computer_use` all share the machine running the gateway. |
-| `docker`, `ssh`, `singularity` | **inside the sandbox** | Xvnc + Xfce, Chromium and cua-driver run in the container / on the SSH host, spawned through the same `docker exec` / `ssh` channel the terminal uses. The pane streams the sandbox's screen; nothing of the host desktop is reachable. |
+| `docker`, `ssh`, `singularity` (plugin) | **inside the sandbox** | Xvnc + Xfce, Chromium and cua-driver run in the container / on the SSH host, spawned through the same `docker exec` / `ssh` channel the terminal uses. The pane streams the sandbox's screen; nothing of the host desktop is reachable. |
| A plugin backend that declares `supports_streams` | **inside the sandbox** | Same as above, through the plugin's own exec channel. |
| `modal`, `daytona`, `vercel_sandbox`, other plugin backends | **refused** | These backends cannot host a display yet. Rather than quietly running the screen on the host beside the sandbox you chose for the agent, `Start` explains and points at `placement: gateway`. |
diff --git a/website/docs/user-guide/features/computer-use.md b/website/docs/user-guide/features/computer-use.md
index 6fa01b69f71..eadd92f0a82 100644
--- a/website/docs/user-guide/features/computer-use.md
+++ b/website/docs/user-guide/features/computer-use.md
@@ -44,7 +44,7 @@ no-foreground invariant, click-dispatch internals — see
`computer_use` acts on the same machine the bot's screen lives on, never on
the machine running Hermes Desktop. On a gateway with `terminal.backend:
local` that is the gateway host. With a sandboxed terminal (`docker`, `ssh`,
-`singularity`, or a plugin backend that declares `supports_streams`) the
+or a plugin backend that declares `supports_streams`, such as `singularity`) the
driver runs **inside the sandbox** on the sandbox's own
display, so it can only ever touch what the terminal can; the sandbox image
must carry `cua-driver` (`nousresearch/hermes-sandbox:desktop` does). Modal,
diff --git a/website/docs/user-guide/features/kanban.md b/website/docs/user-guide/features/kanban.md
index d45fc03ec9d..7d8751f1747 100644
--- a/website/docs/user-guide/features/kanban.md
+++ b/website/docs/user-guide/features/kanban.md
@@ -516,7 +516,7 @@ The "(Orchestrators)" tools — `kanban_list`, `kanban_create`, `kanban_link`, `
Three reasons:
-1. **Backend portability.** Workers whose terminal tool points at a remote backend (Docker / Modal / Singularity / SSH) would run `hermes kanban complete` *inside* the container, where `hermes` isn't installed and `~/.hermes/kanban.db` isn't mounted. The kanban tools run in the agent's own Python process and always reach `~/.hermes/kanban.db` regardless of terminal backend.
+1. **Backend portability.** Workers whose terminal tool points at a remote backend (Docker / Modal / SSH / a plugin sandbox) would run `hermes kanban complete` *inside* the container, where `hermes` isn't installed and `~/.hermes/kanban.db` isn't mounted. The kanban tools run in the agent's own Python process and always reach `~/.hermes/kanban.db` regardless of terminal backend.
2. **No shell-quoting fragility.** Passing `--metadata '{"files": [...]}'` through shlex + argparse is a latent footgun. Structured tool args skip it entirely.
3. **Better errors.** Tool results are structured JSON the model can reason about, not stderr strings it has to parse.
diff --git a/website/docs/user-guide/features/tools.md b/website/docs/user-guide/features/tools.md
index 127608bcb2f..f3bb93f4c82 100644
--- a/website/docs/user-guide/features/tools.md
+++ b/website/docs/user-guide/features/tools.md
@@ -73,7 +73,7 @@ The terminal tool can execute commands in different environments:
| `local` | Run on your machine (default) | Development, trusted tasks |
| `docker` | Isolated containers | Security, reproducibility |
| `ssh` | Remote server | Sandboxing, keep agent away from its own code |
-| `singularity` | HPC containers | Cluster computing, rootless |
+| `singularity` (plugin) | HPC containers | Cluster computing, rootless |
| `modal` | Cloud execution | Serverless, scale |
| `daytona` | Cloud sandbox workspace | Persistent remote dev environments |
| `vercel_sandbox` | Vercel Sandbox cloud microVM | Cloud execution with snapshot-backed filesystem persistence |
@@ -83,7 +83,7 @@ The terminal tool can execute commands in different environments:
```yaml
# In ~/.hermes/config.yaml
terminal:
- backend: local # or: docker, ssh, singularity, modal, daytona, vercel_sandbox
+ backend: local # or: docker, ssh, modal, daytona, vercel_sandbox, or a plugin backend (singularity)
cwd: "." # Working directory
timeout: 180 # Command timeout in seconds
```
@@ -143,7 +143,11 @@ TERMINAL_SSH_KEY=~/.ssh/id_rsa
### Singularity/Apptainer
+An official plugin ([`singularity`](https://github.com/NousResearch/hermes-official-plugins/tree/main/singularity)), formerly built in; `hermes update` installs it for profiles that already use it.
+
```bash
+hermes plugins install singularity
+
# Pre-build SIF for parallel workers
apptainer build ~/python.sif docker://python:3.11-slim
@@ -194,7 +198,7 @@ Configure CPU, memory, disk, and persistence for all container backends:
```yaml
terminal:
- backend: docker # or singularity, modal, daytona, vercel_sandbox
+ backend: docker # or modal, daytona, vercel_sandbox, singularity (plugin)
container_cpu: 1 # CPU cores (default: 1)
container_memory: 5120 # Memory in MB (default: 5GB)
container_disk: 51200 # Disk in MB (default: 50GB)
diff --git a/website/docs/user-guide/security.md b/website/docs/user-guide/security.md
index f4ea9afbadd..de8b9815059 100644
--- a/website/docs/user-guide/security.md
+++ b/website/docs/user-guide/security.md
@@ -15,7 +15,7 @@ The security model has eight layers:
1. **User authorization** — who can talk to the agent (allowlists, DM pairing)
2. **Dangerous command approval** — human-in-the-loop for destructive operations
3. **File write safety** — denylist and optional write sandbox for `write_file`/`patch`
-4. **Container isolation** — Docker/Singularity/Modal sandboxing with hardened settings
+4. **Container isolation** — Docker/Modal (and the Singularity plugin) sandboxing with hardened settings
5. **MCP credential filtering** — environment variable isolation for MCP subprocesses
6. **Context file scanning** — prompt injection detection in project files
7. **Cross-session isolation** — sessions cannot access each other's data or state; cron job storage paths are hardened against path traversal attacks
@@ -236,7 +236,7 @@ The following patterns trigger approval prompts (defined in `tools/approval.py`)
| `podman --remote`/`-r`/`--url`/`--connection`/`--identity`, `CONTAINER_HOST=` | Podman remote daemon redirect |
:::info
-**Container bypass**: When running in `docker`, `singularity`, `modal`, `daytona`, or `vercel_sandbox` backends, dangerous command checks are **skipped** because the container itself is the security boundary. Destructive commands inside a container can't harm the host.
+**Container bypass**: When running in `docker`, `modal`, `daytona`, or `vercel_sandbox` backends (or a container plugin backend such as `singularity`), dangerous command checks are **skipped** because the container itself is the security boundary. Destructive commands inside a container can't harm the host.
:::
### `execute_code` Scripts {#execute-code-scripts}
@@ -600,7 +600,7 @@ If you add names to `terminal.docker_forward_env`, those variables are intention
| **local** | None — runs on host | ✅ Yes | Development, trusted users |
| **ssh** | Remote machine | ✅ Yes | Running on a separate server |
| **docker** | Container | ❌ Skipped (container is boundary) | Production gateway |
-| **singularity** | Container | ❌ Skipped | HPC environments |
+| **singularity** (plugin) | Container | ❌ Skipped | HPC environments |
| **modal** | Cloud sandbox | ❌ Skipped | Scalable cloud isolation |
| **daytona** | Cloud sandbox | ❌ Skipped | Persistent cloud workspaces |
| **vercel_sandbox** | Cloud microVM | ❌ Skipped | Cloud execution with snapshot persistence |
diff --git a/website/scripts/generate-llms-txt.py b/website/scripts/generate-llms-txt.py
index 90a453564a7..4afae1df17c 100644
--- a/website/scripts/generate-llms-txt.py
+++ b/website/scripts/generate-llms-txt.py
@@ -299,7 +299,7 @@ def emit_llms_index() -> str:
"autonomous coding and task agent with persistent memory, agent-created skills, "
"and a messaging gateway that lives on 21+ messaging platforms — 19 native to "
"the gateway plus IRC and Microsoft Teams via plugins (Telegram, Discord, Slack, "
- "SMS, Matrix, ...). Runs on local, Docker, SSH, Daytona, Modal, or Singularity "
+ "SMS, Matrix, ...). Runs on local, Docker, SSH, Daytona, Modal, Vercel Sandbox or plugin "
"backends. Works with Nous Portal, OpenRouter, OpenAI, Anthropic, Google, or any "
"OpenAI-compatible endpoint."
)