ssh-connector
by ykinfohome7
README.md
<div align="center">
# π SSH Connector
**Work directly over SSH on many servers β from Claude and ChatGPT.**
Commands, interactive terminals, SFTP, tunnels, failover, events and a safe `sudo` password β no gateway in between.
[](CHANGELOG.md)
[](https://github.com/ykinfohome7/ssh-connector/actions/workflows/test.yml)
[](LICENSE)
[](https://github.com/ykinfohome7/ssh-connector/stargazers)
**English** Β· [ΠΡΠ»Π³Π°ΡΡΠΊΠΈ](README.bg.md)
[Install](#-install) Β· [Quick start](#-quick-start) Β· [Commands](docs/COMMANDS.md) Β· [Security](docs/SECURITY-STANDARDS.md) Β· [Changelog](CHANGELOG.md)
</div>
---
## β¨ What it does
| | |
|---|---|
| π₯οΈ **Many servers** | Debian and Red Hat, primary + fallback addresses, automatic failover, retries, keepalive |
| β¨οΈ **Real terminal** | Interactive shell with PTY that keeps state (`cd`, variables, running programs, Ctrl+C) |
| π **Safe sudo** | `sudo_password` β type it on a one-time page, take it from the profile, or generate it with *your* length and characters. Never in the chat |
| π **Files** | SFTP: list, read, write, upload, download, mkdir, remove, rename |
| π **Tunnels** | Local port forwarding, jump hosts (bastion) |
| π **Events** | Watch errors, crashes / OOM and logins without asking |
| π§© **Groups & snippets** | Run one command on a whole group; saved commands |
| π **Tailscale** | Status, devices, auth keys β and a permanent HTTPS address via Funnel |
| π§° **GitHub Codespaces** | List/status, wake and confirmation-protected stop via authenticated GitHub CLI; requires Codespaces permission |
| π **Help built in** | `help` lists all **48 commands** in BG and EN with a ready example |
## π¦ Install
Pick the way that fits you.
### Claude Code β plugin (recommended)
```bash
claude plugin marketplace add ykinfohome7/ssh-connector
claude plugin install ssh-connector@ykinfohome7-tools
```
Inside a session: `/plugin marketplace add ykinfohome7/ssh-connector`, then `/plugin install ssh-connector@ykinfohome7-tools`.
The first start creates a private virtualenv (~30 s, only once).
### ChatGPT Codex β plugin
```bash
codex plugin marketplace add ykinfohome7/ssh-connector
```
Then enable **ssh-connector** in the plugin list.
### ChatGPT / Claude apps (web, phone) β connector over HTTPS
They need a public HTTPS address. Use the [always-on server](#-always-on-server) or the [GitHub Actions session](#%EF%B8%8F-github-actions-session), then add the connector:
- **ChatGPT:** Settings β Apps & Connectors β Advanced β Developer mode β *Create* β URL `https://<host>/<TOKEN>/mcp`, no authentication.
- **Claude:** Settings β Connectors β *Add custom connector* β URL `https://<host>/mcp`, header `Authorization: Bearer <TOKEN>`.
After an update press **Refresh** on the connector to load new commands. With Tailscale Funnel the address stays the same.
### Download
- β¬οΈ **[Latest version (ZIP)](https://github.com/ykinfohome7/ssh-connector/archive/refs/heads/main.zip)**
- π·οΈ **[Releases](https://github.com/ykinfohome7/ssh-connector/releases)**
- `git clone https://github.com/ykinfohome7/ssh-connector`
### Manual MCP (no plugin)
```bash
git clone https://github.com/ykinfohome7/ssh-connector && cd ssh-connector
claude mcp add ssh -- sh $(pwd)/plugins/ssh-connector/bin/run.sh # Claude Code
codex mcp add ssh -- sh $(pwd)/plugins/ssh-connector/bin/run.sh # Codex
```
## π Quick start
1. Create `~/.ssh-connector/servers.yaml` from [`servers.example.yaml`](servers.example.yaml) (or set `SSH_CONNECTOR_CONFIG`). Needs `python3`.
2. Ask in plain words, e.g. *"show disk usage on all web servers"* β or call commands directly:
```json
{"tool": "server_test", "arguments": {"name": "web1"}}
{"tool": "run_command", "arguments": {"server": "web1", "command": "df -h"}}
{"tool": "help", "arguments": {}}
```
Full list with parameters and examples: **[docs/COMMANDS.md](docs/COMMANDS.md)**.
## π§° GitHub Codespaces (new in 1.3.3)
Three additional MCP tools: `codespace_status(name="")` lists available Codespaces or checks one; `codespace_start(name)` wakes an existing Codespace; `codespace_stop(name, confirm=true)` stops it only after explicit confirmation. They call the GitHub REST API through the authenticated `gh` CLI on the **connector host**, and need the GitHub `codespace` scope or the repository's Codespaces lifecycle admin permission. Tokens are not passed as tool arguments.
**Important:** a backend running inside a stopped Codespace cannot wake itself. To wake an offline Codespace, call these commands from an independently running connector host (or use GitHub directly).
## π sudo password (new in 1.3.3)
When a command needs `sudo`, the connector does not hang β it asks you to choose:
| Mode | What happens |
|---|---|
| `prompt` | You get a **one-time HTTPS link** (2 min). Type the password there; it is checked on the server |
| `profile` | Uses a preset value from an environment variable / GitHub Secret. Only its **name** is stored |
| `generate` | Random password β **you choose** length (16β128) and characters. Shown once; set on the server only after you press *"I saved it"* |
The password is never in the chat, in the command, in the logs or in the history. It reaches `sudo` over stdin.
## π Always-on server
Run once on one of your servers (e.g. from Termius):
```bash
curl -fsSL https://raw.githubusercontent.com/ykinfohome7/ssh-connector/main/install-server.sh | sudo bash
```
Installs a systemd service, an HTTPS tunnel, a token and an SSH key, and prints what to paste into Claude and ChatGPT. Show it again: `sudo ssh-connector-info`.
## βοΈ GitHub Actions session
An on-demand backend in GitHub Actions with a **permanent** address `https://ssh-connector.<tailnet>.ts.net` (Tailscale Funnel; fallback: Cloudflare quick tunnel).
- Start / restart: edit [`control/session`](control/session) (`start` + anything new on line 2) or *Actions β connector-session β Run workflow*.
- Stop: put `stop` in `control/session`.
- Status and address: [`control/status.md`](control/status.md).
Full setup (secrets, Tailscale, BGDB Codespaces): **[docs/GITHUB-SESSION.md](docs/GITHUB-SESSION.md)**.
## π‘οΈ Security
- Passwords, keys and tokens are **never** shown or stored in files β only environment-variable names and paths.
- SSH keys: **Ed25519**, RSA 4096 only for old systems, rotation every **40β90 days** (`credentials_rotate`).
- Requests without the token get `401`. Treat the token like an SSH key.
- Found a vulnerability? See **[SECURITY.md](SECURITY.md)**.
## π Documentation
| Document | English | ΠΡΠ»Π³Π°ΡΡΠΊΠΈ |
|---|---|---|
| Commands | [COMMANDS.md](docs/COMMANDS.md) | [COMMANDS.bg.md](docs/COMMANDS.bg.md) |
| Security standards | [SECURITY-STANDARDS.md](docs/SECURITY-STANDARDS.md) | [SECURITY-STANDARDS.bg.md](docs/SECURITY-STANDARDS.bg.md) |
| GitHub Actions session | [GITHUB-SESSION.md](docs/GITHUB-SESSION.md) | [GITHUB-SESSION.md](docs/GITHUB-SESSION.md) |
| Changelog | [CHANGELOG.md](CHANGELOG.md) | [CHANGELOG.md](CHANGELOG.md) |
| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) | [CONTRIBUTING.md](CONTRIBUTING.md) |
## β€οΈ Like it? Want something?
- β **Like it** β give the project a [Star](https://github.com/ykinfohome7/ssh-connector/stargazers).
- π‘ **Want a feature** β [open a feature request](https://github.com/ykinfohome7/ssh-connector/issues/new?template=feature_request.yml).
- π **Found a bug** β [report it](https://github.com/ykinfohome7/ssh-connector/issues/new?template=bug_report.yml).
## π License
[GPL-3.0](LICENSE) Β© ykinfohome7
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues