vagrant-sandbox 0.1.0__tar.gz

vagrant_sandbox-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 vagrant-sandbox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

vagrant_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: vagrant-sandbox
+Version: 0.1.0
+Summary: Generate and provision isolated Vagrant development environments
+Author: actocodes
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/actocodes/vagrant-sandbox
+Project-URL: Repository, https://github.com/actocodes/vagrant-sandbox
+Project-URL: Issues, https://github.com/actocodes/vagrant-sandbox/issues
+Project-URL: Changelog, https://github.com/actocodes/vagrant-sandbox/releases
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Vagrant Sandbox
+
+`vagrant-sandbox` generates an isolated Ubuntu Vagrant environment, copies the selected provisioning scripts into the project, and can start the VM immediately.
+
+## Requirements
+
+- Python 3.11 or newer
+- Vagrant installed and available on `PATH`
+- A Vagrant provider such as VirtualBox, VMware, or Parallels
+
+## Install and run
+
+Install the command with `pipx`:
+
+```console
+pipx install vagrant-sandbox
+vagrant-sandbox create
+```
+
+For a one-off run without a persistent installation:
+
+```console
+pipx run vagrant-sandbox create
+```
+
+For local development from a checkout:
+
+```console
+python -m pip install .
+vagrant-sandbox create
+```
+
+`create` prompts for VM settings in an interactive terminal, writes a `Vagrantfile` and `.vagrant-sandbox/provision/` scripts in the current directory, then runs `vagrant up`. To create the files without starting the VM:
+
+```console
+vagrant-sandbox create --no-up
+```
+
+Use `--directory` to choose another output directory. Existing generated files are never replaced unless `--force` is provided.
+
+Choose a distinct private IP for each VM that runs on the same host.
+
+## Customize
+
+Configuration precedence is command-line options over JSON config values over built-in defaults. An example config:
+
+```json
+{
+  "vm_name": "web-dev",
+  "vm_ip": "192.168.56.20",
+  "cpus": 4,
+  "memory": 4096,
+  "box": "bento/ubuntu-24.04",
+  "provider": "virtualbox",
+  "profiles": ["base", "docker", "nodejs"],
+  "custom_scripts": ["scripts/install-tools.sh"]
+}
+```
+
+Custom script paths in a config file are relative to that config file. Scripts are copied into the generated project and run as privileged Vagrant shell provisioners, after the built-in profiles. Only use scripts you trust.
+
+```console
+vagrant-sandbox create --config sandbox.json --vm-name web-dev --cpus 4
+vagrant-sandbox create --profile python --profile docker --provision ./scripts/extra.sh
+vagrant-sandbox profiles
+```
+
+Supported profiles are `base`, `docker`, `nodejs`, and `python`. The `base` profile is always included. `--profile` can be repeated to choose profiles, when omitted, config profiles are used, then the default `base`.
+
+The generated VM does not share the project directory with the host and disables SSH agent forwarding. It uses a host-only private network and does not forward application ports to localhost. Run `vagrant destroy` from the generated project directory to remove the VM.

vagrant_sandbox-0.1.0/README.md

@@ -0,0 +1,70 @@
+# Vagrant Sandbox
+
+`vagrant-sandbox` generates an isolated Ubuntu Vagrant environment, copies the selected provisioning scripts into the project, and can start the VM immediately.
+
+## Requirements
+
+- Python 3.11 or newer
+- Vagrant installed and available on `PATH`
+- A Vagrant provider such as VirtualBox, VMware, or Parallels
+
+## Install and run
+
+Install the command with `pipx`:
+
+```console
+pipx install vagrant-sandbox
+vagrant-sandbox create
+```
+
+For a one-off run without a persistent installation:
+
+```console
+pipx run vagrant-sandbox create
+```
+
+For local development from a checkout:
+
+```console
+python -m pip install .
+vagrant-sandbox create
+```
+
+`create` prompts for VM settings in an interactive terminal, writes a `Vagrantfile` and `.vagrant-sandbox/provision/` scripts in the current directory, then runs `vagrant up`. To create the files without starting the VM:
+
+```console
+vagrant-sandbox create --no-up
+```
+
+Use `--directory` to choose another output directory. Existing generated files are never replaced unless `--force` is provided.
+
+Choose a distinct private IP for each VM that runs on the same host.
+
+## Customize
+
+Configuration precedence is command-line options over JSON config values over built-in defaults. An example config:
+
+```json
+{
+  "vm_name": "web-dev",
+  "vm_ip": "192.168.56.20",
+  "cpus": 4,
+  "memory": 4096,
+  "box": "bento/ubuntu-24.04",
+  "provider": "virtualbox",
+  "profiles": ["base", "docker", "nodejs"],
+  "custom_scripts": ["scripts/install-tools.sh"]
+}
+```
+
+Custom script paths in a config file are relative to that config file. Scripts are copied into the generated project and run as privileged Vagrant shell provisioners, after the built-in profiles. Only use scripts you trust.
+
+```console
+vagrant-sandbox create --config sandbox.json --vm-name web-dev --cpus 4
+vagrant-sandbox create --profile python --profile docker --provision ./scripts/extra.sh
+vagrant-sandbox profiles
+```
+
+Supported profiles are `base`, `docker`, `nodejs`, and `python`. The `base` profile is always included. `--profile` can be repeated to choose profiles, when omitted, config profiles are used, then the default `base`.
+
+The generated VM does not share the project directory with the host and disables SSH agent forwarding. It uses a host-only private network and does not forward application ports to localhost. Run `vagrant destroy` from the generated project directory to remove the VM.

