Metadata-Version: 2.4
Name: debsb
Version: 0.1.1
Summary: Debian Sid Sandbox — instant QEMU/KVM VM from cloud images
Author-email: Yunseong Kim <yunseong.kim@est.tech>
License: GPL-2.0-only
Project-URL: Homepage, https://github.com/yskzalloc/debsb
Project-URL: Repository, https://github.com/yskzalloc/debsb
Project-URL: Issues, https://github.com/yskzalloc/debsb/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Emulators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# debsb

Debian Sid sandbox in one command. Downloads a Debian cloud image, boots it in QEMU/KVM, and gives you an isolated VM with auto-login, SSH, and shared filesystem. No kernel building, no complex setup.

## Install

```bash
pip install debsb
```

### Dependencies

- `qemu-system-x86_64` (with KVM support)
- `cloud-image-utils` (`cloud-localds`)
- `whois` (`mkpasswd`)
- `wget`
- `ssh`

On Debian/Ubuntu:
```bash
sudo apt install qemu-system-x86 cloud-image-utils whois wget openssh-client
```

## Usage

### Build the sandbox (one-time)

```bash
debsb build --size 20G
```

This downloads the Debian Sid cloud image, configures SSH keys and auto-login, and runs first boot. All artifacts are stored in `~/.debsb/`.

Use `--reset` to skip the prompt and rebuild from scratch:
```bash
debsb build --size 20G --reset
```

### Run the sandbox

```bash
# Serial console (auto-login as debian, Ctrl-A X to quit)
debsb run

# SSH session (as debian)
debsb run --ssh

# SSH as root
debsb run --ssh --root

# Run a command and auto-shutdown (requires --ssh)
debsb run --ssh --root --exec "apt update && apt upgrade -y"

# Graphical QEMU window
debsb run --graphics

# With sound
debsb run --sound

# Extra QEMU options
debsb run --qemu-opts='-m 8192'
```

### Execute a command

`--exec` runs a command via SSH and shuts down automatically. Requires `--ssh`:

```bash
debsb run --ssh --exec "uname -a"
debsb run --ssh --root --exec "ls -ahl .debsb"
debsb run --ssh --exec "./my-script.sh"
```

This is useful for CI/automation. The exit code of the command is propagated.

### Verbose mode

Show kernel boot messages:
```bash
debsb run --verbose
```

## Shared filesystem

Your host `~/.debsb/` directory is mounted inside the VM at:
- `/root/.debsb` (symlink to `/mnt/debsb`)
- `/home/debian/.debsb` (symlink to `/mnt/debsb`)

This is automatic — no manual mounting needed.

## How it works

1. Downloads `debian-sid-generic-amd64-daily.qcow2` from cloud.debian.org
2. Creates a cloud-init ISO with SSH keys, user config, and auto-login
3. Boots the VM with QEMU/KVM and waits for cloud-init to finish
4. On subsequent `debsb run`, boots the prepared image directly

## Accounts

| User | Access |
|------|--------|
| `debian` | Serial auto-login, SSH with key, sudo NOPASSWD |
| `root` | SSH with key (`--root` flag) |

SSH key: `~/.debsb/id_ed25519` (auto-generated on first build)

## License

GPL-2.0-only
