NOISSUE - Add cvm management docs #28

WashingtonKK · 2025-12-22T05:05:39Z

What type of PR is this?

What does this do?

Which issue(s) does this PR fix/relate to?

Have you included tests for your changes?

Did you document any new/modified features?

Notes

SammyOina

include screenshots of buildroot configuration for HAL image, also this guide needs to state it is for HAL and keep it separate from public cloud/cloud init which should be documented as well

SammyOina

please go through your changes

SammyOina · 2025-12-23T16:19:23Z

docs/developer-guide/hal.md

+Clone the Cube HAL repository and its Buildroot submodule:
+
+```bash
+git clone https://github.com/ultravioletrs/cube-hal.git


no such repo exists

SammyOina · 2025-12-23T16:19:36Z

docs/developer-guide/hal.md

+```bash
+git clone https://github.com/ultravioletrs/cube-hal.git
+cd cube-hal
+git submodule update --init --recursive


we don't have submodules

Signed-off-by: WashingtonKK <washingtonkigan@gmail.com>

SammyOina

please go through the chnages and verify accuracy of the info

SammyOina · 2026-01-13T12:18:30Z

docs/developer-guide/cvm-management.md

+
+## Managing Confidential VMs
+
+This guide explains how to start, monitor, and manage Confidential Virtual Machines (CVMs) for Cube AI using the Hardware Abstraction Layer (HAL) with Buildroot-based images and the provided management scripts. It is written as a practical, step-by-step reference so you can move from initial launch to ongoing operations without having to infer script behavior.


if this is HAL only we'll need a section for cloud init

SammyOina · 2026-01-13T12:19:07Z

docs/developer-guide/cvm-management.md

+This guide explains how to start, monitor, and manage Confidential Virtual Machines (CVMs) for Cube AI using the Hardware Abstraction Layer (HAL) with Buildroot-based images and the provided management scripts. It is written as a practical, step-by-step reference so you can move from initial launch to ongoing operations without having to infer script behavior.
+
+:::info
+This guide is specifically for HAL-based CVM deployments using Buildroot images. It assumes you are running the HAL tooling locally and that your VM images follow the Buildroot layout. For public cloud deployments using cloud-init, please refer to the separate cloud deployment documentation instead.


HAL tooling? what does that mean

SammyOina · 2026-01-13T13:15:32Z

docs/developer-guide/cvm-management.md

+- 6190 → 22 (SSH)
+- 6191 → 80 (HTTP)
+- 6192 → 443 (HTTPS)
+- 6193 → 7001 (Cube Agent)
+- 6194 → 11434 (Ollama)
+- 6195 → 8000 (vLLM)


only forwarded port to cvm should be agent and ssh, remove all others make sure this reflects in the cube repo as well

SammyOina · 2026-01-13T13:20:00Z

docs/developer-guide/cvm-management.md

+
+### Certificate Management
+
+Certificates are embedded in the filesystem image at build time. This means certificate rotation happens by rebuilding the image, not by editing a running VM.


we can rotate certs by ssh into the cvm and restart services

SammyOina · 2026-01-13T13:23:21Z

docs/developer-guide/hal.md

+Load the Cocos HAL configuration using the BR2_EXTERNAL mechanism:
+
+```bash
+make BR2_EXTERNAL=../cocos/hal/linux cocos_defconfig


SammyOina · 2026-01-13T13:24:49Z

docs/developer-guide/hal.md

+- **Server CA Certificates File** - Path to CA certificate file (default: `/etc/cube/certs/ca.pem`)
+- **Server Certificate File** - Path to server certificate (default: `/etc/cube/certs/server.crt`)
+- **Server Key File** - Path to server private key (default: `/etc/cube/certs/server.key`)
+- **Client CA Certificates File** - Path to client CA certificates (default: `/etc/cube/certs/client_ca.pem`)


this is not env, it is actual file uploaded to build

SammyOina · 2026-01-13T13:25:38Z

docs/developer-guide/hal.md

+**Ollama Configuration:**
+
+- **ollama** - Ollama package dependency (automatically required when selected as LLM backend)
+- **Install default models** - Pre-install common models during build


we have specific ones, should be listed

SammyOina · 2026-01-13T13:26:04Z

docs/developer-guide/hal.md

+
+**Important Notes:**
+
+- If **Agent CA URL** is configured, the agent will fetch certificates from the CA at runtime using the **Certs Token** for authentication


reference which CA we actually use

Signed-off-by: WashingtonKK <washingtonkigan@gmail.com>

SammyOina · 2026-01-16T08:59:56Z

docs/developer-guide/cvm-management.md

+
+## Managing Confidential VMs
+
+This guide explains how to start, monitor, and manage Confidential Virtual Machines (CVMs) for Cube AI using the Hardware Abstraction Layer (HAL) with Buildroot-based images and the provided management scripts. It is written as a practical, step-by-step reference so you can move from initial launch to ongoing operations without having to infer script behavior.


Suggested change

This guide explains how to start, monitor, and manage Confidential Virtual Machines (CVMs) for Cube AI using the Hardware Abstraction Layer (HAL) with Buildroot-based images and the provided management scripts. It is written as a practical, step-by-step reference so you can move from initial launch to ongoing operations without having to infer script behavior.

This guide explains how to start, monitor, and manage Confidential Virtual Machines (CVMs) for Cube AI using the Hardware Abstraction Layer (HAL) with Buildroot-based images and the provided management scripts.

SammyOina · 2026-01-16T09:01:34Z

docs/developer-guide/cvm-management.md

+For AMD Secure Encrypted Virtualization, use the SEV-SNP launch path. This mode enables hardware-backed memory protection for the guest.
+
+```bash
+./qemu.sh start_cvm


