🐍 spython — Safe Python

Run Python in a sandboxed container. Your dependencies are isolated, your files are protected.

Why?

Supply chain attacks on PyPI are real (LiteLLM incident, etc.). When you pip install a package, it can access your entire home directory — SSH keys, tokens, cookies, everything.

spython runs your Python code in a Docker container that can only see the current directory. Nothing else.

How it works

Your macOS
  └── Docker Desktop (Linux VM)
       └── Persistent container (your pip packages live here)
            └── python3 your_script.py
                 └── Can ONLY see: the folder you ran it from
                 └── Cannot see: ~/.ssh, ~/.gnupg, ~/.config, etc.

Install

# Clone the repo
git clone https://github.com/yourname/spython.git
cd spython

# Make executable and link to your PATH
chmod +x spython spip
ln -s "$(pwd)/spython" ~/.local/bin/spython
ln -s "$(pwd)/spip" ~/.local/bin/spip

# First time setup (builds the Docker image)
spython --setup

Requires: Docker Desktop running on macOS.

Usage

# Run a script — mounts ONLY the current directory
cd ~/projects/myapp
spython app.py

# Interactive REPL
spython

# Install packages (persists across runs)
spip install requests flask numpy

# Check what's installed
spip list

# Run a module
spython -m pytest

# Check status
spython --status

# Reset everything
spython --destroy

Security model

	Your macOS	spython container
~/.ssh	✅ accessible	❌ not mounted
~/.gnupg	✅ accessible	❌ not mounted
~/.config	✅ accessible	❌ not mounted
Browser cookies	✅ accessible	❌ not mounted
Current directory	✅ accessible	✅ mounted (read/write)
Network	✅ full	❌ disabled by default
Root access	—	❌ non-root user
Linux capabilities	—	❌ all dropped

Configuration

Environment variables in your ~/.zshrc:

# Allow additional directories
export SPYTHON_ALLOWED="$HOME/projects:$HOME/Desktop:$HOME/Documents:/tmp"

# Enable network for scripts that need it
export SPYTHON_NETWORK=1

# Use a different Python version
export SPYTHON_PYTHON=3.11

Directory whitelist

By default, spython only allows running scripts from:

• ~/projects
• ~/Desktop
• ~/Documents
• /tmp

If you try to run from another directory (like ~/.ssh), it refuses:

$ cd ~/.ssh
$ spython evil.py
[spython] Directory not allowed: /Users/you/.ssh

FAQ

Can I use it with Claude Code? Yes! Just use spython instead of python in your commands, or launch Claude Code from within the sandboxed environment.

Are my pip packages persistent? Yes. spip install installs into the persistent container. Packages survive across runs.

Is the network disabled? By default, yes. Scripts can't phone home. Enable with SPYTHON_NETWORK=1 if needed.

What about .pyc files and outputs? The current directory is mounted read/write, so Python can create files there normally.

License

MIT