Connect a Remote GPU
Add an SSH-accessible Linux GPU host to Lévin™ Harness. Levin checks the machine, records its capabilities, and makes it available for remote plugin runtimes and Agent tasks you explicitly route to it.
Before you connect
| Check | Requirement |
|---|---|
| Reachable host | A Linux GPU machine that your Mac can reach over SSH, including any required VPN, bastion, firewall rule, or security group. |
| SSH account | An SSH login such as user@gpu-host, authenticated with a password, SSH agent, private key, or ~/.ssh/config entry. |
| Write access | The SSH user must be able to create files under the remote runtime root. Levin defaults to ~/.levin/plugins/envs. |
| GPU visibility | For NVIDIA GPU work, the host should make nvidia-smi available to the SSH user. Levin uses it to detect GPUs, the driver, CUDA, and memory. |
Before adding the device, verify the same SSH target from this Mac. This separates network or account issues from Levin's connection test.
Connect the device
- 01Open DevicesOpen Capabilities, select the Devices tab, then choose Add device to start a new device profile.
- 02Configure, test, and saveEnter the SSH target and port, choose password or SSH key/config authentication, and keep the default runtime root unless another writable directory is required. Test the connection, then select Check & Save.
Connection fields
| Field | What to enter |
|---|---|
| Device name | Optional. A recognizable label such as A100 lab. |
| SSH target | Enter the SSH login as username@host, for example ubuntu@192.168.1.50. If ~/.ssh/config already defines a host alias, enter the alias instead, for example a100-lab. |
| Port | Defaults to 22. Enter the port exposed by the SSH service. |
| Authentication | Password mode stores the password locally and hides it after saving. SSH key/config mode delegates authentication to your existing SSH setup. |
| Remote runtime root | The directory where Levin creates plugin environments, runtime data, releases, and worker files for this SSH account. |
Levin saves the device profile only after a live SSH test succeeds. Keep the default port and runtime root unless the host requires different values.
What Levin checks
A successful probe confirms SSH access and reports the capabilities visible to the login account. Optional tools that are missing appear as status details or warnings; Levin does not infer them.
| Check | Example result | Meaning |
|---|---|---|
| GPUs | 2 | GPU devices visible to the login account |
| Driver | 570.86 | NVIDIA driver reported by the host |
| CUDA | 12.8 | CUDA capability visible to the current driver |
| GPU memory | 80 GiB | Memory reported by the visible devices |
| uv | Available | Runtime package manager is ready to use |
Credentials stay with Levin Host. Device lists, agent tools, and task context receive sanitized profile details, never saved passwords or private key material.
Use the remote GPU
Remote GPU work is managed through the Lévin™ Harness plugin system. Configure the device once, then deploy a supported plugin to it. Once deployed, the plugin is ready to run from a conversation.
- 1
Deploy the plugin to your GPU
Open Capabilities → Plugins and choose a plugin that includes a Runtime. On its detail page, select the configured Remote GPU device, complete the deployment, then enable the plugin. Plugins without remote-runtime support remain on the local Mac.
- 2
Use the plugin in a conversation
Start a task and select the enabled plugin or one of its tools with
@. Levin runs supported plugin work through that deployment, so the GPU runtime, remote MCP services, and returned outputs stay attached to the plugin.
Troubleshooting
The connection times out
Confirm the host and port, connect the required VPN, and verify that your Mac can reach the SSH service. A blocked route or missing bastion setup is often the first thing to check.
Authentication is denied
Check the SSH username and selected authentication mode. For key/config mode, first make sure the same target works with your current SSH agent, key permissions, and ~/.ssh/config.
SSH connects but no GPU appears
Run nvidia-smi -L as the same SSH user. The NVIDIA driver and GPU devices must be visible to that account before Levin can report them.
Remote runtime setup fails
Verify that the runtime root is writable and that the host can reach required package, Git, and model sources. For uv bootstrap failures, also check remote DNS and proxy settings, then retry from the plugin details.