kstyagi/nest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: introduce Nest workspace for local Firecracker management

Browse Source 
- Added a new server module for the Nest workspace, integrating with UVM's API.
- Updated project description to reflect the new Nest functionality.
- Created tests for the Nest server and CLI, ensuring proper functionality and error handling.
- Refactored existing UVM server code to separate Nest and UVM functionalities.
- Removed the old UVM dashboard assets package as it is now part of the Nest workspace.
- Enhanced error messages for clarity regarding server shutdown commands.
This commit is contained in:
kstyagi
2026-09-25 13:45:57 +05:30
parent 660ba9efee
commit dca7f78dae
22 changed files with 456 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+41 -26
View File
@@ -1,13 +1,17 @@
# uvm
# Nest
`uvm` is a small, local Firecracker microVM command-line manager for Ubuntu.
It creates one Firecracker process per VM, attaches it to a host TAP device,
Nest is a local infrastructure workspace with a browser dashboard for your
machines, network, and host health. Launch it with `nest --serve`.
Its `uvm` component is a small, local Firecracker microVM manager for Ubuntu.
UVM creates one Firecracker process per VM, attaches it to a host TAP device,
and keeps a private disk and local registry for named VMs. The CLI supports
create, start, stop, restart, resize, delete, inspection, SSH, logs, diagnostics,
host-shared IPv4 internet access, and enforced private-IPv4 TCP port allowlists.
This directory is a self-contained project. All UVM code, tests, packaging
metadata, launcher scripts, and documentation live here.
This directory is a self-contained project. Nest owns the dashboard and
workspace server; UVM provides the machine-management CLI and backend services.
All code, tests, packaging metadata, launchers, and documentation live here.
For architecture, lifecycle invariants, extension guidance, and contributor
workflows, see [DEVELOPER.md](DEVELOPER.md).
@@ -24,11 +28,13 @@ feature contract; these guides describe the implementation in the workspace.
Run commands from this project root:
```sh
./nest.py --help
python3 -B -m nest --help
./uvm.py --help
python3 -B -m uvm --help
```
The `pyproject.toml` file also defines an installable `uvm` console command.
The `pyproject.toml` file defines installable `nest` and `uvm` console commands.
The project is an application, not a reusable Python SDK.
## Requirements
@@ -271,7 +277,7 @@ DNS publication, reverse proxies, or guest-service TLS. UDP and IPv6 service pol
yet supported. Guest-initiated IPv4 TCP/UDP egress, its replies, and required
ARP/ICMP traffic remain allowed; managed TAPs block IPv6.
## Management API
## Nest Dashboard and Management API
Install the project dependencies before serving the API:
@@ -279,28 +285,33 @@ Install the project dependencies before serving the API:
python3 -m pip install .
```
Launch the FastAPI management server using the environment where the project
Launch the Nest workspace server using the environment where the project
dependencies were installed (use the full console-script path if needed):
```sh
export UVM_API_TOKEN='replace-with-a-long-random-secret'
sudo env UVM_API_TOKEN="$UVM_API_TOKEN" \
uvm --serve --host 127.0.0.1 --port 8000
nest --serve --host 127.0.0.1 --port 8000
# Equivalent when running the source checkout directly.
sudo env UVM_API_TOKEN="$UVM_API_TOKEN" \
./uvm.py --serve --host 127.0.0.1 --port 8000
./nest.py --serve --host 127.0.0.1 --port 8000
```
The default bind address is `127.0.0.1` and the default port is `8000`.
OpenAPI documentation is available at `/docs` once the server is running. The
root URL redirects to the local dashboard at `/dashboard`; enter the API token
root URL redirects to the Nest dashboard at `/dashboard`; enter the API token
there for the current browser session.
The dashboard includes a fleet overview, searchable machine collection, private
network and port-policy view, host diagnostics, and machine provisioning. Open a
machine to manage its lifecycle, edit or sync its port rules, copy its SSH command,
or read recent logs. Select machines in the collection for bulk operations.
Nest serves the dashboard and UVM-backed management endpoints together, using
the existing `UVM_API_TOKEN` and `UVM_*` host configuration. The standalone UVM
API is available through `uvm --serve`, with its reference at `/docs`; the `/`
and `/dashboard` routes belong to the Nest server.
The Nest dashboard includes a fleet overview, searchable machine collection,
private network and port-policy view, host diagnostics, and machine provisioning.
Open a machine to manage its lifecycle, edit or sync its port rules, copy its SSH
command, or read recent logs. Select machines in the collection for bulk operations.
Use `Ctrl+K` / `⌘K` (or `/`) to find a machine or page. Fleet data refreshes every
five seconds while the tab is visible; host checks refresh every thirty seconds
and can also be run manually. Charts show observed machine states and allocated
@@ -311,10 +322,10 @@ The server exposes these routes:
| Method | Route | Purpose |
|---|---|---|
| `GET` | `/` | Redirect to the local dashboard |
| `GET` | `/dashboard` | Serve the local management dashboard |
| `GET` | `/` | Redirect to the dashboard (Nest server) |
| `GET` | `/dashboard` | Serve the Nest workspace dashboard (Nest server) |
| `GET` | `/health` | Unauthenticated liveness response |
| `POST` | `/exit` | Gracefully stop the UVM API server |
| `POST` | `/exit` | Gracefully stop the management server |
| `GET` | `/diagnostics` | Run host readiness checks for the dashboard/system view |
| `POST` | `/install` | Install or refresh host assets; body: `{ "force": false }` |
| `GET` | `/vms` | List VM records and observed status |
@@ -365,7 +376,7 @@ sudo env \
UVM_API_TOKEN="$UVM_API_TOKEN" \
UVM_API_TLS_CERT="$UVM_API_TLS_CERT" \
UVM_API_TLS_KEY="$UVM_API_TLS_KEY" \
./uvm.py --serve --host 0.0.0.0 --port 8000
./nest.py --serve --host 0.0.0.0 --port 8000
```
Send the token on management requests:
@@ -385,8 +396,8 @@ curl -X POST \
```
The endpoint returns `202 {"status":"stopping"}` and then gracefully terminates
the UVM API process. It is a protected management endpoint; it does not stop or
delete managed VMs.
the serving Nest or UVM process. It is a protected management endpoint; it does
not stop or delete managed VMs.
Do not expose this server directly to an untrusted network. For remote access,
keep TLS enabled and consider placing it behind an additional authenticated
@@ -570,7 +581,7 @@ Host and API settings can be overridden through environment variables:
| `UVM_ROOTFS_SHA256` | Trusted prebuilt rootfs SHA-256; use with `UVM_ROOTFS_URL` |
| `UVM_FIRECRACKER_BINARY_SHA256` | Optional trusted local Firecracker binary SHA-256 |
| `UVM_ALLOW_UNVERIFIED_DOWNLOADS` | Set to `1` only for unverified local development |
| `UVM_API_TOKEN` | Required for every API server; sent as `X-UVM-Token` |
| `UVM_API_TOKEN` | Required for Nest and standalone UVM servers; sent as `X-UVM-Token` |
| `UVM_API_TLS_CERT` | TLS certificate path required for a non-loopback API bind |
| `UVM_API_TLS_KEY` | TLS private-key path required for a non-loopback API bind |
@@ -584,14 +595,18 @@ Selected files:
├── USAGE.md
├── DEVELOPER.md
├── pyproject.toml
├── uvm.py # Executable compatibility launcher
├── uvm/ # Private application implementation
├── nest.py # Executable Nest workspace launcher
├── nest/ # Nest workspace application
│ ├── cli.py # nest --serve entry point
│ ├── server.py # Workspace server, composing the UVM management API
│ └── dashboard/ # Nest document route and local HTML, CSS, JS, and fonts
├── uvm.py # Executable UVM compatibility launcher
├── uvm/ # Machine-management implementation
│ ├── cli.py # argparse, terminal output, SSH execution
│ ├── lifecycle.py # Lifecycle, bulk operations, recovery, port-policy intent
│ ├── network.py # IP/MAC/TAP/bridge/NAT management
│ ├── firewall.py # Owned nftables bridge policies and offline conntrack cleanup
│ ├── dashboard/ # Local dashboard HTML, CSS, and JavaScript
│ ├── routers/ # FastAPI routes, including the dashboard document
│ ├── routers/ # UVM management API routes
│ └── firecracker/ # Firecracker config, API, and process adapters
└── tests/ # Unit tests and opt-in isolated namespace packet tests
```