agentscope-ai/agentscope · error · PermissionError

Bubblewrap file access is limited to {SANDBOX_WORKDIR!r} and

Error message

Bubblewrap file access is limited to {SANDBOX_WORKDIR!r} and {SANDBOX_TMPDIR!r}: {path!r}

What it means

After normalization, sandbox file access is restricted to the two writable roots: SANDBOX_WORKDIR and SANDBOX_TMPDIR. Any normalized path outside those trees raises PermissionError, e.g. '/etc/passwd' or '/var/log/x', even though they exist inside the container.

Source

Thrown at src/agentscope/workspace/_bubblewrap/_bubblewrap_backend.py:600

            if os.path.exists(path):
                args.extend(["--ro-bind", path, path])
        return args

    def _sandbox_path_for(self, path: str) -> str:
        """Validate and normalize a writable sandbox path."""
        sandbox_path = PurePosixPath(path)
        if not sandbox_path.is_absolute():
            raise ValueError(f"Sandbox path must be absolute: {path!r}")

        normalized = posixpath.normpath(path)
        for sandbox_root in (SANDBOX_WORKDIR, SANDBOX_TMPDIR):
            if normalized == sandbox_root:
                return normalized
            prefix = sandbox_root + "/"
            if normalized.startswith(prefix):
                return normalized

        raise PermissionError(
            "Bubblewrap file access is limited to "
            f"{SANDBOX_WORKDIR!r} and {SANDBOX_TMPDIR!r}: {path!r}",
        )

View on GitHub (pinned to e90f1c7592)

Solutions

1. Keep all file I/O under the sandbox workdir (typically /workspace)
2. Copy needed host files into the workspace before the sandbox session
3. Catch PermissionError and re-prompt the agent with the allowed roots

Example fix

# before
await ws.read_file('/etc/hostname')
# after
await ws.run_command('cp /etc/hostname /workspace/hostname.txt')
await ws.read_file('/workspace/hostname.txt')

norm = posixpath.normpath(path)
if not norm.startswith(('/workspace/', '/tmp/')):
    raise ValueError(f'outside allowed sandbox roots: {norm}')

def within_writable_roots(p: str) -> bool:
    n = posixpath.normpath(p)
    return n.startswith(('/workspace/', '/tmp/'))

except PermissionError as e:
    if 'limited to' in str(e): copy file into workspace and retry

When it happens

Trigger: read_file/write_file on any absolute path not under the sandbox workdir or tmpdir prefixes.

Common situations: Assuming the whole container filesystem is writable; using host paths like /home/user/... verbatim; agent models proposing system paths.

Related errors

• path escapes writable Bubblewrap mounts: {path}
• basedir must not be empty.
• BubblewrapWorkspaceManager currently requires share_net=True
• Bubblewrap workdir escapes basedir.
• Unknown permission mode: {mode}

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