@koller-nexus/vps-ops-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 koller-nexus / William Koller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# vps-ops-mcp
+
+Servidor [MCP](https://modelcontextprotocol.io) (stdio) que opera uma VPS por SSH. O Cursor e o Codex sobem o processo com `bun` e chamam ferramentas de leitura (saúde do host, debug Unix, Docker, Compose, Swarm, firewall) e de mutação (restart, stop, start, prune), com confirmação explícita nas mutações.
+
+O transporte é stdio. Não abra o servidor como um processo longo na mão: o cliente (Cursor ou Codex) é quem o inicia.
+
+## Contribuição
+
+Veja [CONTRIBUTING.md](./CONTRIBUTING.md) (branches, pull requests, verificação) e [ISSUE.md](./ISSUE.md) (como abrir uma issue).
+
+## Requisitos
+
+- [Bun](https://bun.sh)
+- Python 3 (usado pelos scripts de registro)
+- Cliente OpenSSH (`ssh` no `PATH`)
+- Chave privada SSH legível, com acesso ao usuário remoto
+- No host remoto: Docker (e `sudo -n` para `ufw`, `fail2ban`, `sshd -T`, `ss` e `dmesg`, se for usar essas ferramentas)
+
+## Configuração
+
+```bash
+cp .env.example .env
+```
+
+Edite `.env`. O arquivo está no `.gitignore`.
+
+| Variável | Obrigatória | Padrão | Função |
+| --- | --- | --- | --- |
+| `VPS_SSH_KEY_PATH` | sim | — | Caminho absoluto da chave privada. O processo recusa subir se o arquivo não existir ou não for legível. |
+| `VPS_HOST` | não | `vps.example.invalid` | Host SSH (placeholder; set your own host). |
+| `VPS_USER` | não | `ubuntu` | Usuário SSH. |
+| `VPS_PORT` | não | `22` | Porta SSH. |
+| `VPS_COMPOSE_DIR` | não | — | Diretório absoluto do Compose **na VPS**. Sem isso, as ferramentas de Compose exigem o argumento `dir`. |
+| `VPS_COMMAND_TIMEOUT_MS` | não | `30000` | Timeout do comando remoto. Estouro devolve `exit_code` 124. |
+| `VPS_LOG_MAX_BYTES` | não | `200000` | Teto de `stdout`/`stderr`. O excesso é cortado e `truncated` fica `true`. |
+| `VPS_ALLOW_MUTATIONS` | não | `true` | `false`, `0`, `no` ou `off` desliga todas as mutações. |
+| `VPS_SSH_KEY_PASSPHRASE` | não | — | Evite. Prefira `ssh-agent`. Os scripts de registro **não** copiam esta variável para o cliente. |
+
+`VPS_COMPOSE_DIR` precisa ser absoluto e casar com `/^[a-zA-Z0-9/_.-]+$/` (começa com `/`).
+
+## Instalação
+
+```bash
+bun install
+```
+
+Pacote npm (requer [Bun](https://bun.sh); o registry MCP aponta para este artefato):
+
+```bash
+bunx @koller-nexus/vps-ops-mcp
+```
+
+Nome no MCP Registry: `io.github.koller-nexus/vps-ops-mcp`. O registry só publica metadados depois do pacote existir no npm público.
+
+## Registrar nos clientes
+
+Os scripts gravam a configuração do MCP com as variáveis **já exportadas no shell**. Eles não leem `.env` sozinhos. Sem exportar, entram os padrões do script (host, usuário, porta e um caminho de chave local).
+
+Faça isto uma vez, na raiz do repositório, antes de cada script:
+
+```bash
+set -a
+source .env
+set +a
+```
+
+Cada execução faz backup do arquivo de destino (`*.bak.YYYYMMDDHHMMSS`) e substitui só o servidor `vps-ops`. Os outros servidores MCP permanecem.
+
+Variáveis opcionais dos scripts:
+
+| Variável | Padrão | Função |
+| --- | --- | --- |
+| `MCP_PROJECT_DIR` | raiz deste repositório | De onde sai o caminho de `src/index.ts`. |
+| `CURSOR_MCP_JSON` | `~/.cursor/mcp.json` | Arquivo do Cursor a atualizar. |
+| `CODEX_CONFIG` | `~/.codex/config.toml` | Arquivo do Codex a atualizar. |
+
+`VPS_COMPOSE_DIR` só entra na config do cliente se estiver definida e não vazia.
+
+### Cursor
+
+Registro global (vale em qualquer workspace):
+
+```bash
+./scripts/register-cursor-mcp.sh
+```
+
+O script escreve em `~/.cursor/mcp.json`, no formato:
+
+```json
+{
+  "mcpServers": {
+    "vps-ops": {
+      "command": "bun",
+      "args": ["/caminho/absoluto/vps-ops-mcp/src/index.ts"],
+      "env": {
+        "VPS_HOST": "seu.host",
+        "VPS_USER": "ubuntu",
+        "VPS_PORT": "22",
+        "VPS_SSH_KEY_PATH": "/caminho/absoluto/chave",
+        "VPS_COMMAND_TIMEOUT_MS": "30000",
+        "VPS_LOG_MAX_BYTES": "200000",
+        "VPS_ALLOW_MUTATIONS": "true"
+      }
+    }
+  }
+}
+```
+
+Para limitar a um projeto, aponte o script para o `mcp.json` desse projeto:
+
+```bash
+CURSOR_MCP_JSON="/caminho/do/projeto/.cursor/mcp.json" ./scripts/register-cursor-mcp.sh
+```
+
+Depois: recarregue a janela do Cursor (Command Palette → **Developer: Reload Window**) ou reinicie o servidor em **Settings → MCP**. O servidor aparece como `vps-ops`.
+
+### Codex
+
+```bash
+./scripts/register-codex-mcp.sh
+```
+
+O script escreve em `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.vps-ops]
+command = "bun"
+args = ["/caminho/absoluto/vps-ops-mcp/src/index.ts"]
+
+[mcp_servers.vps-ops.env]
+VPS_HOST = "seu.host"
+VPS_USER = "ubuntu"
+VPS_PORT = "22"
+VPS_SSH_KEY_PATH = "/caminho/absoluto/chave"
+VPS_COMMAND_TIMEOUT_MS = "30000"
+VPS_LOG_MAX_BYTES = "200000"
+VPS_ALLOW_MUTATIONS = "true"
+```
+
+Feche e abra a sessão do Codex para ele reler o `config.toml`. Se o CLI estiver no `PATH`, `codex mcp list` deve mostrar `vps-ops`.
+
+## Verificar
+
+Teste o SSH fora do MCP (os mesmos flags que o servidor usa):
+
+```bash
+ssh -i "$VPS_SSH_KEY_PATH" \
+  -o BatchMode=yes \
+  -o IdentitiesOnly=yes \
+  -o StrictHostKeyChecking=accept-new \
+  -p "${VPS_PORT:-22}" \
+  "${VPS_USER}@${VPS_HOST}" \
+  'uname -a'
+```
+
+No Cursor ou no Codex, peça para chamar `vps_ping`. A resposta é JSON:
+
+```json
+{
+  "exit_code": 0,
+  "stdout": "...",
+  "stderr": "",
+  "duration_ms": 0,
+  "truncated": false
+}
+```
+
+`exit_code` diferente de 0 marca a chamada como erro no MCP. Se o processo sair na hora com `VPS_SSH_KEY_PATH is required` ou `missing or unreadable`, a variável não chegou no `env` do cliente — rode o script de registro de novo com o `.env` exportado.
+
+## Ferramentas
+
+Toda chamada devolve `exit_code`, `stdout`, `stderr`, `duration_ms` e `truncated`.
+
+### Leitura
+
+| Ferramenta | Argumentos | O que faz |
+| --- | --- | --- |
+| `vps_ping` | — | `uname -a`, `uptime`, `hostname`. |
+| `vps_resources` | — | `df -h`, `free -h`, load average. |
+| `vps_journal` | `unit`, `n?` (1–500, padrão 100) | `journalctl -u`. Unidade da lista (`docker`, `sshd`, `fail2ban`, `ufw`, `cron`, com ou sem `.service`) ou um nome seguro terminado em `.service`. |
+| `docker_ps` | — | `docker ps -a` em JSON lines. |
+| `docker_inspect` | `name` | `docker inspect`. |
+| `docker_logs` | `name`, `n?` (1–1000, padrão 200), `since?` | `docker logs --tail --timestamps`. |
+| `docker_stats` | — | `docker stats --no-stream`. |
+| `docker_service_ls` | — | `docker service ls` em JSON lines (Swarm). |
+| `docker_node_ls` | — | `docker node ls` em JSON lines (Swarm). |
+| `compose_ps` | `dir?` | `docker compose ps` em `dir` ou `VPS_COMPOSE_DIR`. |
+| `host_listen` | — | `ss -lntup` (`sudo -n`, senão sem sudo). |
+| `host_failed_units` | — | `systemctl --failed --no-pager --full`. |
+| `host_top` | — | Top 30 processos por memória (`ps aux --sort=-%mem`). |
+| `host_dmesg` | `n?` (1–200, padrão 100) | `dmesg -T` + `tail` (`sudo -n`, senão sem sudo). |
+| `host_firewall` | — | `ufw status verbose` (`sudo -n`, senão sem sudo). |
+| `host_fail2ban` | `jail?` | `fail2ban-client status` (`sudo -n`). |
+| `ssh_hardening_check` | — | `sshd -T` filtrado: porta, password, root login, pubkey. |
+
+Nomes de container, serviço, imagem e jail precisam casar com `^[a-zA-Z0-9][a-zA-Z0-9_.-]*$`.
+
+### Mutação
+
+Exigem `confirm: true`. Com `VPS_ALLOW_MUTATIONS=false`, todas são recusadas.
+
+| Ferramenta | Argumentos extra | Comando remoto |
+| --- | --- | --- |
+| `docker_restart` | `name` | `docker restart` |
+| `docker_stop` | `name` | `docker stop` |
+| `docker_start` | `name` | `docker start` |
+| `compose_up` | `dir?`, `services?` | `docker compose up -d` |
+| `compose_restart` | `dir?`, `services?` | `docker compose restart` |
+| `compose_pull_up` | `dir?`, `services?` | `docker compose pull` e depois `up -d` |
+| `docker_rm` | `name`, `force_name` | `docker rm -f`. `force_name` tem de ser igual a `name`. |
+| `disk_cleanup_docker` | `confirm_volumes?` | `docker system prune -f`. Volumes só com `confirm_volumes: true`. |
+
+## Segurança
+
+- Comandos remotos são fixos. Não existe ferramenta de shell livre.
+- Argumentos de nome e caminho passam por allowlist e são citados no shell.
+- SSH usa `BatchMode=yes`, `IdentitiesOnly=yes` e `StrictHostKeyChecking=accept-new`.
+- Mutação sem `confirm: true` é recusada. `docker_rm` pede o nome duas vezes. Prune de volumes pede `confirm_volumes: true`.
+- Para um cliente só de leitura, registre com `VPS_ALLOW_MUTATIONS=false`.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@koller-nexus/vps-ops-mcp",
+  "version": "0.1.0",
+  "description": "Stdio MCP server that inspects and (with confirmation) mutates one VPS over SSH.",
+  "mcpName": "io.github.koller-nexus/vps-ops-mcp",
+  "module": "src/index.ts",
+  "type": "module",
+  "bin": {
+    "vps-ops-mcp": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "server.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/koller-nexus/vps-ops-mcp.git"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "bun build src/index.ts --outdir dist --target bun"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^7"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.6.5"
+  }
+}

package/server.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.koller-nexus/vps-ops-mcp",
+  "title": "VPS Ops",
+  "description": "Stdio MCP server that inspects and (with confirmation) mutates one VPS over SSH.",
+  "repository": {
+    "url": "https://github.com/koller-nexus/vps-ops-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "websiteUrl": "https://github.com/koller-nexus/vps-ops-mcp",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@koller-nexus/vps-ops-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "bunx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "VPS_SSH_KEY_PATH",
+          "description": "Absolute path to a readable SSH private key",
+          "isRequired": true,
+          "isSecret": true,
+          "format": "filepath"
+        },
+        {
+          "name": "VPS_HOST",
+          "description": "SSH hostname of the single target VPS",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "VPS_USER",
+          "description": "SSH username",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "VPS_PORT",
+          "description": "SSH port",
+          "isRequired": false,
+          "format": "number"
+        },
+        {
+          "name": "VPS_COMPOSE_DIR",
+          "description": "Absolute Compose directory on the remote host",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "VPS_COMMAND_TIMEOUT_MS",
+          "description": "Remote command timeout in milliseconds",
+          "isRequired": false,
+          "format": "number"
+        },
+        {
+          "name": "VPS_LOG_MAX_BYTES",
+          "description": "Stdout/stderr byte cap for remote commands",
+          "isRequired": false,
+          "format": "number"
+        },
+        {
+          "name": "VPS_ALLOW_MUTATIONS",
+          "description": "Set false to reject every mutation tool",
+          "isRequired": false,
+          "format": "boolean"
+        },
+        {
+          "name": "VPS_SSH_KEY_PASSPHRASE",
+          "description": "Optional key passphrase; prefer ssh-agent instead",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        }
+      ]
+    }
+  ]
+}

package/src/agents-md.test.ts

@@ -0,0 +1,125 @@
+import { expect, test } from "bun:test";
+import { resolve } from "node:path";
+
+const agentsPath = resolve(import.meta.dir, "..", "AGENTS.md");
+
+const REQUIRED_HEADINGS = [
+  "# VPS Ops MCP Agent Construction Guide",
+  "## Purpose",
+  "## Authority",
+  "## Skill routing",
+  "## Product shape",
+  "## Operator capabilities",
+  "## Proof",
+  "## Delivery and operations",
+  "## Public release",
+  "## Construction sequence",
+  "## Anti-patterns",
+  "## Human setup",
+] as const;
+
+const US1_TOKENS = [
+  "constitution wins",
+  "mcp-builder",
+  ".agents/skills/mcp-builder/SKILL.md",
+  "devops-engineer",
+  ".agents/skills/devops-engineer/SKILL.md",
+  "opensource-pipeline",
+  ".agents/skills/opensource-pipeline/SKILL.md",
+  "speckit-",
+  "test-driven-development",
+  "verification-before-completion",
+  "client-launched",
+  "README.md",
+] as const;
+
+const US2_TOKENS = [
+  "vps_",
+  "confirm:true",
+  "VPS_ALLOW_MUTATIONS",
+  "readOnlyHint",
+  "destructiveHint",
+  "idempotentHint",
+  "openWorldHint",
+  "next corrective",
+  "bun test",
+  "timeout",
+  "byte cap",
+] as const;
+
+const US3_TOKENS = [
+  "explicit human approval",
+  "rollback",
+  "MUST NOT apply undocumented host",
+] as const;
+
+const US4_TOKENS = ["sanitizer", "staging", "MUST NOT commit secrets"] as const;
+
+async function loadAgents(): Promise<string> {
+  const file = Bun.file(agentsPath);
+  if (!(await file.exists())) {
+    throw new Error("AGENTS.md is missing");
+  }
+  return file.text();
+}
+
+function sectionBetween(text: string, start: string, end: string): string {
+  const from = text.indexOf(start);
+  const to = text.indexOf(end);
+  expect(from).toBeGreaterThan(-1);
+  expect(to).toBeGreaterThan(from);
+  return text.slice(from, to);
+}
+
+function expectTokens(text: string, tokens: readonly string[]): void {
+  for (const token of tokens) {
+    expect(text.includes(token), token).toBe(true);
+  }
+}
+
+test("AGENTS.md exists", async () => {
+  expect(await Bun.file(agentsPath).exists()).toBe(true);
+});
+
+test("AGENTS.md headings appear in contract order", async () => {
+  const text = await loadAgents();
+  let last = -1;
+  for (const heading of REQUIRED_HEADINGS) {
+    const idx = text.indexOf(heading);
+    expect(idx).toBeGreaterThan(last);
+    last = idx;
+  }
+});
+
+test("AGENTS.md includes US1 construction tokens", async () => {
+  expectTokens(await loadAgents(), US1_TOKENS);
+});
+
+test("AGENTS.md includes US2 operator and proof tokens", async () => {
+  expectTokens(await loadAgents(), US2_TOKENS);
+});
+
+test("Proof section forbids a live host as automated proof", async () => {
+  const proof = sectionBetween(
+    await loadAgents(),
+    "## Proof",
+    "## Delivery and operations"
+  );
+  expect(proof.includes("MUST NOT")).toBe(true);
+  expect(proof.includes("live host")).toBe(true);
+});
+
+test("AGENTS.md includes US3 delivery tokens", async () => {
+  expectTokens(await loadAgents(), US3_TOKENS);
+});
+
+test("AGENTS.md includes US4 public-release tokens", async () => {
+  expectTokens(await loadAgents(), US4_TOKENS);
+});
+
+test("AGENTS.md has no live secrets or host identity", async () => {
+  const text = await loadAgents();
+  expect(text).not.toMatch(/\b\d{1,3}(?:\.\d{1,3}){3}\b/);
+  expect(text).not.toMatch(/\/Users\/\S+\.(pem|key)|BEGIN (OPENSSH |RSA )?PRIVATE KEY/i);
+  expect(text).not.toMatch(/VPS_SSH_KEY_PASSPHRASE=\S+/);
+});

