Here is a complete end-to-end tutorial blog on Bubblewrap (bwrap) designed for engineers, DevOps users, and security-focused developers (which fits well with your DevOps/EKS/Terraform background where sandboxing tools like this matter).
Bubblewrap (bwrap) Complete Guide
End-to-End Tutorial for Secure Linux Sandboxing
1. What is Bubblewrap (bwrap)?
Bubblewrap (bwrap) is a lightweight Linux sandboxing tool used to create isolated environments for running applications securely.
It is widely used in:
- Container runtimes
- Sandboxing tools
- Desktop security frameworks
- Flatpak
- Developer tools (including modern AI tools like Codex)
Official concept:
Bubblewrap creates restricted containers using Linux kernel features like:
- Namespaces
- Mount isolation
- User isolation
- Process isolation
Without requiring full Docker or Kubernetes.
Why Bubblewrap Matters Today
Modern developer tools execute:
- Code
- Scripts
- Build steps
- Package installs
Without sandboxing, this is dangerous.
Bubblewrap protects your system from:
- Malicious scripts
- Broken builds
- Unsafe dependencies
- Accidental file deletion
2. How Bubblewrap Works
Bubblewrap uses Linux kernel features called:
- Namespaces
- Mount points
- File isolation
Instead of creating full containers, it:
- Creates a new namespace
- Mounts a minimal filesystem
- Allows only selected files
- Runs the target program
- Destroys environment after execution
Bubblewrap Architecture Flow
flowchart LR
User --> bwrap
bwrap --> Namespace
Namespace --> MountFS
MountFS --> RunProgram
RunProgram --> IsolatedExecution
3. Key Features of Bubblewrap
Lightweight
No full container runtime required.
No daemon.
No heavy overhead.
Secure Isolation
Supports:
- User isolation
- File system isolation
- Process isolation
- Network restrictions
Flexible Mounting
You decide:
- What files exist
- What directories are accessible
- What is read-only
- What is writable
No Root Required (Optional)
Bubblewrap supports:
- Root execution
- Rootless containers
4. Where Bubblewrap is Used
Bubblewrap is widely used in:
Flatpak
Desktop apps use Bubblewrap to isolate applications.
Example:
flatpak run org.mozilla.firefox
Runs Firefox inside sandbox.
Developer Tools
Used by:
- AI code runners
- Secure build tools
- Test runners
- CI systems
Including tools like:
- Codex CLI
- Build sandboxes
- Packaging tools
Security Sandboxes
Used in:
- Desktop Linux
- Secure browsing
- Restricted environments
5. Installing Bubblewrap
Install on macOS
Using Homebrew:
brew install bubblewrap
Verify:
bwrap --version
Expected output:
bubblewrap 0.x.x
Install on Ubuntu / Debian
sudo apt update
sudo apt install bubblewrap
Verify:
bwrap --version
Install on RedHat / CentOS
sudo dnf install bubblewrap
Install on Amazon Linux
sudo yum install bubblewrap
Install from Source (Advanced)
git clone https://github.com/containers/bubblewrap
cd bubblewrap
./autogen.sh
./configure
make
sudo make install
6. Understanding Core Bubblewrap Concepts
Before running commands, understand these core ideas.
Namespace
A namespace isolates:
- Processes
- Files
- Users
- Network
Example:
--unshare-pid
--unshare-net
--unshare-user
Mount Binding
Allows mapping directories.
Example:
--bind /home/user /home/user
Read-Only Mount
Example:
--ro-bind /usr /usr
Temporary Filesystem
Creates fresh empty directory.
--tmpfs /tmp
7. Basic Bubblewrap Command
Minimal working example:
bwrap \
--ro-bind /usr /usr \
--ro-bind /bin /bin \
--dir /tmp \
--proc /proc \
/bin/sh
This:
- Creates isolated shell
- Mounts minimal filesystem
- Runs shell securely
What Happens Here?
| Step | Action |
|---|---|
| 1 | Creates namespace |
| 2 | Mounts /usr |
| 3 | Mounts /bin |
| 4 | Creates /tmp |
| 5 | Starts shell |
8. Running Commands Inside Sandbox
Example:
bwrap \
--ro-bind /usr /usr \
--ro-bind /bin /bin \
--dir /tmp \
--proc /proc \
/bin/ls /
Runs:
ls /
Inside sandbox.
9. Creating an Isolated Shell
Most common test scenario:
bwrap \
--ro-bind /usr /usr \
--ro-bind /bin /bin \
--ro-bind /lib /lib \
--ro-bind /lib64 /lib64 \
--dir /tmp \
--proc /proc \
/bin/bash
Now you’re inside sandbox.
Check isolation:
ls /
You’ll see minimal filesystem.
10. Using Read-Only Root Filesystem
Example:
bwrap \
--ro-bind / / \
--tmpfs /tmp \
--proc /proc \
/bin/bash
This makes:
Root filesystem read-only
Safer execution.
11. Restricting File Access
Allow only specific folder.
Example:
bwrap \
--ro-bind /usr /usr \
--bind ~/project /app \
--dir /tmp \
/bin/bash
Inside sandbox:
/app
Contains project files.
Nothing else.
12. Creating Temporary Writable Directories
Example:
--tmpfs /tmp
Creates:
Temporary memory filesystem
Deleted automatically.
13. Running Applications in Sandbox
Example:
Run Python:
bwrap \
--ro-bind /usr /usr \
--ro-bind /lib /lib \
--ro-bind /lib64 /lib64 \
--proc /proc \
--tmpfs /tmp \
python3 script.py
14. Network Isolation
Disable network:
--unshare-net
Example:
bwrap \
--unshare-net \
--ro-bind /usr /usr \
--proc /proc \
/bin/bash
Now:
ping google.com
Fails.
Network blocked.
15. User Namespace Isolation
Run as fake root:
--unshare-user
Example:
bwrap \
--unshare-user \
--uid 0 \
--gid 0 \
/bin/bash
Inside sandbox:
whoami
Returns:
root
But not real root.
16. Running Build Tools Safely
Example:
bwrap \
--bind ~/project /project \
--ro-bind /usr /usr \
--proc /proc \
--tmpfs /tmp \
make
Good for:
- CI builds
- Package testing
17. Bubblewrap vs Docker
| Feature | Bubblewrap | Docker |
|---|---|---|
| Lightweight | Yes | No |
| Daemon | No | Yes |
| Full container | No | Yes |
| Startup speed | Fast | Medium |
| Isolation | Good | Strong |
| Use case | Sandbox | Container runtime |
18. Bubblewrap vs chroot
| Feature | Bubblewrap | chroot |
|---|---|---|
| Security | Strong | Weak |
| Namespace support | Yes | No |
| Process isolation | Yes | No |
| Modern usage | Yes | Legacy |
19. Real-World Use Cases
Secure Code Execution
Used by:
- Online code runners
- AI code tools
- Build systems
CI/CD Isolation
Example pipeline:
GitHub Actions → bwrap → build → destroy
Prevents system pollution.
Malware Analysis
Run suspicious binaries safely.
Developer Testing
Run untrusted packages.
20. Troubleshooting Bubblewrap
Problem: bwrap not found
Fix:
brew install bubblewrap
Problem: Permission denied
Fix:
sudo sysctl kernel.unprivileged_userns_clone=1
(Ubuntu)
Problem: Cannot create namespace
Install:
sudo apt install uidmap
21. Security Best Practices
Always:
- Use read-only mounts
- Restrict writable directories
- Disable network if unnecessary
- Avoid exposing root filesystem
Good pattern:
--ro-bind /usr /usr
--tmpfs /tmp
--unshare-net
22. Performance Considerations
Bubblewrap is:
- Very fast startup
- Minimal overhead
- Faster than Docker for small tasks
Ideal for:
- CLI tools
- Script execution
- Test environments
23. Advanced Example — Minimal Container
Example:
bwrap \
--unshare-all \
--ro-bind /usr /usr \
--ro-bind /bin /bin \
--ro-bind /lib /lib \
--ro-bind /lib64 /lib64 \
--proc /proc \
--tmpfs /tmp \
/bin/bash
Creates:
Tiny container-like environment
24. Integration with DevOps Workflows
Useful for:
- Terraform testing
- Kubernetes scripts
- CI runners
- Secure build pipelines
Given your background in:
- EKS
- Terraform
- CI/CD
Bubblewrap is especially useful for:
safe script execution
IaC testing
sandboxing builds
25. Example — Safe Script Runner
Create:
safe-run.sh
#!/bin/bash
bwrap \
--ro-bind /usr /usr \
--bind "$PWD" /app \
--tmpfs /tmp \
--proc /proc \
/bin/bash /app/script.sh
Run:
chmod +x safe-run.sh
./safe-run.sh
26. Future of Bubblewrap
Bubblewrap continues to grow because:
- Lightweight security is needed
- Containers are heavy for small tasks
- Developer tooling requires sandboxing
Used increasingly in:
- Desktop Linux
- DevOps tooling
- AI execution environments
Final Summary
Bubblewrap is:
✔ Lightweight
✔ Secure
✔ Fast
✔ Easy to integrate
✔ Used in modern developer tooling
Best suited for:
- Developers
- DevOps engineers
- Security engineers
- CI/CD pipelines
- AI code execution tools
If you’re using Codex (like your earlier message)
Bubblewrap is exactly what:
Codex uses internally to sandbox code
So installing and understanding it is very valuable for your workflow.
If you’d like next-level labs
I can create:
- Hands-on Bubblewrap lab exercises
- CI/CD sandbox demo
- Kubernetes sandbox integration
- DevOps security lab using bwrap
Just say: