Skip to content

Develop in Cursor on your own GPU#

In this recipe you add your Linux workstation (with an NVIDIA or AMD GPU) to your workspace, make a development environment on it, and open it in Cursor on your laptop. Cursor's editor, terminal and debugger then run in a container on the workstation's GPU. Nothing listens on the workstation: SSH goes into the container through the connection the machine opens itself, so this works from anywhere, with the workstation behind NAT.

The same steps work for VS Code (Open in VS Code) and, from step 4, for JetBrains Gateway (Connect an editor).

Before you begin#

  • A Linux workstation with an NVIDIA or AMD GPU and its driver, and a laptop (Linux or macOS on Apple silicon) with Cursor and OpenSSH's client (ssh).
  • The editor or admin role in a workspace. Adding the machine is an organisation admin's.
  • astra on the laptop, signed in, working in that workspace (Install the CLI).
  • The container must reach the internet over HTTPS: Cursor installs its server inside it on first connect.

Below, <workstation> stands for your machine's name as the console shows it, and <org>/<workspace>@<cluster> for your workspace.

1. Add the workstation#

Follow Add a machine: Compute → Machines → Add machine, copy the command, run it on the workstation. Put it in a pool your workspace may use. When it is connected, open it and choose its Data location (Confirm): the environment's home drive is kept there, and without one the environment waits with Choose where to keep data on <workstation>.

2. Make the environment on it#

Pin it to the workstation, so it always finds its home: an environment's home drive is kept on each machine it runs on, one copy per machine.

  1. Open Hesperus → Environments and press New environment.
  2. Kind: Shell. Name: cursor-dev.
  3. Under Machine, choose <workstation>. It shows what it has free.
  4. Under Environment, choose PyTorch. Set GPUs to 1, CPU cores to 8 and Memory to 32 GB (or what your workstation has room for).
  5. Press Create and start. The environment's page opens.

$ astra env create cursor-dev --preset pytorch --gpus 1 --cpu 8 --memory 32G --machine <workstation>
cursor-dev is pending: `astra ssh cursor-dev` connects once it is ready (and waits for it)

With ASTRAEUS_TOKEN and API as in API:

$ curl -fsS -X POST "$API/notebook-runtimes" -H "Authorization: Bearer $ASTRAEUS_TOKEN" \
    -H 'content-type: application/json' \
    -d '{"metadata": {"name": "cursor-dev"}, "spec": {"kind": "shell", "image": "pytorch",
         "resources": {"cpu_cores": 8, "memory_bytes": 34359738368, "gpus": {"count": 1}},
         "placement": {"node": "<workstation>"}}}' | jq -r .status.state
Pending

The first start pulls the PyTorch image (about 4 GB for NVIDIA, 20.5 GB for AMD): a few minutes. It is Ready when its SSH server answers.

3. Check it from a terminal#

$ astra ssh cursor-dev -- python -c "import torch; print(torch.cuda.get_device_name(0))"
NVIDIA GeForce RTX 4090

(torch.cuda is also ROCm's on the AMD build.)

4. Write the SSH configuration#

Once, on the laptop, and again after you make another environment:

$ astra ssh config
/Users/you/.ssh/config: cursor-dev.<cluster>.<workspace>.<org>.astra
Connect with `ssh cursor-dev.<cluster>.<workspace>.<org>.astra`, or open it in VS Code or Cursor (Remote-SSH).

5. Open it in Cursor#

On the environment's page, under Connect, press Open in Cursor. Cursor opens a window connected to the host, in /content.

In Cursor, run Remote-SSH: Connect to Host… and pick cursor-dev.<cluster>.<workspace>.<org>.astra (it reads ~/.ssh/config). Then Open Folder → /content.

No API call: Cursor connects with ssh, through astra ssh --proxy.

The first connection installs Cursor's server in your home on the environment's drive (/content/home/root): it takes a minute, and is kept for the next time. In Cursor's terminal:

$ nvidia-smi --query-gpu=name,memory.total --format=csv,noheader
NVIDIA GeForce RTX 4090, 24564 MiB
$ pwd
/content/home/root

6. Work, and let it stop#

  • Keep projects under /content (for example /content/projects): the drive survives restarts; the rest of the container does not.
  • Install Python packages with pip install --user, so they land in your home on the drive (Install packages).
  • Close Cursor's window when you are done. With nobody connected for 60 minutes, the environment stops and the GPU is free. The next astra ssh or Cursor connection starts it again (astra waits for it).

If it does not work#

Symptom Cause and fix
Stays Pending with Choose where to keep data on <workstation> Choose the machine's Data location (step 1).
Stays Pending otherwise Press Why? beside its state: the GPU may be held by another runtime or run.
Cursor never finishes connecting the first time It cannot download its server: the container must reach the internet over HTTPS.
Cursor does not know the host Run astra ssh config again (it writes only environments you own).

More in Troubleshooting.