Connect and Access
Connecting to a virtual machine opens a remote desktop session against a live instance. Starting a configuration and connecting to it are two different actions: starting spawns the machine and decides who owns it, while connecting opens a session on a machine that is already running.
Why starting a VM matters more than connecting to it
Whoever starts the VM becomes its Owner for that session. The Owner controls all access to the machine and its drives for as long as it runs. Co-owners listed in the configuration are added automatically with the Co-owner role, but only the user who actually started it is the Owner. If a co-owner later shuts the machine down and starts it again, they become the Owner and the previous Owner reverts to Co-owner. See VM Roles and Permissions.
Shutting down is cheap and safe. The machine boots from a clean image that resets on every restart, and your data lives on encrypted drives rather than in the machine. Shutting a VM down at the end of the day loses nothing and returns its CPU and memory to your team's allocation. There is no reason to leave a machine running to protect work in progress, provided that work is on a drive.
Configuration changes apply at the next start. A VM is assembled from its configuration when it starts, so changes saved to a configuration while its VM is starting or running take effect only after a restart, and a project tag changed on a running VM does not take effect until the VM is restarted, because those properties are applied when drives are mounted at boot. Deleting a configuration requires its VM to be stopped. For more information, see VM Configurations.
Before you begin
- You have the Start VMs from VM configurations permission and access to the relevant drive keys.
- The Connect Application is installed. See Get Started.
- Your team has CPU and memory quota available for the hardware setup you selected.
Access a Virtual Machine via Remote Desktop Connection (RDP)
- Go to the Virtual Machines icon in the top left taskbar.
- Click the VMs section on the top left panel.
- In the left panel, select the connected virtual machine to access.
- Click the Start Remote Desktop button.
- If the VM is a constellation, the Connect to an application on
vm-nameprompt appears. Select the running worker VM to open the application on, then click Connect. - In the Instructions for
vm-nameprompt, click the Copy button next to your username and password. - Paste the credentials into your RDP client. Alternatively, click Download RDP file and open the downloaded file with your RDP client.
- Click Close.
tiCrypt opens a tunnel to the VM through the Connect application and shows the credentials for the remote desktop session, followed by the instructions of the VM's hardware setup.
The tunnel task Tunneling to vm-name runs three steps: "Opening gate for Connect
within VM", "Forwarding local ports to VM and opening proxy via Connect", and "Setting up
authentication". Every time you open the remote desktop, tiCrypt sets a new password, so copy the
password again after each opening.
Download RDP file appears only when the VM forwards the remote desktop port. It saves
vm-name.rdp, a remote desktop file that points your client at 127.0.0.1 on the local
port of the tunnel and fills in your username. On a Windows VM, the username is prefixed with the
VM's host name. The file asks your client to prompt for the password, so it never contains it.
A constellation is a VM that manages a network of worker VMs. Its prompt reads "This virtual machine is a constellation, meaning its sole purpose is to manage a network of child VMs. Please select a child VM to open an application on." It lists each running worker with its operating system, cores, and RAM. For more information, see Constellations.
The ⋮ menu next to a running VM in the left panel offers the same action as Open remote application.
Click the Copy password button when you only need the password to perform an RDP connection.
Reset Connection of a Remote Desktop (RDP)
- Go to the Virtual Machines icon in the top left taskbar.
- Click the VMs section on the top left panel.
- In the left panel, select the virtual machine to reset the RDP connection.
- Click the Start Remote Desktop button.
- In the prompt, click the Reset Connection button. The prompt warns: "Resetting the connection may disrupt the running application or ongoing SFTP transfers."
- Once done, click Close.
Resetting an RDP connection disrupts running applications and ongoing SFTP transfers.
Turn On a Virtual Machine
- Go to the Virtual Machines icon in the top left taskbar.
- Click the VMs section on the top left panel.
- In the left panel, select the virtual machine to turn on.
- Click the Start VM button in the top right.
- If the drive problems prompt appears, review the drives listed. Click Ignore and Launch to start the VM anyway, or Cancel to fix the drives first. For more information, see Drive problems before start.
The task Starting VM from vm-name runs. When it finishes, you are the
VM's Owner, its drives are attached and mounted, and the configuration's co-owners are added to the
VM with the Co-owner role: they are registered as managers with all permissions, and the drive keys
they need are shared with them.
The Start VM button appears only to the owner and co-owners of a stopped configuration. You can also start a configuration from the Start VM icon next to it in the list, or by ticking Launch a VM from this configuration immediately in the configuration form.
Before it starts the VM, tiCrypt runs these checks in order and stops at the first one that fails:
- Private key: your private key must be decrypted. tiCrypt may ask for your password.
- Quota: the hardware setup must fit the cores, memory, and devices left in your quota. tiCrypt uses the stricter of your team's quota and your own. The messages read "You need N cores but only have M available", "You need X bytes of memory but only have Y available", or "You need N device but only have M available". "Cannot access information about the VM Hardware Setup" means the hardware setup cannot be read.
- Project: your membership in the configuration's project must be active: "Your membership is not active in this VM configuration's project".
- Repeat press: "You must wait 3 seconds between pressing the start button".
- Home drive: "Configuration has no home drive".
- State: "Configuration is not in a stopped state".
- Drives: every drive of the configuration is checked. If any has a problem, the drive problems prompt appears.
Drive problems before start
The drive problems prompt carries the configuration's name as its title and reads "There are
problems with drives attached to vm-name." It lists every drive of the configuration
with its format and capacity, and shows the problem under each affected drive. Cancel is
selected by default. Ignore and Launch starts the VM anyway.
| Message | Meaning |
|---|---|
| Drive is not ready | The drive is initializing or being transferred to another pool. Wait and start again. |
| Drive is not shared with you | You hold no key to the drive. Ask its owner to share it with you. |
| Not all co-owners have a key for this drive | At least one co-owner lacks a key to the drive, or holds only a read-only key to a drive the configuration attaches read-write. Shown only if you have the Get drive keys permission. |
| Drive cannot be attached in read-write mode | The drive is already attached to another VM. |
| Drive cannot be attached in read-only mode | The drive is already attached read-write to another VM. |
| You no longer have access to this drive or drive deleted | The drive was deleted or is no longer shared with you. Remove it from the configuration. |
| Drive is shared with you in read-only mode | The configuration attaches the drive read-write but your key is read-only. |
Errors while the VM starts
The Starting VM from vm-name task checks the home drive, creates the VM, and then
attaches and mounts the drives. A failure shows in the task as "Failed at" followed by one of these
messages.
| Message | Meaning |
|---|---|
| home drive no longer exists or isn't shared with you | The home drive was deleted or unshared. Edit the configuration and choose another home drive. |
home drive already attached read-write to vm-name | Another VM is using the home drive. Shut that VM down or detach the drive. |
home drive is already attached read-only to vm-name | Other VMs have the home drive attached read-only. Detach it from them first. |
| you do not have a read-write access to the home drive | Your key to the home drive is read-only. |
| would exceed VM (CPU) core limit for team | Starting the VM would exceed your team's core quota. The message shows the cores used, the limit, and the cores needed. |
| would exceed VM memory (RAM) limit for team | Starting the VM would exceed your team's memory quota. |
would exceed VM device device limit for team | Starting the VM would exceed your team's quota for that device. |
| hardware setup deleted or unavailable | The hardware setup no longer exists or is no longer available to you. Edit the configuration and choose another one. |
If the request times out, the task reads "Gateway timed out; polling for VM.." and keeps waiting for
the VM. If the first attempt to mount the home drive fails, tiCrypt shows "First attempt to
attach/mount home drive failed (will retry once)" and tries once more. Failures to mount other
drives do not stop the start: tiCrypt shows "Failed to mount RAM disk", "Failed to attach and mount
NFS drive drive-name", or "Failed to attach and mount drive-name (you can
retry later from the VM drives panel)".
Connect to a Virtual Machine
- Go to the Virtual Machines icon in the top left taskbar.
- Click the VMs section on the top left panel.
- In the left panel, select the virtual machine to connect to. Selecting a running virtual machine connects to it automatically.
- If it is not connected, click the Connect to virtual machine button next to it.
- Ensure the virtual machine is turned on before connecting.
- You may be required to enter your password upon connection.
Connect first, then do everything else. Remote Desktop, the terminal, and file transfers all run through the connection established here. None of them are available until the VM shows as connected, so a missing RDP or transfer option usually means this step has not completed rather than that the feature is unavailable.
In tiCrypt, you connect to a full VM rather than SSH-ing into a shared login node. See Shared Computing to tiCrypt for a concept-by-concept mapping of how VM access replaces traditional SSH workflows.
The running VM panel
Selecting a running VM opens the running VM panel on the right. It is not the configuration's detail panel: it shows the live instance, its controller, and what you may do on it.
The header shows the VM's name, its hardware setup with the VM Controller version ("VMC version"), the project tag, the Owner, and badges: FIPS enabled, and Owner, Co-owner, or Shared with you. If tiCrypt cannot read the VM's details, the header reads "Cannot display VM information".
The action cards appear only while you are connected. All of them except VM Settings and Details stay disabled until the VM's home drive is mounted. The following table describes the cards and the VM permissions they need. For the permissions, see VM Users.
| Card | Shown when | Enabled when |
|---|---|---|
| Start Remote Desktop | Always | You have Remote application access. |
| File Transfer (as Admin/Root) | The VM Controller supports elevated file access | You have Sudo (Admin) Access and one of Files, VM to Vault transfer, or Vault to VM transfer. |
| File Transfer | Always | You have one of Files, VM to Vault transfer, or Vault to VM transfer. |
| File Explorer (as Admin/Root) | The VM Controller supports elevated file access | You have Sudo (Admin) Access and one of Files, VM to Vault transfer, or Vault to VM transfer. |
| File Explorer | Always | You have one of Files, VM to Vault transfer, or Vault to VM transfer. |
| Open Terminal | Always | You have Terminals. |
| SFTP to VM | The VM offers SFTP and you have SFTP Access | You have Remote application access. |
| VM Settings and Details | You are a manager of the VM | Always. |
Notices on the running VM panel
The panel can show these notices above the cards:
- No attached home drive: "This VM has no attached home drive. Most functionality does not work without an attached home drive, and has been hidden." Repair attaches and mounts the home drive; Ignore shows the hidden functions for this view only. See Connect to a Virtual Machine.
- Co-owners missing drive keys: "N of M co-owners are missing drive keys for this VM. Those co-owners can't mount all drives upon co-owner restart. Repair shares the keys for this configuration's drives with every co-owner, granting them access to the data on those drives." Only the VM's Owner sees it, and only with both the Get drive keys and Share drives permissions. A co-owner who holds only a read-only key to a read-write drive counts as missing a key. Repair runs the task Share drives with new owners for
vm-name. - Home drive almost full: "Home drive exceeds 90% capacity. Continued usage may lead to data loss or system instability. Take immediate action to free up space or consider adding more drives to your VM." Shown only if you have System Statistics.
- Unsynchronized users: "Warning: Backend does not know about all users authorized to access this VM. Users N will not be able to access this VM until you synchronize the user list." Only the VM's Owner sees it, with the home drive mounted and System Statistics. Synchronize users brings the server's list of authorized users in line with the VM's users. For more information, see VM Users.
Running VM toolbar
The toolbar above the cards holds the actions for the running VM. When there are more than six, they are collected in a ⋮ menu at the right. Each item in that menu has a pin button, Pin or Unpin followed by the action's name; pinned actions also show as icon buttons in the toolbar. Pins are stored in your browser. Actions that need the VM are disabled while you are not connected or the home drive is not mounted.
- Restart controller: restarts the VM Controller. For more information, see Advanced Operations.
- Sync user permissions: refreshes the access directory permissions on the VM's drives.
- Disconnect from VM: closes your connection to the VM.
- Repair corrupted database: repairs the VM's user database. Managers only.
- View logs: shows the VM's log. Available to everyone with access to the VM, and to users with the View the logs of any VM permission.
- JSON Export: shows the VM's details as JSON.
- Libvirt XML description: shows the VM's Libvirt definition. Super-admins only.
- Open VNC terminal: opens a VNC console to the VM.
- Add Co-owners: changes who co-owns the VM's configuration. Owners and co-owners of the configuration only.
- Fix co-owner permissions: makes every co-owner of the configuration a manager with all permissions on the VM. Shown when the configuration has co-owners besides the VM's Owner, and acts only if you are a manager.
- Bulk email: lists the email addresses of the VM's users so you can copy or download them.
- Set project: changes the project tag of the VM. Requires the Tag anything with any project permission.
- Power: restarts or shuts the VM down. Requires the Shut down their VMs permission.
- Open debugger: sends raw requests to the VM Controller. Shown only in debug mode.
Fix co-owner permissions runs the task Fix co-owner permissions on vm-name and
reports "Co-owner permissions repaired", or "All co-owner permissions are already correct" when
nothing needed changing. tiCrypt also runs it automatically when the home drive mounts, at most
once every five minutes.
Open a Virtual Machine's Terminal Hub
- Go to the Virtual Machines icon in the top left taskbar.
- Click the VMs section on the top left panel.
- In the left panel, click the virtual machine to open its terminal.
- Click the Open Terminal option in the center.
- Use the terminal console.
Disconnect from a Virtual Machine
- Go to the Virtual Machines icon in the top left taskbar.
- Click the VMs section on the top left panel.
- In the left panel, click the Disconnect from virtual machine button by the virtual machine to disconnect.
Restart a Virtual Machine
- Go to the Virtual Machines icon in the top left taskbar.
- Click the VMs section on the top left panel.
- Select the virtual machine you want to restart.
- In the left panel, click the menu next to the virtual machine.
- Select Power.
- In the Shut down
vm-name? pop-up, click Restart.
The VM shuts down normally and then starts again from its configuration, which makes you its Owner again.
The Shut down vm-name? pop-up offers three choices:
- Restart: "Restarts the VM. Executes a normal shutdown and then starts the VM again." Only the VM's Owner, the user who started it, can restart it; for anyone else the choice is disabled with "Only VMs you own can be restarted." Restart works only for a VM started from a configuration.
- Normal Shutdown: "Executes a safe and orderly shutdown of the VM."
- Hard Shutdown: "Instantly forces the VM to shut down, but risks data corruption on your drives. Use with caution." It requires ticking I accept the risk.
When you open the pop-up from a stopped configuration's Power action or its Stop VM button, Restart is not offered.
Shut Down a Virtual Machine
- Go to the Virtual Machines icon in the top left taskbar.
- Click the VMs section on the top left panel.
- Select the virtual machine you want to shut down.
- In the left panel, click the menu next to the virtual machine.
- Select Power.
- In the pop-up, click Normal Shutdown.
Forcefully Shut Down a Virtual Machine
- Go to the Virtual Machines icon in the top left taskbar.
- Click the VMs section on the top left panel.
- Select the virtual machine you want to forcefully shut down.
- In the left panel, click the menu next to the virtual machine.
- Select Power.
- In the pop-up, read the risks.
- Tick the box I accept the risk.
- Click Hard shutdown.
Use Hard Shutdown only when the VM is unresponsive. It cuts power without letting the guest flush anything to disk, so writes still in flight are lost and a drive can be left with a corrupted filesystem. Try Normal Shutdown first, and give it time to finish.