Docs

K2Shell documentation.

Everything you need to install, connect servers, bring in your agents, and run K2Shell well.

Getting started

Create an account at k2shell.com/signup and confirm your email address. Every account starts with a 14-day free trial, with no card needed. To run K2Shell on your own server instead, see Self-hosted.

On your first visit, K2Shell asks you to create your vault and shows a recovery code. Save the code somewhere safe. Then add your first host on Hosts.

The vault

Your vault holds saved SSH hosts, passwords, private keys, snippets and command history. It is encrypted in your browser with a key derived from your master password, which never leaves your device.

The vault locks after the idle time set under Account, Auto-lock. If you forget the master password, use the recovery code. Without either, nobody can open the vault, including us. Keyless servers for Claude do not need the vault.

Hosts, folders and import

Hosts lists every server in one place. When you add a host, choose its type: Keyless SSH (enrolled with a certificate, which is what Claude and other agents use) or SSH with a password or private key saved in your vault.

Organise SSH hosts with folders, tags and colors. Snippets and import/export accepts ~/.ssh/config and CSV with the header name,hostname,port,username,folder,tags. Saved keys are listed under Account, SSH keys.

Host keys are pinned the first time you connect. If a key changes, the connection is refused until you clear it on the host's page.

Terminal

Open a terminal from a host or from Terminal with + New tab. Tabs keep running while you use other pages. Turn on Broadcast to type into every tab, use Snippets for saved commands, press → to accept a history suggestion, and press Ctrl+Shift+F to search the scrollback.

Files

Open Files, pick a host, then browse, upload, download, rename, delete and edit. Text files open in an editor with syntax highlighting, and saving writes straight back over SFTP.

Enrolling servers for Claude

On Hosts, choose Add host and the type Keyless SSH. Enter the address, the login user commands should run as, a policy, and an optional owner note that agents see, such as what the server is for. Then run the one-line install command on the server.

As root (or with sudo), the command adds your account's certificate authority to sshd next to anything sshd already trusts, allows your principal for that login user only, checks the config with sshd -t, reloads sshd and reports the host key back. Without root, as on shared hosting, sign in as the login user and run it without sudo. It then trusts your account for that user only, through ~/.ssh/authorized_keys, and changes nothing else.

The install link works once and expires after an hour. If the server cannot reach k2shell.com, choose Paste a script, run it in a root shell, then click Check host key and confirm the fingerprint matches.

Connecting Claude and other agents

The MCP server URL is https://k2shell.com/mcp. It uses Streamable HTTP, with OAuth sign-in or an API key. On a self-hosted install, use https://your-host/mcp instead.

claude.ai and Claude desktop:

In Claude, open Settings, Connectors and choose Add custom connector.
Enter https://k2shell.com/mcp and connect.
Sign in to K2Shell when the sign-in page opens.
On the consent page, choose the policy and which servers Claude may use, then click Allow.
Turn the connector on in a chat.

Connected apps are listed under Account, API keys & MCP, where you can change their policy and servers or disconnect them.

Claude Code, Cursor, Codex and others: create a key on Account, API keys & MCP. The page shows the exact command or config for each client. For Claude Code:

claude mcp add --transport http k2shell https://k2shell.com/mcp --header "Authorization: Bearer k2shell_..."

MCP tools

K2Shell has 17 tools. "Read" tools only look at things; "Write" tools can change a server or start work on it. Every call is checked against the policy of the server and of the connection, and every command is written to Activity.

hosts_listRead. The servers this connection can reach, with address, login user, enrollment state, owner note and policy.

ssh_execWrite. Run one command on one server and return the exit code, stdout and stderr.

ssh_exec_manyWrite. Run the same command on several servers in parallel, with one result per server.

job_startWrite. Start a long command in the background and get a job id (up to an hour).

job_statusRead. The state and output of a background job, or a list of recent jobs.

session_openWrite. Open an interactive terminal with a TTY. You can watch it live; recording depends on settings. Needs the full policy.

session_sendWrite. Type into an open terminal, including Enter and control keys, and return the output.

session_readRead. Read new output from an open terminal.

session_closeWrite. Close a terminal, or list the open ones.

