agentscope-ai/agentscope · error · ValueError

BubblewrapWorkspace currently requires share_net=True becaus

Error message

BubblewrapWorkspace currently requires share_net=True because its TCP MCP gateway must be reachable across separate bwrap executions.

What it means

BubblewrapWorkspace runs a TCP MCP gateway that must stay reachable across separate bwrap invocations, which requires a shared network namespace. Constructing with share_net=False is therefore unsupported and rejected in __init__.

Source

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

                Must be ``True`` for this workspace because the TCP MCP
                gateway is reached across separate ``bwrap`` executions.
            env (`dict[str, str] | None`, optional):
                Extra environment variables for sandboxed commands.
            extra_pip (`list[str] | None`, optional):
                Extra Python requirements installed into the gateway venv.
                For a persistent ``host_workdir``, keep this list stable
                across workspace instances; changing it does not currently
                invalidate an existing Bootstrap environment.
            instructions (`str`, optional):
                System-prompt fragment template.
            default_mcps (`list[MCPClient] | None`, optional):
                MCPs seeded on first initialization.
            skill_paths (`list[str] | None`, optional):
                Local skill directories seeded on first initialization.
        """
        self._validate_gateway_port(gateway_port)
        if not share_net:
            raise ValueError(
                "BubblewrapWorkspace currently requires share_net=True "
                "because its TCP MCP gateway must be reachable across "
                "separate bwrap executions.",
            )
        if host_workdir is not None and not host_workdir.strip():
            raise ValueError("host_workdir must not be empty.")
        if host_cache_dir is not None and not host_cache_dir.strip():
            raise ValueError("host_cache_dir must not be empty.")

        super().__init__(
            workspace_id=workspace_id,
            default_mcps=default_mcps,
            skill_paths=skill_paths,
        )

        self.workdir = SANDBOX_WORKDIR
        self.gateway_port = gateway_port
        self._gateway_port_input = gateway_port

View on GitHub (pinned to e90f1c7592)

Solutions

Omit share_net (defaults to True) or set it explicitly to True
If network isolation is mandatory, use a different workspace backend without the TCP MCP gateway

Example fix

# before
ws = BubblewrapWorkspace(share_net=False)
# after
ws = BubblewrapWorkspace(share_net=True)

Defensive patterns

Strategy: validation

Validate before calling

assert share_net is not False, 'BubblewrapWorkspace requires share_net=True'

Type guard

null

Try / catch

except ValueError as e:
    if 'share_net' in str(e): use a non-bubblewrap backend

Prevention

Don't copy sandbox-hardening flags from other backends
Document that the TCP MCP gateway needs shared networking

When it happens

Trigger: BubblewrapWorkspace(share_net=False) — the only trigger; the check runs before any other setup.

Common situations: Copy-pasting config from other sandbox backends that allow network isolation; hardening attempts that disable networking without realizing the gateway needs it.

Related errors

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