agentscope-ai/agentscope · error · RuntimeError

BubblewrapWorkspace requires Linux.

Error message

BubblewrapWorkspace requires Linux.

What it means

Bubblewrap (bwrap) is a Linux-only sandboxing tool, and BubblewrapWorkspace checks sys.platform during backend provisioning. On macOS or Windows the workspace cannot start and raises RuntimeError.

Source

Thrown at src/agentscope/workspace/_bubblewrap/_bubblewrap_workspace.py:193

            return
        if (
            isinstance(gateway_port, bool)
            or not isinstance(gateway_port, int)
            or not 1 <= gateway_port <= 65535
        ):
            raise ValueError(
                "gateway_port must be None or an integer from 1 to 65535.",
            )

    @property
    def is_persistent(self) -> bool:
        """Whether the workspace files survive ``close``."""
        return self._host_workdir_input is not None

    async def _provision_backend(self) -> None:
        """Validate Bubblewrap availability and bind the backend."""
        if not sys.platform.startswith("linux"):
            raise RuntimeError("BubblewrapWorkspace requires Linux.")
        if shutil.which("bwrap") is None:
            raise RuntimeError("BubblewrapWorkspace requires 'bwrap' on PATH.")
        await self._probe_bubblewrap()
        if self._host_workdir_input is None:
            self._owned_workdir = tempfile.TemporaryDirectory()
            self.host_workdir = self._owned_workdir.name
        else:
            self.host_workdir = os.path.abspath(self._host_workdir_input)
        workdir_created = not os.path.lexists(self.host_workdir)
        os.makedirs(self.host_workdir, mode=0o700, exist_ok=True)
        if not os.path.isdir(self.host_workdir):
            raise ValueError("host_workdir must be a directory.")
        if workdir_created:
            os.chmod(self.host_workdir, 0o700)

        if (
            self._host_workdir_input is None
            and self._host_cache_dir_input is None

View on GitHub (pinned to e90f1c7592)

Solutions

1. Select a different Workspace implementation on non-Linux platforms (duck-typed switch on sys.platform)
2. Run the agent inside a Linux container/VM (Docker devcontainer)
3. Skip bubblewrap tests with pytest.mark.skipif(sys.platform != 'linux')

Example fix

# before
ws = BubblewrapWorkspace(...)
# after
import sys
if sys.platform.startswith('linux'):
    ws = BubblewrapWorkspace(...)
else:
    ws = LocalWorkspace(...)

import sys
assert sys.platform.startswith('linux'), 'BubblewrapWorkspace requires Linux'

def bubblewrap_supported() -> bool:
    import sys
    return sys.platform.startswith('linux')

null

When it happens

Trigger: Constructing/starting BubblewrapWorkspace on any non-Linux platform (dev on macOS, CI on windows-latest, etc.).

Common situations: Developing locally on a Mac while targeting Linux servers; cross-platform test suites that instantiate every workspace backend.

Related errors

• basedir must not be empty.
• BubblewrapWorkspaceManager currently requires share_net=True
• Bubblewrap workdir escapes basedir.
• {left_name} must not overlap {right_name}.
• host_cache_dir must be a directory.

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/e9f0764a4402063d. Report an issue: GitHub.