- Home
- Skills
- Agents & Orchestration
- Remote Workspace: Run AI Agents on Your Linux Server
Remote Workspace: Run AI Agents on Your Linux Server
Antigravity's Agent Manager and many other AI coding tools only work on **local folders**.
$2
Works with the AI Agents you already use
Remote Workspace: Run AI Agents on Your Linux Server
Example session with this skill installed
Set up a remote workspace between this Mac and my Ubuntu server 'dev-box'. The code should live in ~/dev on the server and mount to /Volumes/dev here.
- Read your context and instructions
- Compiled the remote workspace
✅ Remote workspace is live
devbox:~/Codes is mounted on your Mac at /Volumes/Codes, and every command I run now executes on devbox.
What I set up
| Where | Component | Status |
|---|---|---|
| devbox | Network watcher (mac-wakeup service): rings your Mac after network changes | ✅ active |
| devbox | remote-runner MCP tool in ~/.local/share/remote-runner | ✅ installed |
| devbox | Samba share [Codes] → /home/manav/Codes (you set the SMB password) | ✅ running |
| Mac | Reconciler ~/.scripts/auto-mount-smb.sh + 2 launchd jobs | ✅ loaded |
| Mac | Doorbell on TCP 4455 (Tailscale-only) | ✅ listening |
| Mac | Shell safety net in ~/.zshenv | ✅ active |
| Mac | Toggle Workspace.app on your Desktop | ✅ created |
| Claude Code | remote-runner MCP server | ✅ connected |
Verification
$ ~/.scripts/auto-mount-smb.sh --status
Remote Workspace Diagnostics
────────────────────────────
Network OK
SMB 445 OK
Mount OK
Filesystem OK
Verify dir OK
Background Last State: HEALTHY, Fails: 0
$ ssh devbox "nc -z -w 2 100.101.20.5 4455 && echo answered"
answered
run_on_server(cwd="/Volumes/Codes", command=["uname", "-sr"])
exit code: 0 (ran on server in /home/manav/Codes)
Linux 6.8.0-45-generic
$ cd /Volumes/Codes && RW_DRYRUN=1 npm -v
[remote-workspace] running on server: npm -v
ssh devbox cd 'Codes' && 'npm' '-v'
I also added CLAUDE.md to the root of /Volumes/Codes, so every new session runs commands on devbox.
Next steps
- Open
/Volumes/Codes/<project>in your editor as usual. - Ask me to "start the dev server". I'll run it in the background on devbox, and you can open
http://localhost:3000.
3. Done for the day? Double-click Toggle Workspace → Turn OFF (it ejects safely).
4. If it ever stops working, say "my remote workspace is broken" and I'll run the read-only diagnostic first.
Connects securely to your tools. The creator never sees your data.
About this skill
Your agent edits locally. Your server does the heavy work.
Antigravity's Agent Manager and many other AI coding tools only work on local folders. There's no "connect to remote host" button. So npm install, builds, Docker and test runs all happen on your laptop, which heats up and slows down.
This skill makes a folder on your Linux server look and behave like a local folder, and keeps it that way. Your agent sets everything up, checks that it works, and fixes it later if something breaks.
What you get
- 📁 One copy of your code, on the server: mounted on the Mac with macOS's built-in SMB client. No macFUSE, no sync conflicts, no
node_modulesduplicated across machines. - 🖥️ Every command runs on the server: the
remote-runnerMCP tool gives your agentrun_on_server,start_background,read_background,stop_backgroundandlist_background. Commands go as argv lists or plain bash, so there are nossh '...'quoting bugs. - 🛡️ A safety net: if your agent forgets its rules mid-session and types
npm run buildon the Mac inside the share, the command is forwarded to the server anyway. - 🔁 Self-healing connection: the server "rings a doorbell" on your Mac when its network comes back. The share is remounted and verified within seconds, with no polling loop. Frozen mounts, ghost
Codes-1folders and missed events are all handled. - 🌐 Previews just work:
localhost:3000on your Mac opens the dev server running on the Linux box. - 🧊 Tiny footprint: measured at 0.25 s of total CPU in 5¾ hours for the Mac-side listener.
- 🩺 Built-in doctor: a read-only health check plus a symptom-to-fix table, so your agent can diagnose a broken workspace before touching anything.
One skill, four jobs
| Ask your agent to… | It will… |
|---|---|
| "Set up my remote workspace" | Check prerequisites, run the server and Mac installers, connect itself to the MCP tool, verify every piece |
| "Just let me run commands on my server" | Install only the MCP tool on any Linux box (no Mac or SMB needed) |
| Work in the mounted folder | Follow server-only rules: background dev servers, no crawling node_modules |
| "My workspace stopped working" | Run the read-only diagnostic, match the symptom, and propose the smallest fix |
Safe by design
- The agent asks before any
sudo, firewall change, edit to your shell profile or MCP config, force-unmount, or deletion. - Passwords are never typed into chat. Keychain and
sudoprompts stay with you. - SMB and SSH are meant to run only over Tailscale, and the doorbell ignores everything that doesn't come from a Tailscale address.
- Full uninstall instructions are included.
Requirements
macOS (with Xcode Command Line Tools) · Ubuntu server with SSH · Tailscale on both · SSH key login · Python 3.10+ on the server
Built and used daily with Google Antigravity. It works with any agent that edits local folders and supports MCP.
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Agents & Orchestration.
Requires Tailscale on both machines. Server must be Linux (Ubuntu preferred). Mac requires Xcode Command Line Tools. SMB password must be manually saved to Keychain once.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 16 days ago
- Accounts
Google Account
- Software
- Xcode Command Line ToolsUbuntuorDebian serverOpenSSH
Tailscale
Python 3.10+tmuxSamba
node
Git
Tailscale goes on both machines. OpenSSH, Python, tmux and Samba go on the Linux server.
Permissions
Allowed Hosts
File Scopes
Installs small background helpers on the Mac (two launchd jobs) and the server (one systemd user service), plus an MCP server that runs on the user's own Linux machine over SSH. The agent asks before any sudo, firewall, shell-profile or MCP-config change, and before force-unmounts or deletions. No passwords are handled in chat; SMB credentials stay in the macOS Keychain. Nothing is sent to third parties. All traffic stays between the user's own machines over Tailscale. Full uninstall steps are included.