xpert2404/server-use

Orchestrate and manage your servers with AI. Keep SSH credentials local.
server-use gives Claude Code, Codex and other AI agents practical SSH access to your own servers without needing
your login passwords or private key contents in chat or model tool arguments. Connect locally once, then let the
agent inspect a VPS, run fleet commands, manage jobs and cron, or deploy an application with rollback.
It is a standalone, free and open-source project: MIT, no server-use accounts, no hosted control plane, no paid
tiers and no telemetry. A local daemon pools SSH connections; a CLI, portable skills and a local stdio MCP server
let you use the same inventory from different agents.
Claude Code and Codex plugin installs are verified. Other agents, including Cursor, Gemini CLI, OpenCode and
Hermes, can integrate through a shell or a local stdio MCP connection; their individual client setups have not
all been tested. NEXUS Harness is one optional integration.
No remote agent or package is required: servers need sshd and a POSIX shell. Features such as jobs, cron,
monitoring and deploys create their own managed files, listed below.
**Latest release: 0.2.0, alpha.** Client: Windows,
macOS or Linux with Node.js 22+. Real-sshd acceptance covers Debian/Ubuntu; other Linux distributions are
compatibility targets, not claimed acceptance results. Not on the npm registry yet:
npm i -g github:xpert2404/server-use installs the current GitHub source. See acceptance evidence.
Quickstart
Connect a server privately
Run this in **your own terminal**, outside the agent's chat and shell tool:
--ask reads the password without echoing it. server-use installs this machine's SSH key and verifies a fresh
key login. Compare the printed host-key fingerprint with your server provider's console. If SSH key access
already works, omit --ask, or use --key /path/to/key; never paste the private key contents into chat.
Discover existing keys with server-use keys or import your hosts with server-use import ssh-config --dry-run, then server-use import ssh-config. Encrypted keys accept --ask-passphrase or --passphrase-stdin during local onboarding. Native tools expose metadata and paths without returning private keys.
Then install the integration for your agent below. The agent uses the stored local access; it does not need
the login password. Passwords are kept locally only when needed for sudo, failed key setup or explicit retention.
Claude Code
The plugin adds the skills (/server-use:server-use, add-server, deploy-repo, server-cron, server-doctor)
and puts server-use on the Bash tool's PATH (bin/server-use for Git Bash, bin/server-use.cmd for cmd). Then
ask for what you want:
> Check web1, show me what needs attention, and inspect the application logs.
Codex
The verified Codex 0.160 setup uses the plugin for skills and a global CLI install because that plugin does not
add bin/ to PATH. In that version's default workspace-write sandbox, shell commands cannot reach the servers;
the local MCP process runs outside that sandbox, which is why the last line registers it. These are recorded
results for that version, rather than a promise about every client's sandbox. For codex exec without a person to approve tool
calls, add default_tools_approval_mode = "approve" under [mcp_servers.server-use] in ~/.codex/config.toml;
server-use's own per-server policy still stops destructive commands on confirm servers. Older Codex versions on
Windows start MCP servers without SYSTEMROOT, which crashes Node; there, add
env = { SYSTEMROOT = 'C:\Windows' } to the same section.
Other agents with a shell or skills support
Use your agent's documented skills directory; the default ~/.agents/skills is not discovered by every client.
The CLI also works without skills. In a container, point SERVER_USE_HOME at a persistent volume (for example
/data/.server-use) so the inventory, keys and pinned host keys survive restarts.
MCP
The plugin does not register an MCP server: CLI plus skills costs no tool schemas per request. If you prefer tools,
or your client has no shell or a sandbox:
This needs server-use on your PATH (npm i -g github:xpert2404/server-use). For other MCP clients, configure a