--- title: Get Started with the VRE framework: Private Cloud Compute Security Guide role: article role_heading: Article path: private-cloud-compute/vresetup --- # Get Started with the VRE Configure your system to run the PCC Virtual Research Environment (VRE). ## Overview Overview The PCC Virtual Research Environment (VRE) requires a Mac with Apple silicon with at least 16 GB of unified memory and macOS Sequoia 15.1 or later. For optimal VRE performance, we recommend using a Mac with at least 24 GB of unified memory. You can access PCC VRE tooling through the pccvre command-line tool, found under /System/Library/SecurityResearch/usr/bin in macOS. The instructions in this document assume your shell’s PATH includes this directory. To add this location to PATH system-wide, you can run: % echo "/System/Library/SecurityResearch/usr/bin" | sudo tee /etc/paths.d/20-vre You can use the pccvre command-line tool to create and manage VRE Virtual Machine (VM) instances; interact with instances to run custom research code; and understand and exercise the overall flow for making inference requests. pccvre and all of its subcommands display documentation when invoked with --help. You can configure shell completions for the pccvre tool by following ArgumentParser’s setup steps. Enable security research Before using the VRE, you will need to configure your Mac to run security research virtual machines. This allows additional access to hardware features, which in turn might expose additional attack surface. To enable research VMs, boot into recoveryOS, open Terminal, and invoke the following command: % csrutil allow-research-guests enable You can validate this configuration from recoveryOS or a booted macOS environment using the following command: % csrutil allow-research-guests status Accept the PCC VRE license agreement After you enable security research on your Mac and boot back into macOS, invoke the pccvre tool as the root user (using sudo) to view and accept the license agreement. important: You can use the Private Cloud Compute Virtual Research Environment and its tooling only for research as outlined in the license agreement. Commercial use is not permitted. You can invoke pccvre license at any time to display and review the license agreement. Initial software assets You can use the pccvre tool to browse and download the assets associated with each PCC software release. The VRE software assets include a demo model with a similar architecture to the Apple server-based Foundation model, scaled down for efficient execution in the VRE. The demo model has received language pre-training but has neither been trained for instruction following nor received any fine-tuning, so it’s expected to operate with unpredictable quality and can perform only text completion. The model also does not have safety features and might return results that are offensive or harmful. Accordingly, the model is provided on an as-is basis. Apple makes no other warranties, express or implied, and disclaims all implied warranties. Manage VRE instances You can create and manage VRE instances using the pccvre instance subcommand. A VRE instance represents a virtual machine along with its associated OS, Cryptexes, and configuration, including: A cryptex that contains the private cloud extensions and PCC cloud applications (PrivateCloudSupport for worker nodes or TrustedProxy for proxy nodes) A cryptex that contains an LLM model A darwin-init configuration that tells the Private Cloud Compute operating system where to fetch the cryptex assets and which software configuration, such as CFPreferences, to apply after boot An HTTP server on the host to vend required assets, such as cryptexes, into the VM Host-side tools to make inference calls to the VRE instance Create an instance To create a new VRE instance, Exploring available releases, then download release assets, then invoke pccvre instance create: % pccvre release download ... Completed download of assets. % pccvre instance create --name --release pccvre instance create instantiates the associated VM, and then restores it with the Private Cloud Compute operating system. The VM then stays in a stopped state. pccvre configures VM instances with the required number of virtual CPUs and memory (paged) according to instance type, and a 64 GB “disk”, which is a sparse file that expands as the VM populates it. Create a workload Starting in macOS 15.5, pccvre implements “workloads” to help manage multiple VRE instances for handling client request flows described in Attested Request Handling. A workload defines the PCC nodes (such as proxy and inference nodes) along with their configuration for handling a PCC request. To create a set of VRE instances using workloads, download the desired release assets and then invoke pccvre workload create to create the instances: % echo ' { "instances": [ { "name": "trustedproxy", "darwinInitOverrides": { "local-host-name": "trustedproxy" }, "release": "" }, { "name": "inferencenode", "darwinInitOverrides": { "local-host-name": "inferencenode" }, "release": "" } ] } ' > vre-configuration.json % pccvre workload create --configuration vre-configuration.json pccvre workload create builds the required set of instances with release values populated from available releases for the specific application types, and modifies the default darwin-init configuration using the provided darwinInitOverrides. List instances To list the installed VRE instances, use the pccvre instance list command: % pccvre instance list name status ecid ipaddr inferencenode running f992fb068cc16088 192.168.64.3 trustedproxy running 69392e43b667aeac 192.168.64.2 Start an instance To start the VRE instances, use pccvre instance start: % pccvre instance start --name trustedproxy --name inferencenode HTTP service started: 192.168.64.1:64593 HTTP service started: 192.168.64.1:64594 Starting VM: trustedproxy (ecid: 69392e43b667aeac) Starting VM: inferencenode (ecid: f992fb068cc16088) Started VM: trustedproxy Started VM: inferencenode ... In addition to starting the instance VMs, instance start also starts the associated local HTTP servers to vend cryptexes to the VRE instances. These HTTP server instances are started by pccvre on the virtual bridge interface exposed to the VM and are not otherwise accessible outside the host. The lifetime of this HTTP server is tied to the lifetime of the instance — so when it stops, pccvre automatically tears down the HTTP server. The shell session where you run pccvre instance start displays the serial console I/O for the virtual machine hosting the instance until the instance stops. Use Ctrl-C to stop the instance. You can use additional shell sessions to run commands and interact with the instance while it is running. Remove an instance To remove a VRE instance, use pccvre instance remove: % pccvre instance remove --name Confirm deleting VRE 'vre' (y/n) y Configure instances The darwin-init binary runs shortly after boot on PCC nodes to fetch and apply a node’s configuration. In the VRE, it consumes a JSON-based configuration that is stored in the VM’s NVRAM and specifies the following: Cryptexes to install on the node Application preferences to set Other system settings, such as logging privacy levels You can use the pccvre instance configure command to inspect and manipulate this configuration. Note that configuration updates take effect only at boot time of the instance. Inspect and modify darwin-init configuration For each release of Private Cloud Compute software, Apple provides a reference darwin-init configuration alongside the artifacts for bootstrapping the VRE. This configuration installs the associated private cloud extensions and demo model cryptexes, and configures the software on the VRE to accept local connections from the Private Cloud Tools. You can inspect the darwin-init configuration using this command: % pccvre instance configure darwin-init dump --name A similar command provides a new darwin-init configuration for an instance: % pccvre instance configure darwin-init set --name -I new_darwin_init.json Configure concurrent multi-app instances You can inspect the darwin-init file to view the list of applications configured to launch. "secure-config": "com.apple.cloudboard.cloudApps" : [ //list of applications which are configured to run ] To interact with a specific application, you need to know the port at which it is exposed. You can find or configure this port by using these fields in the darwin-init configuration: "secure-config": "com.apple.cloudboard.cloudApp..port" : If you don’t specify a port, the ports start from 4442 and increment by one. "secure-config": "com.apple.cloudboard.cloudApps" : [ , ] // No port fields set. // is on port 4442 // is on port 4443 You can also set the port on which the application listens by setting the darwinInitOverrides when you create a workload. % echo ' { "instances": [ { "name": "trustedproxy", "darwinInitOverrides": { "local-host-name": "trustedproxy", "secure-config" : { "com.apple.cloudboard.cloudApp..port" : , "com.apple.cloudboard.cloudApp..port" : } }, "release": "" } ... other instance configs ] } ' > vre-configuration.json % pccvre workload create --configuration vre-configuration.json Enable SSH The production PCC system doesn’t support shell access, but to enable SSH access for the VRE, Apple provides an additional Debug Shell cryptex that contains a shell and debugging tools. The pccvre instance configure ssh command adds this cryptex to the instance and updates the darwin-init configuration with the specified SSH public key: % pccvre instance configure ssh --name -p Note that this command removes darwin-init from the darwin-init configuration to allow SSH and other non-production options. Use pccvre instance list to see the instance’s IP address and then use ssh root@. You can find additional debugging tools installed with the Debug Shell cryptex under /var/DarwinDataCenterSupportImage/. Inspect debug logging You can enable serial logging by restoring Research Variant and setting serial=3 boot-arg using --boot-args argument of pccvre instance create. You can also inspect system-wide log messages from SSH using /var/DarwinDataCenterSupportImage/usr/bin/log provided by Debug Shell cryptex, which is equivalent to macOS log(1). Manage VRE ensembles Starting in macOS 15.5, pccvre can create ensembles and perform Distributed inference. A VRE ensemble consists of two instances connected using a paravirtualized CIO interface implemented with a modified AppleCIOMesh kernel extension, with appropriate ensembled configuration. To create an ensemble, download the desired release assets and then invoke pccvre ensemble create: % pccvre ensemble create --name --release To start the ensemble, use pccvre ensemble start: % pccvre ensemble start --name You can issue ensemble inference requests, list ensembles, and remove them using corresponding pccvre ensemble commands. To configure ensemble instances, use pccvre instance configure.