file_listRead. List a folder over SFTP. Needs the full policy.

file_readRead. Read a text file over SFTP (up to 2 MB). Needs the full policy.

file_writeWrite. Create, replace or append to a file over SFTP. Needs the full policy.

metrics_getRead. The latest monitoring sample: CPU, memory, disks, load, network, failed services, containers and ports.

alerts_listRead. Open monitoring alerts, or the alert history.

backup_listRead. Backup jobs and their recent runs.

backup_createWrite. Run an existing backup job now, with an optional label. Not allowed with the read-only policy.

password_generateRead. Generate a strong random password on K2Shell and return it to the requesting client; it is not stored.

Policies and scope

Each server and each key or connected app has a policy: full (any command, terminals and files), allowlist (only listed diagnostic command prefixes, with simple arguments) or read-only (no commands; listing servers, metrics, alerts and backups only). Restricted policies reject interpreters, scripts, tools that can run other programs, quoting and shell expansion. Both the server's and the connection's policy must allow a call, and keys and apps can be limited to chosen servers.

Optional: keep command output, sealed so only your vault can read it, and pause agents while your vault is locked.

Monitoring and alerts

Turn on monitoring per server on Monitoring. Samples are taken every minute and kept for 90 days. Set thresholds and add channels (email, Telegram or webhook) under Notification channels and Alert thresholds. Mute a server or an alert type during maintenance.

Backups

On Backups, create a job with a server, folders, a schedule, how many copies to keep, and a destination: K2Shell's own storage, an S3-compatible bucket, or another enrolled server. Downloads are plain .tar.gz files. Agents can list jobs and run one now with backup_create, but only you can create or change jobs.

On a self-hosted install, K2Shell's own database is also snapshotted daily to /data/backups/app. Restore one with node dist/server/backup.js --restore <file> restored.db.

Internal sites

Internal sites opens a web dashboard or admin page from a private network in your browser, through one of your enrolled servers in that network. On a paid plan you can share a site by email; during the trial, sites open for you only. Self-hosted installs need INTERNAL_SITES_DOMAIN with wildcard DNS and HTTPS.

Live sessions, recordings and activity

Live sessions shows every open terminal, with agent sessions highlighted. Turn on recording in Settings to replay sessions on Recordings. Activity lists every command and account event.

Account security

In Settings, add a passkey, turn on two-factor authentication and change your vault master password. Account, Devices shows signed-in devices and lets you sign them out, and Account, Password changes your account password. You get an email when a new device signs in, and you can reset a forgotten account password by email. You can also sign in with Google or GitHub once you have linked them.

Plans and billing

Every account starts with a 14-day free trial with every feature. After it, choose a plan under Account, Plan and billing: Pro is $9 a month or $86 a year, and Team is $12 per seat a month or $115 per seat a year. Payments go through PayPal, and you can cancel any time. A cancelled plan runs to the end of the paid period. See Pricing.

If the trial ends without a plan, you can still sign in, export your hosts and change settings, but terminals, agents, monitoring and backups pause until you subscribe. Your data is kept.

Self-hosting, HTTPS and upgrades

Put K2Shell behind a reverse proxy with HTTPS, and set PUBLIC_URL and TRUST_PROXY=true. Passkeys and OAuth connectors need HTTPS outside localhost.

Self-hosted installs need a license key, entered on Plan and billing or set as LICENSE_KEY. License issuance and renewal require the operator’s licensing process. To upgrade, back up the data volume and start the new version. Schema upgrades also write a copy of the old database next to it.

Troubleshooting

"Host key changed": the server's key no longer matches the pinned one. Check why before clearing it.
Agent command refused: check both the connection's and the server's policy, and whether agents are paused while the vault is locked.
Enrollment fails: use the paste-a-script option and read sshd's output; sshd -t must pass. On shared hosting without root, run the command as the login user without sudo.
Claude can't reach a server: the server's firewall must allow SSH from k2shell.com (91.108.121.216) on its SSH port.
Self-hosted health: /readyz returns the schema version, and docker compose logs app shows errors.

Support

Email support@k2shell.com and a person will reply. Report security issues to security@k2shell.com. See also Privacy and Terms.