mirror of
https://github.com/robcholz/vibebox.git
synced 2026-04-01 00:10:15 +02:00
91 lines
3.0 KiB
Markdown
91 lines
3.0 KiB
Markdown
# 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) |