PySandboxes documentation

This index is organized around common reader tasks. Start with a working example, understand the security model and its limits, then select a provider and verify the scenarios your application needs.

Get started and configure

• Quick start and use cases — run an application in complete mode and follow links to partial mode.
• Configuration files — locate .py-sandboxes, compose files with include, and configure a module.
• FAQ — answers to common usage and troubleshooting questions.
• Samples — framework integrations and instructions for running the sample projects.
• Integrating with the MCP SDK — configure a sandbox for an MCP server.
• Database — use the database-backed data table.

Understand the security model

• Weaknesses — known limits and residual risks of the Python layer.
• Security assessment of the Python layer — attacks, mechanisms, regression tests, and open paths.
• Security assessment of dynamically evaluated code — the eval-* guard's behavior and limits.
• Dynamically evaluated code — configuration reference for the eval-* rules.
• Transport unpickle guard — validation of objects received from the sandbox child.
• Native guard study — the native-extension approach considered and the decision made.
• Related CVEs — published vulnerabilities in adjacent agent frameworks.

Choose and operate an OS provider

• Provider comparison — enforcement mechanisms, prerequisites, compatibility, and trade-offs.
• Landlock
• Bubblewrap (bwrap)
• Firejail
• Unshare
• QEMU
• DNS and network filtering — DNS resolution and iptables behavior.
• Docker Hub images — pull and run published provider images.

Test and evaluate

• Test coverage map — test suites, provider matrix, skipped scenarios, and approximate counts.
• Learning from tests — use full or partial test runs to discover and review sandbox permissions.
• Alternative sandboxes — comparison with other sandboxes, frameworks, and hosted services.
• Use cases — threat scenarios and suitable isolation levels.

Maintain and explore the project

• Implementation — framework architecture and execution flow.
• Coding-agent skills and plugin — learn and review rules from tests with a human approval gate.
• Roadmap — planned work and project direction.
• Releasing — release and publication process for maintainers.
• Confining Python by observation — research background for the policy-learning approach.