Claude Code for Remote/GPU Workflows
A CLI tool doesn't care whether it's running on your laptop or a rack of A100s three hops away.
Intermediate
TopNotchNote
Notes that matter
the actual setup
There's no special "remote mode" to configure — Claude Code is a normal terminal
program, so it runs exactly the same way any other CLI tool does once you're SSHed into
the box that actually has the GPUs. That's also its biggest advantage over a
GUI-only assistant for this exact workflow: no separate remote-desktop or
VS Code Remote-SSH layer required, just a
terminal session.
surviving a dropped connection
An SSH connection dying kills whatever was attached to that terminal, including a
running Claude Code session, unless something keeps the session alive independently. Start
Claude Code inside a tmux session on the remote host, and a
dropped connection becomes a non-event — reattach and the session (and anything it was
running) is exactly where you left it.
tmux new -s claude-work | https://topnotchnote.com/os/tmux.html | starts a named session to run Claude Code inside, on the remote host |'rgw_tmux1'
tmux attach -t claude-work | | reconnects to that same session after an SSH drop, from any new connection |'rgw_tmux2'
headless / non-interactive use
Beyond an interactive terminal session, the
-p flag runs Claude Code
non-interactively: feed it a prompt, let it run to completion, consume the result. That's
the shape that fits inside a CI pipeline or a scheduled job on a training server — no
human watching, a defined task, a result to check when it's done.
# nightly: check overnight training logs, alert only if something looks wrong
tail -500 /var/log/training/run-$(date +%F).log \
| claude -p "Flag anything that looks like a real training failure, not routine warnings"
pushing tasks from your phone
Since terminal, desktop, and web sessions all share the same underlying engine, a task
doesn't have to start where you finish it — kick off a long training-adjacent job from the
web or mobile app, then pull the same session into your terminal later once you're back at
the GPU box, instead of re-describing what you already asked for.
where this actually helps on a gpu box
| Task | Why do it through Claude Code, remotely |
|---|---|
| Debugging a training run that's failing on the actual GPU node | the error, the logs, and the environment are all local to that machine — no copying anything back |
| Profiling a kernel | the profiler output (nsight, rocprof) is huge and machine-specific; better read where it's generated |
| Iterating on a long-running experiment | headless mode can kick off a scripted change-and-rerun loop without you staying attached |
| Nightly log triage across a fleet of nodes | a scheduled headless run per node beats a human scrolling through logs every morning |
related topics
tmux Cheat Sheet — the session-persistence layer this whole workflow depends on.
VS Code Remote Development — the GUI-editor equivalent, for when you want a full editor rather than just a terminal.
GPU Optimization — the kind of profiling work this remote setup is usually built to support.
VS Code Remote Development — the GUI-editor equivalent, for when you want a full editor rather than just a terminal.
GPU Optimization — the kind of profiling work this remote setup is usually built to support.