package/src/config.test.ts

@@ -0,0 +1,101 @@
+import { afterEach, test, expect } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadConfig } from "./config.js";
+
+const KEYS = [
+  "VPS_HOST",
+  "VPS_USER",
+  "VPS_PORT",
+  "VPS_SSH_KEY_PATH",
+  "VPS_COMPOSE_DIR",
+  "VPS_SSH_KEY_PASSPHRASE",
+  "VPS_COMMAND_TIMEOUT_MS",
+  "VPS_LOG_MAX_BYTES",
+  "VPS_ALLOW_MUTATIONS",
+] as const;
+
+const saved = new Map<string, string | undefined>();
+
+function snapshotEnv(): void {
+  for (const key of KEYS) {
+    saved.set(key, process.env[key]);
+    delete process.env[key];
+  }
+}
+
+function restoreEnv(): void {
+  for (const key of KEYS) {
+    const value = saved.get(key);
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+}
+
+function writeKeyFile(): string {
+  const dir = mkdtempSync(join(tmpdir(), "vps-ops-"));
+  const path = join(dir, "id_test");
+  writeFileSync(path, "dummy-key\n", { mode: 0o600 });
+  return path;
+}
+
+afterEach(() => {
+  restoreEnv();
+});
+
+test("requires VPS_SSH_KEY_PATH", () => {
+  snapshotEnv();
+  expect(() => loadConfig()).toThrow(/VPS_SSH_KEY_PATH is required/);
+});
+
+test("rejects unreadable SSH key path", () => {
+  snapshotEnv();
+  process.env.VPS_SSH_KEY_PATH = "/tmp/vps-ops-missing-key";
+  expect(() => loadConfig()).toThrow(/missing or unreadable/);
+});
+
+test("loads defaults when only the key path is set", () => {
+  snapshotEnv();
+  const keyPath = writeKeyFile();
+  process.env.VPS_SSH_KEY_PATH = keyPath;
+
+  const config = loadConfig();
+  expect(config.host).toBe("vps.example.invalid");
+  expect(config.user).toBe("ubuntu");
+  expect(config.port).toBe(22);
+  expect(config.sshKeyPath).toBe(keyPath);
+  expect(config.commandTimeoutMs).toBe(30_000);
+  expect(config.logMaxBytes).toBe(200_000);
+  expect(config.allowMutations).toBe(true);
+  expect(config.composeDir).toBeUndefined();
+});
+
+test("honors overrides and treats off as mutations disabled", () => {
+  snapshotEnv();
+  const keyPath = writeKeyFile();
+  process.env.VPS_SSH_KEY_PATH = keyPath;
+  process.env.VPS_HOST = "10.0.0.8";
+  process.env.VPS_USER = "ops";
+  process.env.VPS_PORT = "2222";
+  process.env.VPS_COMPOSE_DIR = "/opt/stack";
+  process.env.VPS_COMMAND_TIMEOUT_MS = "5000";
+  process.env.VPS_LOG_MAX_BYTES = "1000";
+  process.env.VPS_ALLOW_MUTATIONS = "off";
+
+  const config = loadConfig();
+  expect(config.host).toBe("10.0.0.8");
+  expect(config.user).toBe("ops");
+  expect(config.port).toBe(2222);
+  expect(config.composeDir).toBe("/opt/stack");
+  expect(config.commandTimeoutMs).toBe(5000);
+  expect(config.logMaxBytes).toBe(1000);
+  expect(config.allowMutations).toBe(false);
+});
+
+test("rejects invalid integer env", () => {
+  snapshotEnv();
+  process.env.VPS_SSH_KEY_PATH = writeKeyFile();
+  process.env.VPS_PORT = "-1";
+  expect(() => loadConfig()).toThrow(/Invalid VPS_PORT/);
+});

package/src/config.ts

@@ -0,0 +1,66 @@
+import { accessSync, constants } from "node:fs";
+
+export interface VpsConfig {
+  host: string;
+  user: string;
+  port: number;
+  sshKeyPath: string;
+  sshKeyPassphrase?: string;
+  composeDir?: string;
+  commandTimeoutMs: number;
+  logMaxBytes: number;
+  allowMutations: boolean;
+}
+
+function envBool(name: string, defaultValue: boolean): boolean {
+  const v = process.env[name];
+  if (v === undefined || v === "") return defaultValue;
+  return !["0", "false", "no", "off"].includes(v.toLowerCase());
+}
+
+function envInt(name: string, defaultValue: number): number {
+  const v = process.env[name];
+  if (v === undefined || v === "") return defaultValue;
+  const n = Number.parseInt(v, 10);
+  if (!Number.isFinite(n) || n < 0) {
+    throw new Error(`Invalid ${name}=${v}; expected non-negative integer`);
+  }
+  return n;
+}
+
+export function loadConfig(): VpsConfig {
+  const host = process.env.VPS_HOST?.trim() || "vps.example.invalid";
+  const user = process.env.VPS_USER?.trim() || "ubuntu";
+  const port = envInt("VPS_PORT", 22);
+  const sshKeyPath = process.env.VPS_SSH_KEY_PATH?.trim();
+
+  if (!sshKeyPath) {
+    throw new Error(
+      "VPS_SSH_KEY_PATH is required. Set it to the absolute path of your SSH private key."
+    );
+  }
+
+  try {
+    accessSync(sshKeyPath, constants.R_OK);
+  } catch {
+    throw new Error(
+      `VPS_SSH_KEY_PATH is missing or unreadable: ${sshKeyPath}`
+    );
+  }
+
+  const composeDir = process.env.VPS_COMPOSE_DIR?.trim() || undefined;
+  const sshKeyPassphrase =
+    process.env.VPS_SSH_KEY_PASSPHRASE?.trim() || undefined;
+
+  return {
+    host,
+    user,
+    port,
+    sshKeyPath,
+    sshKeyPassphrase,
+    composeDir,
+    commandTimeoutMs: envInt("VPS_COMMAND_TIMEOUT_MS", 30_000),
+    logMaxBytes: envInt("VPS_LOG_MAX_BYTES", 200_000),
+    allowMutations: envBool("VPS_ALLOW_MUTATIONS", true),
+  };
+}