12. Reference architecture

The reference architecture assumes a host machine running multiple isolated Firecracker VMs, always one VM per user. Network access can be controlled at the level of individual VMs, so outbound communication can be restricted to approved targets only. cdx-daemon acts as the control plane that connects to the VMs and manages them remotely; it does not have to run on the same host as the VMs.

The home directory /home/codexis is mounted into the VM from an NFS server. Storage on the NFS is managed via ZFS datasets and backed up with snapshots to S3 or an S3-compatible storage. If the client requires all business data to remain local, the entire stack can be operated on-premise and a local S3-compatible object storage can be used for backups. The only external services that then remain are the CODEXIS API and the OpenAI API.

Selected folders from the client PC or the company file server are synchronized to the NFS layer using Syncthing. As a result, the same files appear inside the user's VM as standard directories, and the agent can work with them without manual upload and download.