--- title: Interact with the VRE framework: Private Cloud Compute Security Guide role: article role_heading: Article path: private-cloud-compute/vreinteraction --- # Interact with the VRE Issue requests to and configure the VRE. ## Issue inference requests Issue inference requests The VRE tooling provides a wrapper you can use to submit an inference request to the PCC software running inside the VRE. To issue an inference request, use this command: % pccvre instance inference-request -N --prompt "" Starting with macOS 15.5, pccvre implements additional release-specific inference options when you use recent PCC releases. To explore and use these options, invoke the following commands: % pccvre instance invoke -N --help % pccvre instance invoke -N inference-request --help % pccvre instance invoke -N inference-request --prompt "" Behind the scenes, this command connects to the endpoint published by cloudboardd in the VRE — the same endpoint that the PCC Gateway uses to connect to PCC nodes in production. pccvre uses the underlying CloudBoard and TIE application protocols to submit a request and display the response. For example, you might make an inference request that uses both proxy node and inferencing node, as demonstrated in the Create a workload section of the Get Started with the VRE article, with: % pccvre instance \ invoke --name trustedproxy \ inference-request \ --prompt "" \ -- --tie-proxy trustedproxy.local \ --hostname inferencenode.local When you make this inference request, the inference-request command prints Apple Silicon Node Attestation generated by the VRE instances, and then the tokens as they are streamed back from the VRE, Request execution log entries, and finally the request summary. Use the inference-request command, when you make an inference request, to print: Apple Silicon Node Attestation generated by the VRE instances Tokens as they are streamed back from the VRE Request execution log entries The request summary Executing inference: {"sepAttestation":"MIIFGzCCBKICAQEwggJMohsEGWZlMDEtYjcwNmRhNzVlMzhjZDUyNy1kLTCjRw ... tie_vre_cli.Apple_Cloudml_Inference_Tie_GenerateResponse: next_token_response { token: "**\"" token_padding: "M2Wq8..." } ... tie_vre_cli.Apple_Cloudml_Inference_Tie_GenerateResponse: final_response { ... Exercise prefill-decode disaggregation The VRE provides a mechanism to enable Prefill-decode disaggregation between VRE instances. To enable it, you must run a modified workload (see Create a workload) that uses a proxy node and multiple inference nodes: % echo ' { "instances": [ { "name": "trustedproxy", "darwinInitOverrides": { "local-host-name": "trustedproxy" }, "release": "" }, { "name": "prefillnode", "darwinInitOverrides": { "local-host-name": "prefillnode" }, "release": "" }, { "name": "decodenode", "darwinInitOverrides": { "local-host-name": "decodenode" }, "release": "" } ] } ' > vre-configuration.json % pccvre workload create --configuration vre-configuration.json pccvre workload create instantiates, restores, and configures the instances. The client can explicitly ask for prefill-decode disaggregation in the request, instead of the proxy using heuristics to decide whether to hand off requests from one instance to another between the prefill and decode phases. In PCC, Node selection for requests from proxy nodes; in the VRE, pccvre takes on the role of the PCC Gateway and accepts your chosen PCC nodes as arguments: % pccvre instance \ invoke --name trustedproxy \ inference-request \ --prompt "" \ -- --tie-proxy trustedproxy.local \ --ft-leader prefillnode.local \ --et-leader decodenode.local Here, the --ft-leader and --et-leader flags identify the leaders of the prefill-phase and decode-phase ensembles, respectively; the VRE client retains the first token (FT) and extend token (ET) names for these phases. Using this approach, you can see multiple worker node attestations, one for each node participating in request processing, in addition to the inference-request output in the previous example. Use a specific proxy application to serve the request If the proxy instance is configured with multiple concurrent applications as described in Configure concurrent multi-app instances, you can pass the port argument to use a specific proxy application. % pccvre instance \ invoke --name trustedproxy \ inference-request \ --prompt "" \ -- --tie-proxy trustedproxy.local \ --hostname inferencenode.local \ --port Exercise KV cache reuse A Multi-Turn Agent is a sequence of related turns in which the server reuses the encrypted key-value cache (KV cache) that one turn produces when it processes the next, avoiding recomputation of tokens the model already processed (see KV cache reuse). Each turn supplies its own key material, so state cached from an earlier turn stays cryptographically inaccessible except while the server processes a turn whose request delivered the matching keys. Use the tie-vre-cli chat command to exercise this flow against a VRE instance running an inference node with the research model (see Create a workload). Each turn carries a session identifier that ties it to the interaction, and the command writes the metadata that each turn returns to the working directory, so a later invocation can continue the same session. Issue the first turn with chat, passing a session identifier of your choice, the model that handles the interaction, and the first prompt. Because no earlier turn exists for the session, the command treats this as the first turn and writes the interaction metadata it returns to a local interaction___turn_1.json file: % pccvre instance invoke -N inferencenode \ tie-vre-cli chat \ --session-id 11111111-1111-1111-1111-111111111111 \ --model-bundle-identifier com.apple.fm.language.research.adapter \ --user-prompt "Who wrote Frankenstein?" \ --hostname inferencenode.local Issue the next turn with the same --session-id. The command reads the metadata the previous turn saved, appends the new prompt to the recorded transcript, and forwards the previous turn’s routing hint. Pass the same --hostname, so the turn reaches the node that served the previous turn and the server can reuse that turn’s KV cache instead of recomputing it: % pccvre instance invoke -N inferencenode \ tie-vre-cli chat \ --session-id 11111111-1111-1111-1111-111111111111 \ --model-bundle-identifier com.apple.fm.language.research.adapter \ --user-prompt "When was she born?" \ --hostname inferencenode.local Pass --force-recalculation on a turn to make the server recompute the KV cache rather than reuse it, so you can compare the two paths. Run a multi-turn interaction across two instances You can test multi-turn interactions with two VRE instances: one PCC Agent VRE and one TIE VRE. You submit requests to the PCC Agent VRE with an initial prompt, along with a file containing follow-up prompts, each delimited by a newline character. Start a PCC Agent VRE instance named pccagent_vre (or a name of your choosing). Restore it from a “PCC Agent” release, which you can find by application name in pccvre release list. That release also bundles the TIE Proxy application, so the node acts as the proxy the multi-turn request targets with the --tie-proxy argument in step 4. Start a TIE VRE instance named llm_vre (or a name of your choosing), restored from a “TIE” release. Give the instance a larger amount of memory so you can test KV cache reuse and multi-turn interactions: % /System/Library/SecurityResearch/usr/bin/vrevm modify -N llm_vre --nram 32 Set environment variables referencing the hostnames of the instances created above. If you chose custom instance names in the previous steps, update pccagent_vre and llm_vre accordingly. % PCCAGENT_HOST="$(/System/Library/SecurityResearch/usr/bin/pccvre instance list | grep pccagent_vre | awk '{print $4}')" % LLM_HOST="$(/System/Library/SecurityResearch/usr/bin/pccvre instance list | grep llm_vre | awk '{print $4}')" Submit a multi-turn request targeting the PCC Agent VRE instance. PCC Agent invokes the Multi-Turn Agent, which issues a series of requests to the LLM VRE. % echo -e "How are you?\nHow is your day?" > prompts.txt % pccvre instance invoke --name pccagent_vre \ tie-vre-cli \ --payload '{"model_config":{"options":{"max_tokens":5}, "inference_id": "com.apple.fm.language.research.adapter"},"multi_turn_metadata":{"force_recalculation":false, "session_id":"11111113-1113-495A-93FC-0C247A3E6E5F", "interaction_id":"10000002-1001-1111-93FC-0C247A3E6E5F"}}' --user-prompt "hello" \ --workload-parameters '{"inference-id": ["com.apple.fm.language.instruct_server_v2.lw_planner_v4"]}' \ --parse-as-generate-request true \ --request-bypass false \ --tie-proxy "$PCCAGENT_HOST" \ --hostname "$LLM_HOST" \ --follow-up-prompts prompts.txt \ --workload-type "pcc-agent" In this request, model_config.inference_id (com.apple.fm.language.research.adapter) is the model the LLM node runs for each turn, and the inference-id in --workload-parameters (com.apple.fm.language.instruct_server_v2.lw_planner_v4) is the planner PCC Agent uses to drive the interaction. With force_recalculation set to false, each turn reuses the KV cache; setting it to true makes each turn recompute its context instead. Inspect diagnostic logging The VRE can forward five kinds of diagnostic data to a collector: logs, crash reports, panic reports, security events, and metrics. You can configure the VRE to forward this diagnostic data to a local collector, using the darwin-init configurations provided below. In these examples, is the IP address and is the port of your collector. Enable log, crash, and panic forwarding This configuration instructs splunkloggingd in the VRE to forward crash logs, panic logs, and allowed log lines that match the provided predicate: "secure-config": { "com.apple.logging.policyPath": "/private/var/PrivateCloudSupport/opt/audit-lists/customer/", "com.apple.logging.logFilteringEnforced": true, "com.apple.logging.crashRedactionEnabled": true }, "preferences": [ { "key": "Predicates", "value": [ "process == \"cloudboardd\"" ], "application_id": "com.apple.prcos.splunkloggingd" }, { "key": "Index", "value": "", "application_id": "com.apple.prcos.splunkloggingd" }, { "key": "Server", "value": "http://:8088", "application_id": "com.apple.prcos.splunkloggingd" }, { "key": "Token", // optional "value": "", "application_id": "com.apple.prcos.splunkloggingd" } ] Additionally, please note: Predicates: Replace cloudboardd with the process of interest. You can use an “always true” predicate such as "foo" == "foo" to forward all allowed logs. See man log for more help with predicates. Token: Optional key. If your collector requires a token, include it here to have it piped through to the log forwarder. Index: Required. If your collector requires an index (such as Splunk), put the index here. If not, then put any string value. You can also specify each of these keys with an additional Prism prefix to configure an optional second destination with its own predicate. Enable security events "secure-config": { "com.apple.securitymonitorlited.serverURL" : "http://:8088" } The above configuration overrides the destination for security events. Every secure-config security policy respects this setting, including customer. Enable metrics submission { "application_id" : "com.apple.acdc.cloudmetricsd", "key" : "DefaultDestination", "value" : { "Namespace" : "namespace", "Workspace" : "workspace" } }, { "application_id" : "com.apple.acdc.cloudmetricsd", "key" : "Destinations", "value" : [ { "Clients" : [ ], "Namespace" : "namespace", "PublishInterval" : 60, "Workspace" : "workspace" } ] }, { "application_id" : "com.apple.acdc.cloudmetricsd", "key" : "OpenTelemetryEndpoint", "value" : { "DisableMtls" : true, "Hostname" : "", "Port" : } }, { "application_id" : "com.apple.acdc.cloudmetricsd", "key" : "UseOpenTelemetryBackend", "value" : true }, { "application_id" : "com.apple.acdc.cloudmetricsd", "key" : "LocalCertificateConfig", "value" : { } } The above configuration enables cloudmetricsd to submit metrics data to the provided host and port. Configure a collector Logs, crash reports, panic reports, and security events are all forwarded using the Splunk HEC protocol. You can configure any collector that supports this protocol — such as Splunk, Vector, or OpenTelemetry Collector — to receive and display these events. Metrics are forwarded using Open Telemetry Line Protocol (OTLP) and require a collector that can accept OTLP events. Using the OpenTelemetry Collector’s splunk-hec module can enable receiving events sent over both the Open Telemetry Line Protocol (OTLP) and Splunk HEC protocols. To use this module to receive events from the VRE, start by downloading otelcol-contrib from a release of opentelemetry-collector-contrib. Then construct a configuration (otel.yaml) as follows: receivers: splunk_hec: endpoint: "0.0.0.0:8088" access_token_passthrough: true otlp: protocols: grpc: endpoint: "0.0.0.0:8089" processors: exporters: debug: verbosity: normal service: pipelines: logs: receivers: [splunk_hec] exporters: [debug] metrics: receivers: [otlp] processors: [] exporters: [debug] This configuration enables receiving all of the types of diagnostic data listed above. You can find more details on configuring the output of the debug exporter and splunkhecreceiver at their respective repositories. You can then launch the collector as follows: % ./otelcol-contrib --config otel.yaml If you configured the VRE instance to emit diagnostics, events print out to stdout. Inspect an attestation bundle You can inspect Apple Silicon Node Attestation of PCC production nodes, as well as VRE instances. Use the Appendix: Apple Intelligence Report to view attestations of PCC production nodes. Issue an inference request against a VRE instance to view its attestation bundle. Use pccvre attestation parse to display the contents of an attestation bundle, including its SEP attestation, sealed hash ledger, application data, and transparency proofs. Use pccvre attestation canonicalize to generate a Release data structure from an attestation bundle. Note that releases generated using the VRE don’t match PCC node releases due to differences in SoC identifiers, virtualized kexts, and demo model. Use pccvre attestation canonicalize --detail and pccvre release dump --detail to print Appendix: Apple Silicon Secure Boot Tags of tickets in a release structure and compare releases. Use pccvre attestation verify to verify an attestation using the host’s CloudAttestation framework. For VRE attestations to be successfully verified, the following flags must be set: The pccvre attestation subcommands accept attestation bundles in several input formats: apple-intelligence-report — the default input format — reads an Apple Intelligence Report and uses the --request-index and --attestation-index arguments to select a specific attestation bundle within the report. attestation-bundle:protobuf format accepts both binary and Base64-encoded Protobuf attestation bundles. attestation-bundle:json format accepts the JSON representation of an attestation bundle. note: --input-format apple-intelligence-report in pccvre attestation subcommands requires macOS 26.4. Validate transitive trust When you make inference requests against VRE instances using the pccvre instance invoke -N inference-request command, the output contains both node attestations that the user’s device receives and Request execution log (REL) entries. These REL entries contain attestation bundles of transitively trusted nodes from when TIE Proxy was in use, for example: Proxy attestation: release digest: 2c43734a192c7f423fc7d4dcf73903428bffc253909e0ae808f11f64edcffeb0 trusted release set: [] {"sepAttestation":"MIIFQTCCBMYCAQEwggJwoSIEIMyWzhPfc9lm3TeCxEU6iOFtwLo1vbaaLb... ... Request execution log entry: is NACK: false is final: false associated proxy attestation: release digest: 2c43734a192c7f423fc7d4dcf73903428bffc253909e0ae808f11f64edcffeb0 compute node attestation: release digest: de8ed97fa5d4b0ee326e2834b0399f2ed89444fc7db1a38abb7a16a1ef85a7f3 {"sepAttestation":"MIIFHDCCBKICAQEwggJMohsEGWZlMDEtYmNmNWM4YjFlZGY4ZDFhYy1kLT... ... Request execution log entry: is NACK: false is final: true associated proxy attestation: release digest: 2c43734a192c7f423fc7d4dcf73903428bffc253909e0ae808f11f64edcffeb0 The above example illustrates three types of entries a user’s device sees when using a proxy node: The attestation of the proxy itself, which anchors the Trusted log revisions for proxied worker nodes. Request execution log entries, each containing the selected worker node’s release digest as well as complete attestation. The final REL entry for the request, signaling that the proxy is sending no further requests to other PCC nodes. A proxy node validates each worker node’s attestation against the trusted log revision its own attestation anchors. A VRE release loosens that enforcement by setting the com.apple.pcc.research.disableAppleInfrastrucutureEnforcement secure-config parameter on the proxy. A node accepts that parameter only in a virtual machine, and its attestation names the security policy that governed its boot. Restrict proxy transitive trust A proxy node sends requests to an inference node only while the transparency log, at the revision the proxy’s own attestation anchors, includes the inference node’s release digest. The com.apple.cloudboard.attestation.enableTransitiveProofVerification secure-config key governs this check. To watch a proxy reject a worker, create a Create a workload holding a proxy instance and an inference instance, issue an inference request through the proxy, and then change the software the inference node runs. Enabling SSH on the inference node, for example, adds a cryptex to its release: the node’s release digest changes, the proxy no longer accepts its attestation, and inference fails. Load custom cryptexes Use cryptexes to create and package additional software to install on a VRE instance. The pccvre tool provides a command to create a new cryptex from a specified directory structure: % pccvre cryptex create --source CustomCryptexRootDirectory --variant MyCustomCryptex Created new cryptex at path: MyCustomCryptex.aar with variant name: MyCustomCryptex When such a cryptex is installed in VRE, its content is mounted at /private/var/PrivateCloudSupportInternalAdditions/. pccvre cryptex create marks packaged binaries as allowed in Restricted Execution Mode. Binaries installed with a custom cryptex must have a code signature; ad-hoc signing is sufficient. The cryptex variant is an identifier string that must be unique within a VRE instance. pccvre provides helpers to easily list and modify the set of cryptexes configured for a VRE instance: % pccvre instance configure cryptex list -N Configured cryptexes: - FM_LANGUAGE_SECURITY_RESEARCH_V1 - PrivateCloud Support % pccvre instance configure cryptex remove -N -V PrivateCloudSupport Removed cryptex matching 'PrivateCloudSupport' from VRE instance. % pccvre instance configure cryptex list -N vre Configured cryptexes: - FM_LANGUAGE_SECURITY_RESEARCH_V1 % pccvre instance configure cryptex add -N -C "MyCustomCryptex:$PATH_TO_MY_CUSTOM_CRYPTEX" Added cryptex 'MyCustomCryptex' to VRE instance. Execute binaries in a cryptex The executables present in a cryptex may link libraries and frameworks also present in the cryptex. To enable dyld to find these libraries and frameworks, you must run the executable with the cryptexctl exec command to set an appropriate subsystem_root_path value that informs dyld of the relevant search paths: % cryptexctl exec /private/var/PrivateCloudSupportInternalAdditions/ /private/var/PrivateCloudSupportInternalAdditions/$PATH_TO_EXECUTABLE In this example, the binary at $PATH_TO_EXECUTABLE is able to link libraries and frameworks located relative to /private/var/PrivateCloudSupportInternalAdditions/. Any children of that process automatically inherit the configuration. This step is needed only when running such executables manually, such as through ssh, as cryptexd automatically handles it when loading LaunchDaemons contained within a cryptex. Disable Restricted Execution Mode Restricted Execution Mode (REM) enables the system to lock out functionality that’s required only during the system’s initial boot and setup. Entering REM is enforced by TXM to be a one-way transition switch, after which the TXM refuses to load additional trust caches and imposes new constraints on code execution. By default, the darwin-init configuration for the VRE configures REM the same way as actual PCC nodes — {"userspace-reboot": "rem"}. After setup is complete, darwin-init initiates a user-space reboot, and launchd makes a system call to request TXM to activate the one-way REM switch. This process limits the set of executables that can run after entering REM to those in the loaded trust caches. On the VRE, you can change the darwin-init configuration to {"userspace-reboot": "rem-dev"}. This change configures the VRE to forgo making a system call to TXM to activate the one-way REM switch after the user-space reboot, which allows you to use tools that are normally restricted by REM. Debug the kernel You can debug the kernel by attaching to the GDB stub of a VRE instance. pccvre instance start prints the GDB stub port: % pccvre instance start --name vre ... GDB stub available at localhost:59013 Restore custom firmware The PCC VRE supports restoring an instance with custom firmware for the kernel cache, SPTM, and TXM images. To see further documentation for these options, invoke pccvre instance create --help. All system firmware is packed as an Image4 payload (.im4p) file. The pccvre image4 extract command provides the functionality to extract binary payloads from the Image4 file. Conversely, the pccvre image4 package command provides the functionality to package a binary payload into an image4 wrapped payload for the specified firmware. To see further documentation for these commands, invoke pccvre image4 --help. Interact with the control-plane agent Apple provides a PCC control-plane testing server that you can run on your host to interact with the controlplaneagent daemon, discussed in ServiceControl framework, which runs in the VRE instance. The pccvre tool provides a subset of commands to facilitate the use of the control-plane testing server. To explore them, invoke the following command: % pccvre instance invoke -N control-plane --help The setup command registers a port on your host for the control-plane testing server to listen on, and configures the controlplaneagent to connect to that port: % pccvre instance invoke -N control-plane setup --port After the setup, restart the VRE instance so controlplaneagent loads the new configuration. Next, start the control-plane testing server: % pccvre instance invoke -N control-plane server After the controlplaneagent connects to the control-plane testing server, you can exercise the controlplaneagent functionalities by invoking the send command. Behind the scenes, the send command uses the control-plane testing server to provide the specified command when the controlplaneagent next requests a command. % pccvre instance invoke -N control-plane send This example exercises TIE model switching through the control plane. Note that the init command, which asks the controlplaneagent to manage the specified service, is required to run only once for that service: % pccvre instance invoke -N control-plane send init --service "com.apple.tie-controllerd.from.control-plane-agent" % pccvre instance invoke -N control-plane send deactivate --service "com.apple.tie-controllerd.from.control-plane-agent" % pccvre instance invoke -N control-plane send model-switch --service "com.apple.tie-controllerd.from.control-plane-agent" --model "com.apple.fm.language.research.partial_grammar#cv10" % pccvre instance invoke -N control-plane send activate --service "com.apple.tie-controllerd.from.control-plane-agent" Exercise cloud asset distribution To exercise Cloud asset distribution, you can set the following configuration: "secure-config": { "com.apple.cloudos.cloudassetdownloaderd.enabled": true, "com.apple.cloudos.cloudassetdownloaderd.useControlPlaneAgent": true } If the asset you want to test is not in AEA format, set the following additional configuration: "secure-config": { "com.apple.cloudos.cloudassetdownloaderd.allowNonAEAAssets": true } First set up and start the control-plane testing server as described in Interact with the control-plane agent: run control-plane setup, restart the instance, then start control-plane server. Then use control-plane send apply to provide the cloud asset configurations to cloudassetdownloaderd; the map takes effect only once controlplaneagent is polling the server: % pccvre instance invoke -N control-plane send apply \ --service "com.apple.cloudos.cloudassetdownloaderd" \ --key "applicationAssetMap" \ --value '{"CipherMLAssets":[{"url":"http://:/test-v1.aar","version":"1","asset_id":"testAsset"}]}' cloudassetdownloaderd adopts a given asset map once. Re-sending an identical applicationAssetMap is a no-op that triggers no new download, so to exercise the download again, change the version or asset_id. You can use pccvre http-server to host your test assets. Run the command with your asset directory; it then prints the server’s IP address and port for use in the configuration above. % pccvre http-server 192.168.64.1:49516 To verify your assets are being loaded, you can SSH into the VRE instance and use the log show command to look at the cloudassetdownloaderd logs: % log show --info --predicate 'subsystem=="com.apple.cloudos.cloudassetdownloader"' Received new asset configs to apply: [applicationID: CipherMLAssets, assetID: testAsset, source: http://192.168.64.1:49516/test-v1.aar, destination: /private/var/mobile/assetdownloader/CipherMLAssets/testAsset/1, version: 1] Asset processed successfully. Source=http://192.168.64.1:49516/test-v1.aar Destination=/private/var/mobile/assetdownloader/CipherMLAssets/testAsset/1 Exercise external tool calling PCC Agent invokes Appendix: Tool Gateway Protocol through cb_bridged, which connects to a tool gateway: an external gRPC service hosted outside the PCC trust boundary. You can exercise this path in the VRE. Set up the agent and compute VRE instances This example uses two VRE instances: Run a mock tool gateway MockToolGateway ships as part of the PCC tools. Use the pccvre instance invoke tool subcommand, a trampoline for running other tools from the PCC tools directory on the host: % pccvre instance invoke --name pccagent tool MockToolGateway --host 0.0.0.0 --port 50051 MockToolGateway implements the PccToolGateway gRPC service and replies to every tool call with a basic response, so you can exercise the connection and protocol without a real tool implementation. Connect the agent to the mock gateway Add the following secure-config overrides to the pccagent instance’s darwin-init configuration (see Create a workload), replacing with an address the VRE guest can reach on your host. MockToolGateway serves without TLS, so you must set tlsConfig.enable to false. "secure-config": { "com.apple.cloudboard.cb_bridged.toolGateway.targetHost": "", "com.apple.cloudboard.cb_bridged.toolGateway.targetPort": 50051, "com.apple.cloudboard.cb_bridged.toolGateway.tlsConfig.enable": false } Restart the agent instance so cb_bridged loads the new configuration. Script the shadow responses To fully control the tool call, you need two shadow response scripts: a tool call request and a final inference answer. Responses need to adhere to the correct protocol; the Minimal response protocol helps you do this. Example tool call request: tool_call.txt call { call_id: "call_1" content { function { tool_name: "web_search" arguments: "{\"search_queries\": [\"current weather in Cupertino\"]}" } } } Example final answer: final_answer.txt content { tokens: "The current weather in Cupertino is 68°F and sunny." } Example terminating response: final_response.txt final_response { sentence: "The current weather in Cupertino is 68°F and sunny." } Encode each response using protoc, the protobuf compiler, piping through the base64 command, and capture the result in a variable named for the response it encodes: (The final answer script also needs to send inference_complete and final_response responses to correctly terminate the request. Give final_response a sentence; an empty one leaves the client waiting until it times out.) % tool_call_data=$(protoc --encode Response response.proto <<< "$(cat tool_call.txt)" | base64) % final_answer_data=$(protoc --encode Response response.proto <<< "$(cat final_answer.txt)" | base64) % inference_complete_data=$(protoc --encode Response response.proto <<< "inference_complete {}" | base64) % final_response_data=$(protoc --encode Response response.proto <<< "$(cat final_response.txt)" | base64) Create each script JSON file from these variables: % cat > tool_call.json < final_answer.json < with your host’s address on the VM network, which is 192.168.64.1 for the default NAT configuration: "secure-config": { "com.apple.cloudboard.cloudApp.TIECloudApp.shadow.enabled": true, "com.apple.cloudboard.cloudApp.TIECloudApp.shadow.remoteHost": "", "com.apple.cloudboard.cloudApp.TIECloudApp.shadow.remotePort": 8080, "com.apple.cloudboard.cloudApp.TIECloudApp.shadow.workloadName": "tie-cloudboard-apple-com", "com.apple.cloudboard.skipMultiAppValidations": true } Make a tool-calling inference request PCCAgentApp only routes a tool call to cb_bridged if the request declares that tool as a server tool capability up front. Add a tool_constraints entry naming the tool to the request payload when making the inference request. A web_search capability declaration requires country_code, and PCCAgentApp rejects a request that omits it. Omitting the capability declaration entirely causes PCCAgentApp to reject the eventual tool call before it reaches cb_bridged. You also need to pass the IP addresses or hostnames and port in the --tie-proxy, --hostname, and --port options: % pccvre instance \ invoke --name pccagent \ tie-vre-cli inference \ --tie-proxy \ --hostname \ --workload-type pcc-agent \ --request-bypass false \ --user-prompt "" \ --workload-parameters '{"inference-id":[""]}' \ --payload '{"model_config":{"inference_id":"","options":{"tool_constraints":{"tool_capabilities":[{"web_search":{"locale":"en_US","country_code":"US"}}]}}}}' Four of these options are required for the tool call to reach cb_bridged: Choose an inference identifier whose feature declares no safety guardrails, such as com.apple.fm.language.instruct_server_v2.open_ended_compose. Guardrails make their own inference calls to the same instance, and because the shadow remote serves its scripts in round-robin order, a guardrail call consumes the tool call script before the request that needs it. MockToolGateway logs each connection, request, and response to standard output. A successful run logs the MCP handshake followed by a tools/call entry, and tie-vre-cli prints the tool call and then the final answer. PCCAgentApp maps the web_search server tool to the gateway-side tool pegasus_search, and rewrites the model’s search_queries array into a single query argument alongside locale and country_code, so the gateway sees: { "jsonrpc": "2.0", "id": "", "method": "tools/call", "params": { "name": "pegasus_search", "arguments": { "query": "current weather in Cupertino", "locale": "en_US", "country_code": "US" } } } Exercise HomeKit Secure Video Analysis The HomeKit Secure Video Analysis (HKSV) workflow generates natural-language video descriptions and embeddings for HomeKit Secure Video clips, coordinating a PCC Agent instance, a media decoder, an embedding worker, and an LLM. You can exercise this workflow in the VRE. Set up the agent and compute VRE instances This example uses four VRE instances: You configure the LLM node with shadowing because the LLM that ships with the VRE can’t take image inputs, which the HKSV analysis workflow requires for captioning. PCC Agent VRE For this node, use a “PCC Agent” release; no changes are required. Media decoder VRE For this node, use a “PCC MediaDecode” release. To replicate the Jetsam settings of a production MediaDecode node, apply this change to the darwin-init: % pccvre instance configure \ darwin-init dump --name mediadecode_vre \ | jq '(.cryptex[] | select(.variant == "PCCApp_MediaDecode")) += {"jetsam_properties_variant": "s1"}' \ > /tmp/mediadecode_vre-darwin-init.json % pccvre instance configure darwin-init set --name mediadecode_vre --input /tmp/mediadecode_vre-darwin-init.json Embedding worker VRE For this node, use a “PCC Agent Worker Embedding” release. LLM VRE The following procedure adapts a TIE compute instance (with TIECloudApp enabled) to serve a captioning response using the shadow app. The HKSV workflow reads the caption from both the streamed response content tokens and the terminating final_response sentence, so a script that populates only one of them returns empty captions. Provide the same caption JSON in a content token and in a final_response, and close the token stream with an inference_complete message between them. Example caption content: content.txt content { tokens: "{\"short_caption\":\"Test caption\",\"full_caption\":\"This is a full caption.\",\"noteworthy\":1,\"is_sensitive\":false,\"is_no_activity\":false}" } Example terminating response: final_response.txt final_response { sentence: "{\"short_caption\":\"Test caption\",\"full_caption\":\"This is a full caption.\",\"noteworthy\":1,\"is_sensitive\":false,\"is_no_activity\":false}" } The protobuf schema is defined here: Appendix: TIE Response Protocol. Encode the caption content, the inference_complete message that closes the token stream, and the terminating final_response, using protoc, the protobuf compiler, piping through the base64 command, and capture each in a variable: % content_data=$(protoc --encode Response response.proto <<< "$(cat content.txt)" | base64) % inference_complete_data=$(protoc --encode Response response.proto <<< "inference_complete {}" | base64) % final_response_data=$(protoc --encode Response response.proto <<< "$(cat final_response.txt)" | base64) Create a shadow app script JSON file that serves the caption content, then the terminating messages: % cat > responses.json < with your host’s address on the VM network, which is 192.168.64.1 for the default NAT configuration: "secure-config": { "com.apple.cloudboard.cloudApp.TIECloudApp.shadow.enabled": true, "com.apple.cloudboard.cloudApp.TIECloudApp.shadow.remoteHost": "", "com.apple.cloudboard.cloudApp.TIECloudApp.shadow.remotePort": 8080, "com.apple.cloudboard.cloudApp.TIECloudApp.shadow.workloadName": "tie-cloudboard-apple-com", "com.apple.cloudboard.skipMultiAppValidations": true } Make an HKSV analysis request Use the following command to make a request with an HKSVFragment H.264 or H.265 video, as described in HomeKit Secure Video Analysis: % pccvre instance \ invoke --name pccagent_vre \ tie-vre-cli hksv \ --tie-proxy \ --media-decode-node \ --embedding-node \ --llm-node \ --log-routing \ --video-path