git.iko.soy/vibebox
on fa22141 help sign in
vibebox/docs/implementations.md
100 lines 3.3 kB history raw
1# Implementations
3## Definitions
5### Vibebox Command
7Commands for vibebox, the format is `:<command>`
9### Box Command
11Commands for general vm spawned by the vibebox, a typical linux command,
12the format is as same as the linux, `<command>`
14### Data Storage
16Global session index is stored in `~/.vibebox/sessions.toml`.
18Global images are stored in `~/.vibebox/images`.
20Project config is stored in `[project_dir]/vibebox.toml`, this should be committed to VCS.
22Project cache should be stored in `[project_dir]/.vibebox/`.
24### Session management
26Each session represents an underlying VM instance, users can quit, enter, spawn a session.
28A session is represented by a UUID（RFC 4122 variant），and it is UUIDv7.
30Example:
32`019bf290-cccc-7c23-ba1d-dce7e6d40693`
34Each session has the following members:
36- `id`: session id
37- `directory`: project directory (absolute), if directory changes name, this should also change.
38- `last_active`: utc time indicating the last active time for the session
40Sessions info are stored in `~/.vibebox/sessions.toml`
42A session can be shut down, resumed, deleted, created.
44A session links to a directory. Currently, a directory can only have a single session; a session can be connected to
45multiple vibeboxes.
47Instance data are stored in `project_dir/.vibebox`.
49Deleting `[project_dir]/.vibebox/` permanently deletes the session. The global index entry (if any) will be removed by
50any command that uses the global index but failed to locate.
52There is a reference count for each session, and this represents the number of `vibebox` using that session.
54A session (VM) will only shut down after `AUTO_SHUTDOWN_GRACE_MS` milliseconds if the reference count is 0. Shutting a
55session down can save some resources, but the first startup time will be larger than resuming an active session.
57When a session shuts down, the VM stops, but the instance disk in project_dir/.vibebox/ is preserved for faster
58later boots.
60#### Behavior
62In host cli:
64- use `vibebox` without config to connect to an exising session, or create a new one if not existed.
65- use `vibebox delete <session_id>` to delete an existed session, delete <session_id> removes
66 `[session.directory]/.vibebox/` and deletes the global index entry.
67- use `vibebox list` to list a list of sessions
69In vibebox:
71- use `:exit` to exit vibebox.
73### (Shows all the mounts/network/visibility)
75Each session has mounts, meaning it has a file system mapping from host to the inner VM, this has a default value, and
76users can add new mounts to it.
78Each session also has its own network mapping, users can choose to use blocklist or allowlist mode to control the
79traffic by hostname/domain.
81The command can display the mapping and network strategy.
83They are also stored per project, in `vibebox.toml`
85#### Behaviors
87- use `:explain` to display:
88 - mounts: host_path → guest_path, ro/rw
89 - network: mode (allowlist/blocklist) and entries
90 - storage: paths to vibebox.toml and .vibebox/ (relative from the project_dir)
92## Connection
94### SSH
96- In Project cache, generate and store ssh pair
97- In provisioning, install and enable openssh-server in VM
98- Mount ssh pair to VM when starting up
99- get ipv4 address of VM, store it to project cache
100- and connect to VM via ssh with ip and ssh key