feat: first commit

docs/implementations.md

@@ -0,0 +1,91 @@
+# Implementations
+
+## Definitions
+
+### Vibebox Command
+
+Commands for vibebox, the format is `:<command>`
+
+### Box Command
+
+Commands for general vm spawned by the vibebox, a typical linux command,
+the format is as same as the linux, `<command>`
+
+### Data Storage
+
+Global session index is stored in `~/.vibebox/sessions.toml`.
+
+Global images are stored in `~/.vibebox/images`.
+
+Project config is stored in `[project_dir]/vibebox.toml`, this should be committed to VCS.
+
+Project cache should be stored in `[project_dir]/.vibebox/`.
+
+### Session management
+
+Each session represents an underlying VM instance, users can quit, enter, spawn a session.
+
+A session is represented by a UUID（RFC 4122 variant），and it is UUIDv7.
+
+Example:
+
+`019bf290-cccc-7c23-ba1d-dce7e6d40693`
+
+Each session has the following members:
+
+- `id`: session id
+- `directory`: project directory (absolute)
+- `last_active`: utc time indicating the last active time for the session
+
+Sessions info are stored in `~/.vibebox/sessions.toml`
+
+A session can be shut down, resumed, deleted, created.
+
+A session links to a directory. Currently, a directory can only have a single session; a session can be connected to
+multiple vibeboxes.
+
+Instance data are stored in `project_dir/.vibebox`.
+
+Deleting `[project_dir]/.vibebox/` permanently deletes the session. The global index entry (if any) will be removed by
+any command that uses the global index but failed to locate.
+
+There is a reference count for each session, and this represents the number of `vibebox` using that session.
+
+A session (VM) will only shut down after `AUTO_SHUTDOWN_GRACE_MS` milliseconds if the reference count is 0. Shutting a
+session down can save some resources, but the first startup time will be larger than resuming an active session.
+
+When a session shuts down, the VM stops, but the instance disk in project_dir/.vibebox/ is preserved for faster
+later boots.
+
+#### Behavior
+
+In host cli:
+
+- use `vibebox` without config to connect to an exising session, or create a new one if not existed.
+- use `vibebox delete <session_id>` to delete an existed session, delete <session_id> removes
+  `[session.directory]/.vibebox/` and deletes the global index entry.
+- use `vibebox list` to list a list of sessions
+
+In vibebox:
+
+- use `:new` to prompt user to delete and create a session.
+- use `:exit` to exit vibebox.
+
+### (Shows all the mounts/network/visibility)
+
+Each session has mounts, meaning it has a file system mapping from host to the inner VM, this has a default value, and
+users can add new mounts to it.
+
+Each session also has its own network mapping, users can choose to use blocklist or allowlist mode to control the
+traffic by hostname/domain.
+
+The command can display the mapping and network strategy.
+
+They are also stored per project, in `vibebox.toml`
+
+#### Behaviors
+
+- use `:explain` to display:
+    - mounts: host_path → guest_path, ro/rw
+    - network: mode (allowlist/blocklist) and entries
+    - storage: paths to vibebox.toml and .vibebox/ (relative from the project_dir)

docs/new_features.md

@@ -0,0 +1,22 @@
+# New Features
+
+## Priority 1
+
+### Session management
+
+1. each session is a folder
+2. by default, there should be a reference count for each vm, if count is 0, shutdown in DEFAULT_EXPECT_TIMEOUT.
+3. You can also use command inside a session to never allow it to auto shutdown
+4. you can use commands to resume a session
+
+### explain (Shows all the mounts/network/visibility)
+
+1. you can display all the mounts & network activity.
+2. you can set disable to disable a network connection.
+3. use a config file in .vibebox/config.toml to config it
+
+## Priority 2
+
+### Port Forwarding
+
+1. Port will be auto forwarded to the host

docs/old_features.md

@@ -0,0 +1,47 @@
+# Existing Features (Legacy Snapshot)
+
+This document summarizes the currently implemented features in the repo at the time of review.
+
+## Core Purpose
+- Single-binary CLI to spin up a Linux VM on Apple Silicon macOS for sandboxing LLM agents.
+- Uses Apple Virtualization framework with a lightweight Debian nocloud image.
+
+## VM Lifecycle
+- Downloads a Debian base image on first run and verifies SHA-512 before use.
+- Decompresses the base image and provisions it once, saving as a default template.
+- Creates a per-project instance disk at `.vibe/instance.raw` on first run.
+- Instance disks persist across runs until manually deleted.
+
+## Default Sharing and Mounts
+- Automatically shares the current project directory into the VM.
+- Shares common cache/config directories when present:
+- `~/.m2`, `~/.cargo/registry`, `~/.codex`, `~/.claude`.
+- Maintains a dedicated guest mise cache at `~/.cache/vibe/.guest-mise-cache` on the host.
+- Supports disabling default mounts with `--no-default-mounts`.
+- Supports explicit mounts via `--mount host:guest[:read-only|:read-write]`.
+
+## CLI Options and Automation
+- `--cpus` and `--ram` to configure virtual CPU count and memory size.
+- `--script` to upload and run a shell script inside the VM.
+- `--send` to type a command into the VM console.
+- `--expect` to wait for console output before continuing with script or send actions.
+- Optional disk image argument to boot an existing raw disk directly.
+
+## Console and Login Experience
+- Auto-login as root by waiting for login prompt.
+- Mounts shared directories using virtiofs, then bind-mounts to target paths.
+- Prints a startup MOTD showing host and guest mount mappings.
+- Streams VM console to the terminal with raw mode for interactive use.
+
+## Security and Signing
+- Checks for `com.apple.security.virtualization` entitlement on startup.
+- Self-signs the binary with the required entitlement if missing, then re-execs.
+
+## Networking and Devices
+- NAT networking enabled by default.
+- Virtio block device for storage and virtio entropy device for randomness.
+- Serial console plumbing between host and guest for I/O.
+
+## Platform Assumptions
+- ARM-based macOS (Ventura or newer) is required.
+- First run requires network access to fetch the base image.