NOISSUE - Improve ReadMe Documentation - #588
Closed
Musilah wants to merge 2 commits into
Closed
Conversation
Signed-off-by: Musilah <nataleigh.nk@gmail.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #588 +/- ##
==========================================
+ Coverage 68.36% 68.40% +0.04%
==========================================
Files 116 116
Lines 7344 7344
==========================================
+ Hits 5021 5024 +3
+ Misses 1746 1743 -3
Partials 577 577 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
@SammyOina please review this one |
SammyOina
requested changes
Apr 20, 2026
Signed-off-by: Musilah <nataleigh.nk@gmail.com>
SammyOina
requested changes
Apr 28, 2026
|
|
||
| ### Prerequisites | ||
|
|
||
| - Go 1.22+ |
| ./build/cocos-manager | ||
| ``` | ||
|
|
||
| **Agent** is built into the [EOS](https://github.com/ultravioletrs/eos)-based HAL and starts automatically inside the CVM. |
Contributor
There was a problem hiding this comment.
eos repo is out of date point instead to hal/linux in this repo
Contributor
There was a problem hiding this comment.
Pull request overview
This PR is a documentation refresh across the repository’s README files. It aims to give contributors and operators a clearer top-level overview plus per-component setup, configuration, API, and usage guidance for the core binaries and in-CVM supporting services.
Changes:
- Reworks the top-level README with architecture, features, quick start, and documentation links.
- Expands existing Manager, Agent, CLI, and HAL READMEs with more structured configuration and usage sections.
- Adds new README files for supporting services such as attestation-service, computation-runner, ingress/egress proxy, and log-forwarder.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 25 comments.
Show a summary per file
| File | Description |
|---|---|
README.md |
Rewrites the project overview, architecture, prerequisites, and quick start. |
manager/README.md |
Expands Manager configuration, setup, API, deployment, and troubleshooting docs. |
hal/linux/README.md |
Adds HAL Linux purpose, build, and output instructions. |
hal/cloud/README.md |
Documents cloud-init layout, environment variables, running, and debugging. |
cmd/log-forwarder/README.md |
Adds usage and configuration docs for the log forwarder service. |
cmd/ingress-proxy/README.md |
Adds overview and usage docs for inbound CVM proxying. |
cmd/egress-proxy/README.md |
Adds overview and usage docs for outbound CVM proxying. |
cmd/computation-runner/README.md |
Adds overview, config, deployment, and example flow for workload execution. |
cmd/attestation-service/README.md |
Adds overview, config, deployment, and RPC usage docs for attestation. |
cli/README.md |
Reorganizes CLI command documentation and examples. |
agent/README.md |
Expands Agent configuration, API, deployment, and example usage docs. |
Comments suppressed due to low confidence (2)
hal/cloud/README.md:167
- These filenames do not match the systemd unit written by
config.yaml, which logs to/var/log/cocos/agent.stdoutand/var/log/cocos/agent.stderrwithout the.logsuffix. Readers following these commands will tail files that never exist.
### View file-based logs
```bash
cat /var/log/cocos/agent.stdout.log
cat /var/log/cocos/agent.stderr.log
manager/README.md:334
- This SEV-SNP example uses unsupported env names:
MANAGER_GRPC_URLis not parsed by the manager, and the C-bit override isMANAGER_QEMU_SEV_SNP_CBIT_POSin code. Copy-pasting this snippet will not apply the intended configuration.
MANAGER_GRPC_URL=localhost:7001 \
MANAGER_LOG_LEVEL=debug \
MANAGER_QEMU_ENABLE_SEV_SNP=true \
MANAGER_QEMU_SEV_SNP_CBITPOS=51 \
MANAGER_QEMU_BIN_PATH=<path to QEMU binary> \
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ### Prerequisites | ||
|
|
||
| - Go 1.22+ |
|
|
||
| | Variable | Description | Default | | ||
| | --- | --- | --- | | ||
| | `MANAGER_QEMU_OVMF_VERSION` | EDKII version from which OVMF was built | `edk2-stable202408` | |
| | --- | --- | --- | | ||
| | `MANAGER_QEMU_ENABLE_SEV_SNP` | Enable AMD Secure Nested Paging (SEV-SNP) | `true` | | ||
| | `MANAGER_QEMU_SEV_SNP_ID` | SEV-SNP device ID | `sev0` | | ||
| | `MANAGER_QEMU_SEV_SNP_CBITPOS` | C-bit position in the physical address | `51` | |
Comment on lines
+292
to
+294
| | `Run` | Submit a computation to be executed on a new CVM; streams back computation events | | ||
| | `CreateVM` | Provision a CVM with a given configuration (algorithm, datasets, policy) | | ||
| | `StopVM` | Terminate a running CVM | |
Comment on lines
+300
to
+301
| | `GET` | `/version` | Returns the running Manager version | | ||
| | `GET` | `/health` | Health check endpoint | |
|
|
||
| ### `checksum` — Compute File Checksum | ||
|
|
||
| Computation manifests require SHA-256 checksums for the algorithm and each dataset. |
| | `Agent` | `Data` | Upload an encrypted dataset | | ||
| | `Agent` | `Result` | Download the encrypted computation result | | ||
| | `Agent` | `Attestation` | Retrieve a hardware attestation report | | ||
| | `Agent` | `State` | Query the current computation state machine status | |
|
|
||
| | Variable | Description | Default | | ||
| | --- | --- | --- | | ||
| | `COCOS_AGENT_VERSION` | Cocos Agent release to install | `v0.3.1` | |
Comment on lines
+45
to
+50
| Other in-CVM services connect to the socket via gRPC. The `attestation-service` proto exposes two RPC methods: | ||
|
|
||
| | Method | Description | | ||
| | --- | --- | | ||
| | `FetchAttestation` | Request a hardware attestation report wrapped in an EAT token | | ||
| | `GetAzureToken` | Request an Azure MAA attestation token | |
Comment on lines
+40
to
+44
| # Run (inside a CVM) | ||
| ./build/cocos-ingress-proxy | ||
| ``` | ||
|
|
||
| To override the backend: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What type of PR is this?
This is a documentation update because it updates the following documentation: ReadMe.md files
What does this do?
It improves the styling and flow of readmes as well as update them to match the current repo state.
Which issue(s) does this PR fix/relate to?
N/A
Have you included tests for your changes?
Did you document any new/modified feature?
Notes