Remote Server

workflow no always-loaded rules -- loads on demand updated 2026-09-10

SSH access to a remote server. Adds /onremote command for health checks and remote command execution. Delegates to Haiku.

README

remote-server

SSH access to a configured remote server. Adds a /onremote command for health checks and remote command execution. All operations delegate to Haiku to minimize token usage.

What It Installs

File	Purpose
`~/.claude/commands/onremote.md`	`/onremote` slash command
`~/.claude/settings.json`	Adds `ssh`, `scp`, `rsync` to the allow list

Prerequisites

SSH key-based auth must be configured before using this module. Password prompts are not supported (Claude cannot enter them interactively).

# Copy your public key to the remote server (one-time setup)
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@remote-host

Usage

/onremote              # Health check: uptime, disk, active processes
/onremote "command"    # Run a command on the remote server

Examples:

/onremote "tail -n 50 ~/logs/app.log"
/onremote "df -h"
/onremote "ps aux | grep myapp"
/onremote "brew services restart myservice"

Manual Installation

If not using the CCGM installer, copy the files and substitute your values:

# In commands/onremote.md, replace:
# __REMOTE_HOST__  → your server's IP or hostname
# __REMOTE_USER__  → your SSH username
# __REMOTE_ALIAS__ → a friendly name for the server

Then add to ~/.ssh/config for convenience:

Host my-server
    HostName 192.168.1.100
    User myuser
    IdentityFile ~/.ssh/id_ed25519
    ServerAliveInterval 30
    ServerAliveCountMax 3

Will install

Path	Action	Target	Type
`commands/onremote.md`	→	`commands/onremote.md`	command
`settings.partial.json`	merge	`settings.json`	config

Dependencies

No dependencies.

Required by

No other module depends on this one.

Asks during install

Remote server hostname or IP address (e.g. 192.168.1.100 or server.tailscale.ts.net)?

Default:
SSH username on the remote server?

Default:
Short name for this server (used in status output, e.g. 'home-server')?

Default: remote-server

Included in presets

Install this module

Agent prompt

Recommended for agent users -- hands the whole install off to your assistant.

Fetch https://ccgm.dev/modules/remote-server.md and install this module into my Claude Code setup.

Native plugin marketplace

One command via the native plugin marketplace -- additive, does not merge settings.json.

claude plugin install remote-server@ccgm

The marketplace path is additive, not a replacement: it installs commands, agents, and skills as native plugin components, but it does not perform the bash installer's deep settings.json merge, and it does not write the always-loaded global CLAUDE.md context. Rules are only injected via an opt-in SessionStart hook rather than being auto-loaded. Use the bash installer when those pieces matter to you.

Manual, per file

Full control -- copy exactly the files you want from the sections below.

Files

command (1)

commands/onremote.md

Uses installer-substituted placeholders -- install via the bash installer, or fill in the __VARS__ after copying.

---
description: Run a task on __REMOTE_ALIAS__ by describing it in plain language
allowed-tools: Agent
---

# /onremote - Remote Server Task Runner

Use the Agent tool to execute this workflow on a cheaper model:

- **model**: haiku
- **description**: remote server task

Pass all workflow instructions and the input to the agent.

After the agent completes, relay its output to the user exactly as received.

---

## Workflow Instructions

Remote server: `__REMOTE_USER__@__REMOTE_HOST__` (__REMOTE_ALIAS__)

### Input

```
$ARGUMENTS
```

### If no arguments - Health Check

Run a health check and present a brief status report:

```bash
ssh __REMOTE_USER__@__REMOTE_HOST__ "uptime"
ssh __REMOTE_USER__@__REMOTE_HOST__ "df -h /"
ssh __REMOTE_USER__@__REMOTE_HOST__ "ps -u __REMOTE_USER__ -o pid,command | grep -Ev '/System/|/usr/lib|/usr/sbin|Contents/MacOS|\.framework' | grep -v PID"
```

Present as:

```
Remote: __REMOTE_ALIAS__ (__REMOTE_HOST__)
Uptime:  {uptime}
Disk:    {df /}

Active processes:
{process list}
```

### If arguments provided - Execute Task

The arguments are a natural language description of what to do on the remote server.

1. Interpret the intent
2. Determine what shell commands are needed to accomplish it
3. Run them via SSH: `ssh __REMOTE_USER__@__REMOTE_HOST__ "..."`
4. Report back in plain language - what you did and what the result was

Examples of how to interpret input:
- "check if myservice is running" → `ps aux | grep myservice`
- "how much disk space is left" → `df -h /`
- "restart ollama" → `brew services restart ollama` (or find the right command)
- "show the last 50 lines of the myservice log" → find the log file and tail it
- "what processes are using the most CPU" → `ps aux | sort -rk3 | head -10`

Use multiple SSH calls if needed. Interpret the task fully - do not ask clarifying questions unless the intent is genuinely ambiguous.

### Rules

- Output-only commands: never open an interactive shell (`ssh -t`).
- Chain multi-step work with `&&` in one SSH call instead of many round-trips.
- Prefer `tail -n 50 <log>` over verbose diagnostic tools.
- Do not run destructive operations (`rm`, `shutdown`, `kill -9`) without the user's explicit confirmation.

config (1)

settings.partial.json

Merged into ~/.claude/settings.json -- a fragment, not a replacement.

{
  "permissions": {
    "allow": [
      "Bash(ssh:*)",
      "Bash(scp:*)",
      "Bash(rsync:*)",
      "Bash(ssh-keyscan:*)",
      "Bash(ssh-copy-id:*)"
    ]
  }
}

View source on GitHub

Tags