SSH access and SSH keys through the AI assistant

An AI assistant connected through MCP (https://api.app.blackbox.md/mcp) can, at your request, get direct SSH access to your servers and manage SSH keys in your account and on the server. You give it access with an API token created in “Contul meu” (My account) → “Token-uri API” (API tokens) (blackbox.md/account/api-tokens). You can also manage the same keys yourself: on the “Chei SSH” (SSH keys) page in your account, and on the server card in “My Servers”, in the app.blackbox.md panel.

Available to: the holder of the blackbox.md account, through an API token with the permissions below. The server tools work on the servers you ordered and on a company's servers for which BLACKBOX has given you management rights. They do not work on servers marked “Managed” in the panel (view only); for changes to those servers, write to us.

The blackbox.md website is available in Romanian and Russian; this article quotes the Romanian labels with their English meaning.

Tools and required permissions

• On the tokens page, these permissions are called “Vizualizează parolele/accesul serverelor” (View server passwords/access) (servers:credentials), “Citește lista cheilor mele SSH” (Read the list of my SSH keys) (ssh_keys:read) and “Adaugă și șterge cheile mele SSH” (Add and delete my SSH keys) (ssh_keys:write). Tools that the token has no permission for do not appear in the assistant's list. Details: Token permissions (scopes).
• The limits are shared by all the tokens in your account and are separate from the panel's limits. All MCP tools together accept at most 120 calls per minute.

Direct SSH access for the assistant

get_server_ssh_access gives the assistant its own SSH key for a server: the agent key. BLACKBOX generates an Ed25519 key with the comment blackbox-agent-…, adds it to /root/.ssh/authorized_keys, and returns it together with the connection details.

1. Ask the assistant, for example: “Give me SSH access to the server SERVER_IP, I want to copy files with rsync.”

2. The assistant calls get_server_ssh_access. The AI client may ask you to approve the call.

3. The response contains:

   Field	Content
   host, port, username	the server's IP address, the SSH port and the root user
   private_key	the private part of the key, in OpenSSH format, not protected by a passphrase
   public_key, fingerprint	the public line ssh-ed25519 … blackbox-agent-… and the SHA256:… fingerprint
   ssh_command	the ready-to-use command, ssh -i <keyfile> -p PORT root@IP; replace <keyfile> with the path to the file that holds the key
   created, rotated, previous_key_removed	whether the key was just created, whether it was replaced, and whether the old one was deleted

• Every call returns the same key and puts it back if it was deleted from the server in the meantime. On servers ordered on blackbox.md, the key is usually added when the server is created; if the server did not receive it then, it is created at the first call.
• A server has a single agent key, shared by all your tokens.
• With regenerate=true, a new key is created and the old one is deleted from the server. If the deletion fails, the response shows previous_key_removed: false: in that case, remove in the panel the blackbox-agent-… key whose fingerprint differs from the one in the response.

The assistant does not need a key for ordinary commands: it uses run_server_command (Running commands on the server through AI). The agent key is useful for copying files with rsync or scp, for interactive sessions in your own terminal, and for tools that need a real SSH connection (for example VS Code Remote - SSH or Ansible). The assistant can use it on its own only if the AI client runs commands on your computer (for example Claude Code or Cursor); otherwise, it can give you the key and the command so that you connect yourself.

How to use the agent key from your terminal

1. Explicitly ask the assistant to show you the private key: it is instructed not to show passwords and keys in the conversation unless you explicitly ask.

2. Copy all the text, from -----BEGIN OPENSSH PRIVATE KEY----- up to and including -----END OPENSSH PRIVATE KEY-----, into a new file, for example ~/.ssh/blackbox_agent. After the last line, press Enter so that the file ends with a new line; otherwise SSH may respond with invalid format.

3. On macOS and Linux, restrict the file's permissions and connect:

   chmod 600 ~/.ssh/blackbox_agent
   ssh -i ~/.ssh/blackbox_agent -p 22 root@SERVER_IP

4. On Windows, check that the file did not get a .txt extension. In PowerShell, give access to the file only to your user (otherwise SSH may reject the key with UNPROTECTED PRIVATE KEY FILE), then connect:

   icacls $env:USERPROFILE\.ssh\blackbox_agent /inheritance:r /grant:r "$($env:USERNAME):(R)"
   ssh -i $env:USERPROFILE\.ssh\blackbox_agent -p 22 root@SERVER_IP

Copying files with the same key:

rsync -avz -e "ssh -i ~/.ssh/blackbox_agent" ./site/ root@SERVER_IP:/var/www/site/
scp -i ~/.ssh/blackbox_agent backup.tar.gz root@SERVER_IP:/root/

Details: Transferring files to the server (scp, rsync, SFTP). For your own permanent access, install your own key: any assistant can replace the agent key at any time with regenerate=true.

The keys in your account

list_ssh_keys, add_ssh_key and delete_ssh_key work with the same keys as the “Chei SSH” (SSH keys) page (blackbox.md/account/ssh-keys, “Contul meu” (My account) → “Chei SSH”): a key added by the assistant appears there, and the other way around. The same rules apply (SSH keys in your account (blackbox.md)):

• at most 20 keys per account (otherwise too_many_keys);
• a single public key line of type ssh-ed25519, ssh-rsa (at least 2048 bits), ecdsa-sha2-nistp256/384/521, sk-ssh-ed25519@openssh.com or sk-ecdsa-sha2-nistp256@openssh.com (otherwise invalid_public_key, unsupported_key_type or key_too_weak);
• a required name, on a single line, of at most 80 characters;
• a private key is rejected (private_key_submitted), and so is a key that is already saved (duplicate_key).

Example: “Save the public key below in my account, with the name ‘Work laptop’.” add_ssh_key does not install the key on any server; for that, the assistant then uses add_server_ssh_key. The other way around, delete_ssh_key deletes the key only from your account: on the servers where it is installed, the key keeps working until you remove it from each server.

The keys on the server

These tools use the BLACKBOX management connection, without your password or key. add_server_ssh_key, list_server_ssh_keys and remove_server_ssh_key work with /root/.ssh/authorized_keys, just like the “Add SSH key” section on the server card (Adding and removing SSH keys on the server).

• A pasted key is installed only on that server and is not saved in your account.
• set_server_password_auth does the same thing as the “Disable password login” and “Enable password login” buttons: it writes the settings to a file in /etc/ssh/sshd_config.d/, checks them, reloads SSH, and restores the previous settings if a step fails. The badge on the card changes to “Key-only” or “Password + key” (Enabling and disabling SSH password login). Ask the assistant to use this tool, not to edit sshd_config with commands.

Examples: “Install the ‘Work laptop’ key on the server SERVER_IP.”, “Which SSH keys are installed on the server SERVER_IP?”

Safeguards against losing access

The assistant is instructed to ask for your confirmation before it removes a key from the server, turns off password login or replaces the agent key. However, the confirmation window is shown by the AI client: keep action approval turned on in its settings.

Important The safeguards do not replace your own check. Before you turn off the password or remove a key, check in a new terminal that you can log in with your own key, and keep the current session open. Customers have no web or VNC console; if you lose access, see Lost access to your server (password or key).

How to revoke the assistant's SSH access

Security The private key you receive from get_server_ssh_access gives root access: keep it as safe as a password. It passes through the AI client and the client's provider, like any tool result. Do not send it in chats and do not save it in code repositories.

1. Revoke the tokens you no longer use: “Contul meu” (My account) → “Token-uri API” (API tokens) → “Revocă” (Revoke) (API tokens: creating, copying and revoking). Otherwise, any token with servers:credentials can reinstall the key at the next call.
2. Remove the agent key in the panel: on the server card, “Add SSH key” → “Installed keys” → the row with the comment blackbox-agent-… → “Remove”, then confirm. “Key removed.” appears (BLACKBOX keys on your server).
3. If the assistant still needs SSH access, ask it for a new key with regenerate=true. A call without regenerate would put the old key back.

Common errors

Full list: MCP limits and error codes.

Frequently asked questions

Why does the assistant say it doesn't have the get_server_ssh_access tool? The token does not have the “Vizualizează parolele/accesul serverelor” (View server passwords/access) permission (servers:credentials). You cannot add permissions to an existing token: create a new token.

I removed the agent key in the panel and it appeared again. Why? An assistant with a token that has servers:credentials requested SSH access again, and get_server_ssh_access put the same key back. Revoke unused tokens or request a new key with regenerate=true.

Does access through the assistant work on a “Key-only” server? Yes. The agent key is installed through the BLACKBOX management connection, and logging in with a key works even when password login is turned off.