___             __       _____                ____              
   /   |  __________/ /_    / ___/____ _____  ___/ / /_  ____  _  __
  / /| | / ___/ ___/ __ \   \__ \/ __ `/ __ \/ __  / __ \/ __ \| |/_/
 / ___ |/ /  / /__/ / / /  ___/ / /_/ / / / / /_/ / /_/ / /_/ />  <  
/_/  |_/_/   \___/_/ /_/  /____/\__,_/_/ /_/\__,_/_.___/\____/_/|_|  

🏝️ Arch-Sandbox

Create and manage isolated Arch Linux environments with ease

arch-sandbox is a powerful command-line tool that spins up isolated Arch Linux environments using overlay filesystems and systemd-nspawn. Perfect for developers, system administrators, and Linux enthusiasts who need safe, disposable environments for testing and experimentation.

Features • Installation • Usage • Contributing • License

---

✨ Features

• 🔒 Isolated Environments - Run Arch Linux sandboxes without affecting your host system
• 📦 Overlay Filesystem - Keep changes separate using overlayfs technology
• 💾 Persistent or Ephemeral - Choose to keep or discard your sandbox after use
• 📸 Snapshot Management - Save and restore sandbox states
• 📦 Package Installation - Install packages directly in persistent sandboxes
• 🎯 Simple CLI - Powered by Cobra for an intuitive command-line experience
• ⚡ Lightweight - Minimal overhead, maximum performance

📋 Prerequisites

Ensure you have the following installed on your Arch Linux system:

• systemd-nspawn - for containerization
• mount - for overlay filesystem operations
• pacman - for Arch Linux package management
• zstd - for .tar.zst archive handling

Install prerequisites on Arch Linux:

sudo pacman -S systemd zstd

Note: You'll need root privileges (sudo) to run arch-sandbox due to systemd-nspawn and mount requirements.

🚀 Installation

Method 1: Install from AUR (Recommended)

The easiest way to install arch-sandbox is through the Arch User Repository (AUR):

# Using yay
yay -S arch-sandbox

# Or using paru
paru -S arch-sandbox

Note: The AUR package may be in the process of being published. If it's not available yet, please use Method 2 (Manual Installation) below.

This method automatically handles dependencies and keeps the tool up-to-date with your system.

Method 2: Manual Installation from Source

If you prefer to build from source or want the latest development version:

Step 1: Install Build Dependencies

sudo pacman -S go git systemd zstd

Step 2: Clone the Repository

git clone https://github.com/OminduD/arch-sandbox.git
cd arch-sandbox

Step 3: Build the Binary

go build -o arch-sandbox

Step 4: Install Globally (Optional)

sudo install -Dm755 arch-sandbox /usr/local/bin/arch-sandbox

Or copy it to a directory in your PATH:

sudo mv arch-sandbox /usr/local/bin/

Verify Installation

arch-sandbox --help

🛠️ Usage

Quick Start

Create a disposable sandbox for quick testing:

sudo arch-sandbox new mysandbox

Create a persistent sandbox that survives reboots:

sudo arch-sandbox new mysandbox --persist

Available Commands

Create a New Sandbox

arch-sandbox new <name> [flags]

Flags:

• -p, --persist - Keep the sandbox after exiting (default: cleanup on exit)
• --base-dir string - Base directory for sandboxes (default: ~/.arch-sandbox)

Examples:

# Create a disposable sandbox
sudo arch-sandbox new testbox

# Create a persistent sandbox
sudo arch-sandbox new devbox --persist

# Create a sandbox in a custom location
sudo arch-sandbox new projectbox --persist --base-dir /data/sandboxes

Install Packages

Install packages directly in a persistent sandbox:

sudo arch-sandbox install <sandbox-name> <package>

Example:

# Install vim in a sandbox
sudo arch-sandbox install devbox vim

# Install git in a sandbox
sudo arch-sandbox install devbox git

Manage Snapshots

Save and restore sandbox states:

# Save a snapshot
sudo arch-sandbox snapshot <sandbox-name> save <snapshot-id>

# Restore a snapshot
sudo arch-sandbox snapshot <sandbox-name> restore <snapshot-id>

# List snapshots
sudo arch-sandbox snapshot <sandbox-name> list

Sandbox Creation Process

The tool follows these steps to create a sandbox:

Start
  ↓
[Create Directories] → [Check Dependencies]
                          ↓
                       [Download Tarball]
                          ↓
                       [Extract Tarball]
                          ↓
                       [Mount Overlayfs]
                          ↓
                       [Launch systemd-nspawn]
                          ↓
                       [Cleanup (if not persistent)]

Inside the Sandbox

You'll enter a /bin/bash shell where you can:

• 📦 Install packages with pacman
• 🧪 Test scripts or configurations safely
• 🔧 Experiment with system changes
• 📝 Develop and test software
• 🚪 Exit with exit or Ctrl+D

Managing Sandboxes

Cleanup

• Disposable Sandboxes: Automatically deleted on exit
• Persistent Sandboxes: Stored in ~/.arch-sandbox/<name>

Delete a persistent sandbox manually:

rm -rf ~/.arch-sandbox/<name>

List All Sandboxes

ls -la ~/.arch-sandbox/

⚠️ Important Notes

• 🔐 Run as root or with sudo for systemd-nspawn and mount operations
• 🌐 Internet access is required for tarball download
• 📦 Tarball source: https://archive.archlinux.org/iso/2025.07.01/archlinux-bootstrap-2025.07.01-x86_64.tar.zst

🤝 Contributing

We welcome contributions from everyone! Whether you're fixing bugs, adding features, or improving documentation, your help makes arch-sandbox better.

Please see our Contributing Guide for detailed instructions on how to get started, set up your development environment, and submit your pull requests.

📜 License

MIT License. See LICENSE for details.

---

Made with ❤️ by the Arch-Sandbox community