vagrant_sandbox-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vagrant-sandbox"
+version = "0.1.0"
+description = "Generate and provision isolated Vagrant development environments"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "actocodes" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: System :: Systems Administration",
+  "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/actocodes/vagrant-sandbox"
+Repository = "https://github.com/actocodes/vagrant-sandbox"
+Issues = "https://github.com/actocodes/vagrant-sandbox/issues"
+Changelog = "https://github.com/actocodes/vagrant-sandbox/releases"
+
+[project.scripts]
+vagrant-sandbox = "vagrant_sandbox.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+vagrant_sandbox = ["templates/*", "profiles/*.sh"]

vagrant_sandbox-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vagrant_sandbox-0.1.0/src/vagrant_sandbox/__init__.py

@@ -0,0 +1,4 @@
+"""Create and provision isolated Vagrant development environments."""
+
+__version__ = "0.1.0"
+

vagrant_sandbox-0.1.0/src/vagrant_sandbox/cli.py

@@ -0,0 +1,97 @@
+import argparse
+import sys
+from pathlib import Path
+
+from .generator import generate_project, start_vm
+from .settings import AVAILABLE_PROFILES, load_config, resolve_settings
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="vagrant-sandbox",
+        description="Generate and provision an isolated Vagrant development VM.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    create = subparsers.add_parser("create", help="Generate a Vagrantfile and start the VM.")
+    create.add_argument("--config", type=Path, help="JSON configuration file.")
+    create.add_argument(
+        "--directory",
+        type=Path,
+        default=Path.cwd(),
+        help="Project directory (default: current directory).",
+    )
+    create.add_argument("--vm-name")
+    create.add_argument("--vm-ip")
+    create.add_argument("--cpus", type=int)
+    create.add_argument("--memory", type=int, help="VM memory in MB.")
+    create.add_argument("--box")
+    create.add_argument("--provider", help="Vagrant provider (for example virtualbox).")
+    create.add_argument(
+        "--profile",
+        action="append",
+        choices=AVAILABLE_PROFILES,
+        dest="profiles",
+        help="Provisioning profile; repeat to select multiple (default: base).",
+    )
+    create.add_argument(
+        "--provision",
+        action="append",
+        type=Path,
+        dest="custom_scripts",
+        help="Custom shell provisioning script; repeat to add multiple.",
+    )
+    create.add_argument("--force", action="store_true", help="Replace generated files that already exist.")
+    create.add_argument("--no-up", action="store_true", help="Generate files without running vagrant up.")
+    create.add_argument("--non-interactive", action="store_true", help="Do not prompt; use config and defaults.")
+
+    subparsers.add_parser("profiles", help="List built-in provisioning profiles.")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "profiles":
+        print("Available profiles:")
+        print("  base    Common CLI tools, build essentials, Git, and workspace setup")
+        print("  docker  Docker Engine")
+        print("  nodejs  Node.js LTS")
+        print("  python  Python 3, pip, and venv")
+        return 0
+
+    try:
+        config = load_config(args.config)
+        cli_values = {
+            key: getattr(args, key)
+            for key in (
+                "vm_name",
+                "vm_ip",
+                "cpus",
+                "memory",
+                "box",
+                "provider",
+                "profiles",
+                "custom_scripts",
+            )
+        }
+        settings = resolve_settings(
+            config,
+            cli_values,
+            interactive=not args.non_interactive and sys.stdin.isatty(),
+        )
+        vagrantfile = generate_project(settings, args.directory, force=args.force)
+        print(f"Generated {vagrantfile}")
+        if args.no_up:
+            return 0
+        result = start_vm(settings, args.directory.resolve())
+        if result:
+            print(f"vagrant up failed with exit code {result}.", file=sys.stderr)
+        return result
+    except (ValueError, FileExistsError, OSError, RuntimeError) as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vagrant_sandbox-0.1.0/src/vagrant_sandbox/generator.py

@@ -0,0 +1,100 @@
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+from .settings import Settings
+
+
+PACKAGE_DIR = Path(__file__).parent
+TEMPLATE_PATH = PACKAGE_DIR / "templates" / "Vagrantfile.template"
+PROFILES_DIR = PACKAGE_DIR / "profiles"
+PROVISION_DIR = Path(".vagrant-sandbox") / "provision"
+
+
+def render_vagrantfile(settings: Settings) -> str:
+    blocks = [
+        _provision_block(f"profile-{profile}", PROVISION_DIR / f"{profile}.sh")
+        for profile in settings.profiles
+    ]
+    blocks.append(
+        _provision_block(
+            "user-setup",
+            PROVISION_DIR / "user-setup.sh",
+            privileged=False,
+        )
+    )
+    blocks.extend(
+        _provision_block(
+            f"custom-{index + 1}",
+            PROVISION_DIR / f"custom-{index + 1}-{script.name}",
+        )
+        for index, script in enumerate(settings.custom_scripts)
+    )
+    template = TEMPLATE_PATH.read_text(encoding="utf-8")
+    replacements = {
+        "@@VM_NAME@@": json.dumps(settings.vm_name),
+        "@@VM_IP@@": json.dumps(settings.vm_ip),
+        "@@VM_CPUS@@": str(settings.cpus),
+        "@@VM_MEMORY@@": str(settings.memory),
+        "@@BOX@@": json.dumps(settings.box),
+        "@@PROVISIONERS@@": "\n".join(blocks),
+    }
+    for marker, value in replacements.items():
+        template = template.replace(marker, value)
+    return template
+
+
+def generate_project(settings: Settings, output_dir: Path, force: bool = False) -> Path:
+    output_dir = output_dir.resolve()
+    vagrantfile = output_dir / "Vagrantfile"
+    provision_dir = output_dir / PROVISION_DIR
+    generated_paths = [vagrantfile]
+    generated_paths.extend(
+        provision_dir / f"{profile}.sh" for profile in settings.profiles
+    )
+    generated_paths.append(provision_dir / "user-setup.sh")
+    generated_paths.extend(
+        provision_dir / f"custom-{index + 1}-{script.name}"
+        for index, script in enumerate(settings.custom_scripts)
+    )
+    existing = [path for path in generated_paths if path.exists()]
+    if existing and not force:
+        names = ", ".join(str(path.relative_to(output_dir)) for path in existing)
+        raise FileExistsError(
+            f"Generated file(s) already exist: {names}. Use --force to replace them."
+        )
+
+    provision_dir.mkdir(parents=True, exist_ok=True)
+    for profile in settings.profiles:
+        source = PROFILES_DIR / f"{profile}.sh"
+        shutil.copyfile(source, provision_dir / f"{profile}.sh")
+    shutil.copyfile(PROFILES_DIR / "user-setup.sh", provision_dir / "user-setup.sh")
+    for index, script in enumerate(settings.custom_scripts):
+        shutil.copyfile(script, provision_dir / f"custom-{index + 1}-{script.name}")
+    vagrantfile.write_text(render_vagrantfile(settings), encoding="utf-8", newline="\n")
+    return vagrantfile
+
+
+def start_vm(settings: Settings, output_dir: Path) -> int:
+    command = ["vagrant", "up"]
+    if settings.provider:
+        command.extend(["--provider", settings.provider])
+    try:
+        result = subprocess.run(command, cwd=output_dir, check=False)
+    except FileNotFoundError as error:
+        raise RuntimeError(
+            "Vagrant was not found. Install Vagrant and ensure it is on PATH."
+        ) from error
+    return result.returncode
+
+
+def _provision_block(name: str, script_path: Path, privileged: bool = True) -> str:
+    relative = script_path.as_posix()
+    options = (
+        f"name: {json.dumps(name)}, "
+        f"path: File.expand_path({json.dumps(relative)}, __dir__)"
+    )
+    if not privileged:
+        options += ", privileged: false"
+    return f'  config.vm.provision "shell", {options}\n'

vagrant_sandbox-0.1.0/src/vagrant_sandbox/profiles/base.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+export DEBIAN_FRONTEND=noninteractive
+
+apt-get update -y
+apt-get upgrade -y
+apt-get install -y build-essential git curl wget unzip jq vim tmux htop tree ripgrep ca-certificates gnupg ufw
+timedatectl set-timezone UTC
+

vagrant_sandbox-0.1.0/src/vagrant_sandbox/profiles/docker.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+export DEBIAN_FRONTEND=noninteractive
+
+if ! command -v docker >/dev/null 2>&1; then
+  curl -fsSL https://get.docker.com | sh
+fi
+usermod -aG docker vagrant
+systemctl enable --now docker
+

vagrant_sandbox-0.1.0/src/vagrant_sandbox/profiles/nodejs.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+export DEBIAN_FRONTEND=noninteractive
+
+if ! command -v node >/dev/null 2>&1; then
+  curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
+  apt-get install -y nodejs
+fi
+

vagrant_sandbox-0.1.0/src/vagrant_sandbox/profiles/python.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+export DEBIAN_FRONTEND=noninteractive
+
+apt-get install -y python3 python3-pip python3-venv
+

vagrant_sandbox-0.1.0/src/vagrant_sandbox/profiles/user-setup.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+mkdir -p "$HOME/workspace"
+if ! grep -Fq "alias ll=" "$HOME/.bashrc"; then
+  cat >> "$HOME/.bashrc" <<'EOF'
+
+# --- dev sandbox ---
+alias ll='ls -alF'
+alias gs='git status'
+cd ~/workspace 2>/dev/null || true
+EOF
+fi
+git config --global init.defaultBranch main
+

vagrant_sandbox-0.1.0/src/vagrant_sandbox/settings.py

@@ -0,0 +1,193 @@
+import ipaddress
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+
+DEFAULTS: dict[str, Any] = {
+    "vm_name": "sandbox",
+    "vm_ip": "192.168.56.10",
+    "cpus": 2,
+    "memory": 2048,
+    "box": "bento/ubuntu-24.04",
+    "provider": None,
+    "profiles": ["base"],
+    "custom_scripts": [],
+}
+ALLOWED_CONFIG_KEYS = frozenset(DEFAULTS)
+AVAILABLE_PROFILES = ("base", "docker", "nodejs", "python")
+PRIVATE_NETWORKS = tuple(
+    ipaddress.ip_network(network)
+    for network in ("10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16")
+)
+
+
+@dataclass(frozen=True)
+class Settings:
+    vm_name: str
+    vm_ip: str
+    cpus: int
+    memory: int
+    box: str
+    provider: str | None
+    profiles: tuple[str, ...]
+    custom_scripts: tuple[Path, ...]
+
+
+def load_config(path: Path | None) -> dict[str, Any]:
+    if path is None:
+        return {}
+    try:
+        with path.open(encoding="utf-8") as config_file:
+            data = json.load(config_file)
+    except (OSError, json.JSONDecodeError) as error:
+        raise ValueError(f"Could not read config file '{path}': {error}") from error
+    if not isinstance(data, dict):
+        raise ValueError("Config file must contain a JSON object.")
+    unknown = set(data) - ALLOWED_CONFIG_KEYS
+    if unknown:
+        raise ValueError(f"Unknown config option(s): {', '.join(sorted(unknown))}")
+    if "custom_scripts" in data:
+        scripts = data["custom_scripts"]
+        if not isinstance(scripts, list) or not all(isinstance(item, str) for item in scripts):
+            raise ValueError("'custom_scripts' must be a list of file paths.")
+        data["custom_scripts"] = [
+            (path.parent / item).resolve() if not Path(item).is_absolute() else Path(item)
+            for item in scripts
+        ]
+    return data
+
+
+def resolve_settings(
+    config: dict[str, Any],
+    cli: dict[str, Any],
+    interactive: bool = False,
+    input_fn: Callable[[str], str] = input,
+) -> Settings:
+    values = {**DEFAULTS, **config}
+    for key, value in cli.items():
+        if value is not None:
+            if key == "custom_scripts":
+                values[key] = [*values["custom_scripts"], *value]
+            else:
+                values[key] = value
+
+    if interactive:
+        prompts = (
+            ("vm_name", "VM name"),
+            ("vm_ip", "Private IPv4 address"),
+            ("cpus", "CPU cores"),
+            ("memory", "Memory in MB"),
+            ("box", "Vagrant box"),
+            ("provider", "Provider (blank for Vagrant default)"),
+            ("profiles", "Provisioning profiles (comma-separated)"),
+            ("custom_scripts", "Custom shell scripts (comma-separated paths)"),
+        )
+        for key, label in prompts:
+            if cli.get(key) is not None:
+                continue
+            current = values[key]
+            if key in ("profiles", "custom_scripts"):
+                shown = ", ".join(str(item) for item in current)
+            else:
+                shown = "" if current is None else str(current)
+            answer = input_fn(f"{label} [{shown}]: ").strip()
+            if not answer:
+                if key == "provider":
+                    values[key] = None
+                continue
+            if key in ("profiles", "custom_scripts"):
+                items = [item.strip() for item in answer.split(",") if item.strip()]
+                values[key] = items if key == "profiles" else [
+                    Path(item).expanduser().resolve() for item in items
+                ]
+            elif key in ("cpus", "memory"):
+                try:
+                    values[key] = int(answer)
+                except ValueError as error:
+                    raise ValueError(f"{label} must be an integer.") from error
+            else:
+                values[key] = answer or None
+
+    return validate_settings(values)
+
+
+def validate_settings(values: dict[str, Any]) -> Settings:
+    vm_name = values["vm_name"]
+    if not isinstance(vm_name, str) or not re.fullmatch(
+        r"[A-Za-z0-9][A-Za-z0-9_-]{0,62}", vm_name
+    ):
+        raise ValueError(
+            "VM name must be 1-63 letters, digits, hyphens, or underscores and start with a letter or digit."
+        )
+
+    vm_ip = values["vm_ip"]
+    if not isinstance(vm_ip, str):
+        raise ValueError("VM IP must be a valid private IPv4 address.")
+    try:
+        ip = ipaddress.ip_address(vm_ip)
+    except (TypeError, ValueError) as error:
+        raise ValueError("VM IP must be a valid IPv4 or IPv6 address.") from error
+    if not isinstance(ip, ipaddress.IPv4Address):
+        raise ValueError("VM IP must be IPv4 for Vagrant's host-only network.")
+    if not any(ip in network for network in PRIVATE_NETWORKS):
+        raise ValueError(
+            "VM IP must belong to a private IPv4 range (10/8, 172.16/12, or 192.168/16)."
+        )
+
+    cpus = _bounded_integer(values["cpus"], "CPU count", 1, 256)
+    memory = _bounded_integer(values["memory"], "Memory", 512, 1_048_576)
+    box = values["box"]
+    if not isinstance(box, str) or not box.strip() or any(char in box for char in "\r\n"):
+        raise ValueError("Vagrant box must be a non-empty single-line string.")
+
+    provider = values["provider"]
+    if provider is not None and (
+        not isinstance(provider, str) or not re.fullmatch(r"[A-Za-z0-9_-]+", provider)
+    ):
+        raise ValueError("Provider must contain only letters, digits, hyphens, or underscores.")
+
+    profiles_value = values["profiles"]
+    if not isinstance(profiles_value, (list, tuple)) or not all(
+        isinstance(item, str) for item in profiles_value
+    ):
+        raise ValueError("'profiles' must be a list of profile names.")
+    profiles = list(dict.fromkeys(profiles_value))
+    unknown_profiles = set(profiles) - set(AVAILABLE_PROFILES)
+    if unknown_profiles:
+        raise ValueError(f"Unknown profile(s): {', '.join(sorted(unknown_profiles))}")
+    if not profiles:
+        profiles = ["base"]
+    if "base" not in profiles:
+        profiles.insert(0, "base")
+
+    scripts_value = values["custom_scripts"]
+    if not isinstance(scripts_value, (list, tuple)):
+        raise ValueError("'custom_scripts' must be a list of file paths.")
+    scripts: list[Path] = []
+    for script in scripts_value:
+        if not isinstance(script, (str, Path)):
+            raise ValueError("Each custom provisioning script must be a file path.")
+        path = Path(script).expanduser().resolve()
+        if not path.is_file():
+            raise ValueError(f"Custom provisioning script does not exist: {path}")
+        scripts.append(path)
+
+    return Settings(
+        vm_name=vm_name,
+        vm_ip=str(ip),
+        cpus=cpus,
+        memory=memory,
+        box=box.strip(),
+        provider=provider,
+        profiles=tuple(profiles),
+        custom_scripts=tuple(scripts),
+    )
+
+
+def _bounded_integer(value: Any, label: str, minimum: int, maximum: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or not minimum <= value <= maximum:
+        raise ValueError(f"{label} must be between {minimum} and {maximum}.")
+    return value

vagrant_sandbox-0.1.0/src/vagrant_sandbox/templates/Vagrantfile.template

@@ -0,0 +1,48 @@
+# Generated by vagrant-sandbox. Edit settings through the config or CLI.
+VM_NAME = @@VM_NAME@@
+VM_IP = @@VM_IP@@
+VM_CPUS = @@VM_CPUS@@
+VM_MEMORY = @@VM_MEMORY@@
+
+Vagrant.configure("2") do |config|
+  config.vm.box = @@BOX@@
+  config.vm.hostname = VM_NAME
+
+  # Keep project files on the host isolated from the guest.
+  config.vm.synced_folder ".", "/vagrant", disabled: true
+  config.ssh.forward_agent = false
+  config.ssh.forward_x11 = false
+  config.vm.network "private_network", ip: VM_IP
+
+  config.vm.provider "virtualbox" do |vb|
+    vb.name = VM_NAME
+    vb.cpus = VM_CPUS
+    vb.memory = VM_MEMORY
+    vb.linked_clone = true
+    vb.customize ["modifyvm", :id, "--clipboard-mode", "disabled"]
+    vb.customize ["modifyvm", :id, "--draganddrop", "disabled"]
+    vb.customize ["modifyvm", :id, "--natdnshostresolver1", "on"]
+  end
+
+  config.vm.provider "vmware_desktop" do |vmware|
+    vmware.vmx["numvcpus"] = VM_CPUS.to_s
+    vmware.vmx["memsize"] = VM_MEMORY.to_s
+    vmware.vmx["isolation.tools.copy.disable"] = "TRUE"
+    vmware.vmx["isolation.tools.paste.disable"] = "TRUE"
+    vmware.vmx["isolation.tools.dnd.disable"] = "TRUE"
+  end
+
+  config.vm.provider "parallels" do |parallels|
+    parallels.cpus = VM_CPUS
+    parallels.memory = VM_MEMORY
+  end
+
+@@PROVISIONERS@@
+
+  config.vm.post_up_message = <<-MSG
+    Sandbox '#{VM_NAME}' is up at #{VM_IP}.
+    Clone repositories into ~/workspace inside the VM; host folders are not shared.
+    Add SSH config with: vagrant ssh-config --host sandbox-#{VM_NAME}
+  MSG
+end
+

vagrant_sandbox-0.1.0/src/vagrant_sandbox.egg-info/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: vagrant-sandbox
+Version: 0.1.0
+Summary: Generate and provision isolated Vagrant development environments
+Author: actocodes
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/actocodes/vagrant-sandbox
+Project-URL: Repository, https://github.com/actocodes/vagrant-sandbox
+Project-URL: Issues, https://github.com/actocodes/vagrant-sandbox/issues
+Project-URL: Changelog, https://github.com/actocodes/vagrant-sandbox/releases
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Vagrant Sandbox
+
+`vagrant-sandbox` generates an isolated Ubuntu Vagrant environment, copies the selected provisioning scripts into the project, and can start the VM immediately.
+
+## Requirements
+
+- Python 3.11 or newer
+- Vagrant installed and available on `PATH`
+- A Vagrant provider such as VirtualBox, VMware, or Parallels
+
+## Install and run
+
+Install the command with `pipx`:
+
+```console
+pipx install vagrant-sandbox
+vagrant-sandbox create
+```
+
+For a one-off run without a persistent installation:
+
+```console
+pipx run vagrant-sandbox create
+```
+
+For local development from a checkout:
+
+```console
+python -m pip install .
+vagrant-sandbox create
+```
+
+`create` prompts for VM settings in an interactive terminal, writes a `Vagrantfile` and `.vagrant-sandbox/provision/` scripts in the current directory, then runs `vagrant up`. To create the files without starting the VM:
+
+```console
+vagrant-sandbox create --no-up
+```
+
+Use `--directory` to choose another output directory. Existing generated files are never replaced unless `--force` is provided.
+
+Choose a distinct private IP for each VM that runs on the same host.
+
+## Customize
+
+Configuration precedence is command-line options over JSON config values over built-in defaults. An example config:
+
+```json
+{
+  "vm_name": "web-dev",
+  "vm_ip": "192.168.56.20",
+  "cpus": 4,
+  "memory": 4096,
+  "box": "bento/ubuntu-24.04",
+  "provider": "virtualbox",
+  "profiles": ["base", "docker", "nodejs"],
+  "custom_scripts": ["scripts/install-tools.sh"]
+}
+```
+
+Custom script paths in a config file are relative to that config file. Scripts are copied into the generated project and run as privileged Vagrant shell provisioners, after the built-in profiles. Only use scripts you trust.
+
+```console
+vagrant-sandbox create --config sandbox.json --vm-name web-dev --cpus 4
+vagrant-sandbox create --profile python --profile docker --provision ./scripts/extra.sh
+vagrant-sandbox profiles
+```
+
+Supported profiles are `base`, `docker`, `nodejs`, and `python`. The `base` profile is always included. `--profile` can be repeated to choose profiles, when omitted, config profiles are used, then the default `base`.
+
+The generated VM does not share the project directory with the host and disables SSH agent forwarding. It uses a host-only private network and does not forward application ports to localhost. Run `vagrant destroy` from the generated project directory to remove the VM.

vagrant_sandbox-0.1.0/src/vagrant_sandbox.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+src/vagrant_sandbox/__init__.py
+src/vagrant_sandbox/cli.py
+src/vagrant_sandbox/generator.py
+src/vagrant_sandbox/settings.py
+src/vagrant_sandbox.egg-info/PKG-INFO
+src/vagrant_sandbox.egg-info/SOURCES.txt
+src/vagrant_sandbox.egg-info/dependency_links.txt
+src/vagrant_sandbox.egg-info/entry_points.txt
+src/vagrant_sandbox.egg-info/top_level.txt
+src/vagrant_sandbox/profiles/base.sh
+src/vagrant_sandbox/profiles/docker.sh
+src/vagrant_sandbox/profiles/nodejs.sh
+src/vagrant_sandbox/profiles/python.sh
+src/vagrant_sandbox/profiles/user-setup.sh
+src/vagrant_sandbox/templates/Vagrantfile.template
+tests/test_cli.py
+tests/test_generator.py
+tests/test_settings.py

vagrant_sandbox-0.1.0/src/vagrant_sandbox.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vagrant_sandbox-0.1.0/src/vagrant_sandbox.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vagrant-sandbox = vagrant_sandbox.cli:main

vagrant_sandbox-0.1.0/src/vagrant_sandbox.egg-info/top_level.txt

@@ -0,0 +1 @@
+vagrant_sandbox

vagrant_sandbox-0.1.0/tests/test_cli.py

@@ -0,0 +1,27 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+from vagrant_sandbox.cli import main
+
+
+class CliTests(unittest.TestCase):
+    def test_no_up_generates_project_files(self):
+        with tempfile.TemporaryDirectory() as directory:
+            result = main(
+                [
+                    "create",
+                    "--directory",
+                    directory,
+                    "--non-interactive",
+                    "--no-up",
+                ]
+            )
+            root = Path(directory)
+            self.assertEqual(result, 0)
+            self.assertTrue((root / "Vagrantfile").is_file())
+            self.assertTrue((root / ".vagrant-sandbox" / "provision" / "user-setup.sh").is_file())
+
+
+if __name__ == "__main__":
+    unittest.main()

vagrant_sandbox-0.1.0/tests/test_generator.py

@@ -0,0 +1,67 @@
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from vagrant_sandbox.generator import generate_project, render_vagrantfile, start_vm
+from vagrant_sandbox.settings import resolve_settings
+
+
+class GeneratorTests(unittest.TestCase):
+    def test_render_preserves_isolation_and_selected_provisioners(self):
+        settings = resolve_settings({}, {"vm_name": "testbox", "profiles": ["nodejs"]})
+        content = render_vagrantfile(settings)
+        self.assertIn('config.vm.synced_folder ".", "/vagrant", disabled: true', content)
+        self.assertIn("config.ssh.forward_agent = false", content)
+        self.assertIn('name: "profile-base"', content)
+        self.assertIn('name: "profile-nodejs"', content)
+        self.assertIn('name: "user-setup"', content)
+        self.assertIn("privileged: false", content)
+        self.assertIn('VM_NAME = "testbox"', content)
+
+    def test_generation_refuses_to_replace_without_force(self):
+        settings = resolve_settings({}, {})
+        with tempfile.TemporaryDirectory() as directory:
+            output = Path(directory)
+            (output / "Vagrantfile").write_text("keep me", encoding="utf-8")
+            with self.assertRaises(FileExistsError):
+                generate_project(settings, output)
+            self.assertEqual((output / "Vagrantfile").read_text(encoding="utf-8"), "keep me")
+
+    def test_custom_script_is_copied_and_referenced(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            custom_script = root / "custom.sh"
+            custom_script.write_text("echo custom\n", encoding="utf-8")
+            settings = resolve_settings({}, {"custom_scripts": [custom_script]})
+            output = root / "project"
+            generate_project(settings, output)
+            self.assertEqual(
+                (output / ".vagrant-sandbox" / "provision" / "custom-1-custom.sh").read_text(encoding="utf-8"),
+                "echo custom\n",
+            )
+            generated = (output / "Vagrantfile").read_text(encoding="utf-8")
+            self.assertIn("custom-1-custom.sh", generated)
+
+    def test_interactive_blank_provider_clears_configured_provider(self):
+        answers = iter(("", "", "", "", "", "", "", ""))
+        settings = resolve_settings(
+            {"provider": "virtualbox"},
+            {},
+            interactive=True,
+            input_fn=lambda _prompt: next(answers),
+        )
+        self.assertIsNone(settings.provider)
+
+    def test_start_vm_passes_provider_without_shell(self):
+        settings = resolve_settings({}, {"provider": "virtualbox"})
+        with patch("vagrant_sandbox.generator.subprocess.run") as run:
+            run.return_value.returncode = 0
+            self.assertEqual(start_vm(settings, Path(".")), 0)
+            run.assert_called_once_with(
+                ["vagrant", "up", "--provider", "virtualbox"], cwd=Path("."), check=False
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

vagrant_sandbox-0.1.0/tests/test_settings.py

@@ -0,0 +1,50 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+from vagrant_sandbox.settings import load_config, resolve_settings
+
+
+class SettingsTests(unittest.TestCase):
+    def test_base_profile_is_always_included(self):
+        settings = resolve_settings({}, {"profiles": ["docker"]})
+        self.assertEqual(settings.profiles, ("base", "docker"))
+
+    def test_cli_overrides_config(self):
+        settings = resolve_settings(
+            {"vm_name": "from-config", "cpus": 4},
+            {"vm_name": "from-cli", "cpus": None},
+        )
+        self.assertEqual(settings.vm_name, "from-cli")
+        self.assertEqual(settings.cpus, 4)
+
+    def test_rejects_invalid_ip_and_unknown_profile(self):
+        for values in (
+            {"vm_ip": "not-an-ip"},
+            {"vm_ip": "8.8.8.8"},
+            {"profiles": ["not-a-profile"]},
+        ):
+            with self.subTest(values=values), self.assertRaises(ValueError):
+                resolve_settings(values, {})
+
+    def test_custom_script_paths_are_relative_to_config(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            script = root / "install.sh"
+            script.write_text("echo ready\n", encoding="utf-8")
+            config_file = root / "config.json"
+            config_file.write_text('{"custom_scripts": ["install.sh"]}', encoding="utf-8")
+            config = load_config(config_file)
+            settings = resolve_settings(config, {})
+            self.assertEqual(settings.custom_scripts, (script.resolve(),))
+
+    def test_interactive_values_override_defaults(self):
+        answers = iter(("devbox", "192.168.56.22", "4", "4096", "ubuntu/jammy64", "", "base,python", ""))
+        settings = resolve_settings({}, {}, interactive=True, input_fn=lambda _prompt: next(answers))
+        self.assertEqual(settings.vm_name, "devbox")
+        self.assertEqual(settings.cpus, 4)
+        self.assertEqual(settings.profiles, ("base", "python"))
+
+
+if __name__ == "__main__":
+    unittest.main()