Overview

LucidLink Classic supports deployment in virtual machine (VM) environments, allowing teams to access and collaborate on filespace data via cloud or on-premises compute infrastructure. To ensure long-term filespace health and prevent connectivity issues, VM-based deployments require specific configuration and planning.

This article covers the recommended approach for deploying LucidLink Classic on VMs, including image preparation, automated provisioning and the distinction between static and ephemeral VM configurations.

Ephemeral vs. static VMs: Why it matters

Considerations for ephemeral VMs

An ephemeral VM is a short-lived compute instance used in cloud environments, render farms, VDI platforms and automated ingest pipelines. These instances are created, utilized and destroyed on demand.

While this pattern is efficient for compute, using ephemeral VMs with LucidLink Classic without proper control poses a long-term risk. Every time a new VM boots from a base image and connects to your filespace, it registers as a unique client (nodeID).

Your filespace supports a finite limit of approximately 60,000 nodeID registrations. While this seems like a large number, uncontrolled automated pipelines or ephemeral VDI pools can exhaust these slots rapidly. Once this limit is reached:

• New machines cannot connect to the filespace.

• Existing connected machines continue to function.

• Legitimate team members attempting to connect from new devices are blocked.

Each nodeID (registered client connection) is permanent and cannot be reclaimed or reset once established. Reaching the maximum nodeID limit is an irreversible state that typically requires a full filespace migration to restore service to new devices.

We strongly recommend against workflows that rely on large numbers of short-lived, disposable VMs connecting to a LucidLink Classic filespace. Use static VM configurations or persistent identities to maintain filespace health and preserve available nodeID slots.

The nodeID limit applies specifically to LucidLink Classic. These architectural constraints are not applicable to the New LucidLink (3.x) environments.

The recommended approach: static VMs

The safest and most supported approach is to use static (persistent) VMs. These are machines that are provisioned once, maintained over time and reused rather than recreated.

With a static VM:

• The LucidLink client registers a single nodeID during its initial connection to the filespace.

• The same VM is reused for subsequent sessions without registering a new nodeID.

• The filespace does not accumulate unnecessary nodeIDs over time.

This configuration mirrors the behavior of a physical workstation, which is the primary architecture LucidLink Classic is designed around.

Prepare your base VM image correctly

When building a base VM image or template from which multiple machines will be deployed, follow these steps:

• Install the LucidLink Classic client - Install the application on the base image before capturing it.

• Remain disconnected - Do NOT connect or log in to the filespace on the base image before capturing or saving it.

• Clear existing metadata - Ensure no filespace-specific metadata exists in the image at the time of capture. Remove any specific filespace registrations found in the .lucid directory, usually located in the user folder. While the .lucid folder itself can remain, you must delete the filespace UUID subfolders (e.g., .lucid/instance_501/<fsuid>).

Understanding nodeID retention logic

The nodeID is a unique identifier generated during the initial connection to a filespace. To ensure a VM reuses its existing registration and does not consume additional slots, the local metadata must be preserved once the VM is set up.

The nodeID is stored within the following directory structure, typically found in the user's home folder: .lucid/instance_501/<fsuid>

Retention requirements

To prevent a machine from registering as a new client and generating a new nodeID, follow these practices:

• Preserve the instance folder - Do not delete or purge the instance_<id> or <fsuid> subfolders. If these are removed, LucidLink will treat the next connection as a brand-new machine.

• Maintain persistent storage - Ensure the directory containing the .lucid folder is stored on a persistent disk that survives reboots and image updates.

• Avoid manual cleanup scripts - Ensure that maintenance scripts or profile-cleaning tools do not target the .lucid directory.

Configure cache location and size via script

For VMs where the default cache location is not ideal (e.g., when using a dedicated data volume), use the LucidLink CLI to set the cache location and size during your provisioning script:

lucid2 config --set --local --DataCache.Location /mnt/lucid_cache
lucid2 config --set --local --DataCache.Size 100G

This ensures each VM utilizes the appropriate storage for caching without manual intervention.

Running LucidLink as a service

In VM environments, it is often necessary for the filespace to remain mounted without an active user session. Configuring LucidLink Classic as a service ensures that the mount is available immediately upon boot and persists after a user logs out.

This setup is ideal for automated workloads, server-side processing and shared compute resources. Use the following guides to configure the service for your operating system:

• Configuring the Windows Service

• Configuring the Linux systemd Service

Managing unavoidable ephemeral workflows

If your workflow requires short-lived compute instances (e.g., cloud-based render nodes or ingest pipelines), implement the following mitigations to protect your filespace health:

• Minimize unique instances - Reduce the number of unique machines connecting to the filespace. Where possible, reuse VM instances by stopping and starting them rather than destroying and recreating them.

• Implement persistent pools - Instead of creating a new VM for every task, maintain a fixed pool of registered VMs. Route your workloads through these existing machines to keep nodeID registrations predictable.

• Control automation - Do not automate uncontrolled filespace connections via scripts or applications without calculating how many unique nodeID registrations will accumulate over time.

• Consult LucidLink Support - Contact LucidLink Support before building an automated pipeline that involves frequent provisioning of new clients. Our team can assess your architecture and advise on a safe approach.