> ## Documentation Index
> Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL.
> Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other.
> Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking.
> Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify.

# VComLink: Async Communication Between EVE-OS and VMs

> Overview of VComLink, the EVE-OS communication framework that lets virtual machines access curated host services (such as TPM operations) over a secure vsock channel.

## Introduction

VComLink is a lightweight communication service built into EVE-OS that lets virtual machines access specific host-level services over a secure, kernel-mediated channel. Rather than exposing the full hardware TPM to guest VMs (as the [EVE-OS Virtual TPM](https://zededa.mintlify.site/new-ui/infrastructure-services/virtual-machines-on-eve-os/eve-os-virtual-tpm.md) feature does), VComLink relays only specific, well-defined operations that a VM is permitted to invoke.

The first available service is the TPM channel, which lets VMs delegate cryptographic operations to the hardware TPM on the EVE-OS host. Additional service channels are under development.

## Prerequisites

* EVE-OS 14.5.0-LTS or later.
* A KVM-based EVE-OS image.

## How It Works

VComLink runs as a daemon on the EVE-OS host and is automatically exposed to all virtual machines through the virtio socket (vsock) interface on port 2000. No network setup or additional configuration is required.

When a VM sends a request, VComLink routes it to the appropriate service handler based on the target channel specified in the message. Each request and response pair is handled independently, which simplifies concurrency and improves reliability.

Communication between the VM and VComLink stays within the host kernel space, avoiding the overhead and exposure of traditional TCP/IP networking.

![VComLink communication framework diagram showing message routing between VMs and EVE-OS host services over vsock.](https://mintcdn.com/zededa/nH470gZ2VKSQBZu8/new-ui/infrastructure-services/virtual-machines-on-eve-os/images/VComLink_framework.png?fit=max\&auto=format\&n=nH470gZ2VKSQBZu8\&q=85\&s=2e0bc8c43196aa0797761fa127111a96)

## Key Features

| Feature | Description |
| - | - |
| Multi-channel architecture | Supports multiple independent service channels, each mapped to a specific host function. |
| Asynchronous, transaction-based communication | Each request and response pair is handled independently, with no persistent session state required. |
| Kernel-mediated transport (vsock) | Uses HTTP over vsock for direct, low-overhead communication between the VM guest and the EVE-OS host. |
| No configuration required | VComLink is available automatically to all VMs on the node. |

## Available Channels

### TPM service channel

The TPM channel lets VMs invoke cryptographic operations on the hardware TPM hosted by EVE-OS. All communication uses Protocol Buffers (protobuf) to define request and response message structures.

Example operations available through the TPM channel:

* Retrieving a TPM-stored public key.
* Signing data with a hardware-backed key.
* Performing remote attestation via credential activation.
* Reading non-volatile TPM memory.
* Certifying a TPM key for integrity validation.

## Using VComLink in Applications

VComLink is designed for application developers building workloads that need access to host TPM capabilities from inside a VM. Because communication uses protobuf over HTTP on vsock, you can implement a client in any language that supports protobuf and vsock socket connections.

To get started:

1. Review the VComLink `.proto` API definition files in the [EVE-OS repository](https://github.com/lf-edge/eve) to understand the message structure for each supported channel.
2. Generate protobuf client stubs in your preferred language. Go and Python bindings are available in the repository.
3. Implement your VM application using the generated stubs to send requests over vsock to port 2000 on the host CID.

### Example: retrieve a TPM public key (Python)

The following Python example sends a `TpmRequestGetPub` message over HTTP on vsock to request the public part of a TPM key from the VComLink TPM service channel.

```python theme={"dark"}
import socket
import messages_pb2
import http.client

VSOCK_CID_HOST = 2
VSOCK_PORT = 2000

class VsockHTTPConnection(http.client.HTTPConnection):
    def connect(self):
        self.sock = socket.socket(socket.AF_VSOCK, socket.SOCK_STREAM)
        self.sock.connect((VSOCK_CID_HOST, VSOCK_PORT))

def main():
    # Create the protobuf request
    request_proto = messages_pb2.TpmRequestGetPub()
    request_proto.index = 0x81010001  # Example TPM index
    request_bytes = request_proto.SerializeToString()

    # Set up connection to vsock host
    conn = VsockHTTPConnection("vsock", VSOCK_PORT)
    conn.request("POST", "/tpm/getpub", body=request_bytes, headers={
        "Content-Type": "application/octet-stream"
    })

    # Get the HTTP response
    resp = conn.getresponse()
    if resp.status != 200:
        raise Exception(f"HTTP error: {resp.status} {resp.reason}")

    # Read and parse the response protobuf
    response_bytes = resp.read()
    response_proto = messages_pb2.TpmResponseGetPub()
    response_proto.ParseFromString(response_bytes)

    # Print result
    print("TPM Public Key Retrieved:")
    print(f"- Public Key (hex): {response_proto.public.hex()}...")
    print(f"- Algorithm: {response_proto.algorithm}")
    print(f"- Attributes (bitmask): {response_proto.attributes:#010x}")

    conn.close()

if __name__ == "__main__":
    main()
```

Sample output:

```text theme={"dark"}
TPM Public Key Retrieved:
- Public Key (hex): 0001000b000300b200208371976... (truncated)
- Algorithm: 1
- Attributes (bitmask): 0x000300b2
```

## VComLink Versus Virtual TPM

| | VComLink | Virtual TPM (vTPM) |
| - | - | - |
| What the VM gets | Curated service relay (specific TPM operations only) | A complete, independent virtual TPM 2.0 device |
| TPM isolation | VM invokes operations on the host HW TPM through VComLink | VM has its own isolated SWTPM instance |
| Configuration required | None | None (enabled by default) |
| Use case | Applications that need specific HW TPM operations on the host | Applications or OS features that require a full, dedicated TPM (for example, Windows 11, BitLocker, Azure IoT) |

## Next Steps

> [card] [EVE-OS Virtual TPM](https://zededa.mintlify.site/new-ui/infrastructure-services/virtual-machines-on-eve-os/eve-os-virtual-tpm.md)
>
> Use vTPM when your VM workload needs a complete, dedicated TPM 2.0 device.

> [card] [Overview of the TPM in EVE-OS](https://zededa.mintlify.site/new-ui/infrastructure-services/eve-os/tpm-overview.md)
>
> Background on how EVE-OS uses the physical TPM for platform security.

> [card] [Deploy an Application Instance](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/deploy-an-application-instance.md)
>
> Deploy a VM workload that uses VComLink.