if the other is start_tdx this should be start_sev or start_snp, but auto detect would be be better. make the change in cube as well

SammyOina · 2026-01-16T09:31:11Z

docs/developer-guide/cvm-management.md

+Monitor the CVM interactively. Ctrl+C stops monitoring but leaves the CVM running, which makes this mode convenient for temporary observation.
+
+```bash
+./cvm-monitor.sh daemon


-d flag would be better

SammyOina · 2026-01-16T09:32:41Z

docs/developer-guide/cvm-management.md

+Production mode - monitor runs detached in background. Use this when you want the monitor to persist across terminal sessions.
+
+```bash
+./cvm-monitor.sh background


daemon is a process that runs in the background, so this clashes with the previous section, daemon should be a flag (set or not set) reflect on cube

SammyOina · 2026-01-16T09:33:32Z

docs/developer-guide/cvm-management.md

+ssh -p 6190 user@localhost
+
+# Access Ollama API
+curl http://localhost:6194/api/tags


ollama should not be exposed through port forwarding, fix in cube too

SammyOina · 2026-01-16T09:34:52Z

docs/developer-guide/hal.md

+Load the Cube HAL configuration using the BR2_EXTERNAL mechanism:
+
+```bash
+make BR2_EXTERNAL=../cube/hal/linux cube_defconfig


cube does not have such a file path, please review the changes and test

SammyOina · 2026-01-16T09:35:31Z

docs/developer-guide/hal.md

+### 5. Boot Inside an SEV-SNP CVM
+
+Use the provided scripts to launch a CVM with your HAL image:
+
+```bash
+# For AMD SEV-SNP
+./qemu.sh start_cvm
+
+# For Intel TDX
+./qemu.sh start_tdx
+```


duplicate of the other doc, make references instead

SammyOina · 2026-01-16T09:35:45Z

docs/developer-guide/hal.md

+# SSH into the CVM
+ssh -p 6190 root@localhost
+
+# Check Cube Agent status
+systemctl status cube-agent
+
+# Verify Ollama is running
+curl http://localhost:11434/api/tags


Signed-off-by: WashingtonKK <washingtonkigan@gmail.com>

SammyOina requested changes Dec 22, 2025

View reviewed changes

SammyOina requested changes Dec 23, 2025

View reviewed changes

WashingtonKK added 5 commits January 13, 2026 12:28

NOISSUE - Add cvm management docs

93f0221

Signed-off-by: WashingtonKK <washingtonkigan@gmail.com>

lint docs

d8bb6cd

Signed-off-by: WashingtonKK <washingtonkigan@gmail.com>

update docs

32f8be9

Signed-off-by: WashingtonKK <washingtonkigan@gmail.com>

update docs

4dad14b

Signed-off-by: WashingtonKK <washingtonkigan@gmail.com>

enhance cvm management docs

52cc7af

Signed-off-by: WashingtonKK <washingtonkigan@gmail.com>

WashingtonKK force-pushed the cube-cvm branch from df0af1b to 52cc7af Compare January 13, 2026 09:28

SammyOina requested changes Jan 13, 2026

View reviewed changes

WashingtonKK added 3 commits January 14, 2026 10:45

update docs

bf38107

Signed-off-by: WashingtonKK <washingtonkigan@gmail.com>

update docs

0012812

Signed-off-by: WashingtonKK <washingtonkigan@gmail.com>

fix lint

ab0f653

Signed-off-by: WashingtonKK <washingtonkigan@gmail.com>

SammyOina requested changes Jan 16, 2026

View reviewed changes

WashingtonKK added 3 commits January 19, 2026 15:34

update docs

c6a0a2c

Signed-off-by: WashingtonKK <washingtonkigan@gmail.com>

address PR review comments

4f7ccf7

Signed-off-by: WashingtonKK <washingtonkigan@gmail.com>

fix ci

325a677

Signed-off-by: WashingtonKK <washingtonkigan@gmail.com>

SammyOina assigned WashingtonKK Jan 19, 2026

SammyOina approved these changes Jan 21, 2026

View reviewed changes


		## Managing Confidential VMs

		This guide explains how to start, monitor, and manage Confidential Virtual Machines (CVMs) for Cube AI using the Hardware Abstraction Layer (HAL) with Buildroot-based images and the provided management scripts. It is written as a practical, step-by-step reference so you can move from initial launch to ongoing operations without having to infer script behavior.


		### Certificate Management

		Certificates are embedded in the filesystem image at build time. This means certificate rotation happens by rebuilding the image, not by editing a running VM.


		Important Notes:

		- If Agent CA URL is configured, the agent will fetch certificates from the CA at runtime using the Certs Token for authentication

NOISSUE - Add cvm management docs #28

Are you sure you want to change the base?

NOISSUE - Add cvm management docs #28

Uh oh!

Conversation

WashingtonKK commented Dec 22, 2025

What type of PR is this?

What does this do?

Which issue(s) does this PR fix/relate to?

Have you included tests for your changes?

Did you document any new/modified features?

Notes

Uh oh!

SammyOina left a comment

Choose a reason for hiding this comment

Uh oh!

SammyOina left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SammyOina left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants