Running commands on the server through AI

How the assistant runs commands as root, the time and output limits, and the rules for long or interactive commands.

With the run_server_command MCP tool, the AI assistant connected to your account through https://api.app.blackbox.md/mcp (Claude, Cursor, VS Code, etc.) runs shell commands as root on your servers: it installs packages, reads logs and restarts services. The permission comes from the API token you create on blackbox.md → “Contul meu” (My account) → “Token-uri API” (API tokens) (/account/api-tokens).

Available to: the blackbox.md account holder, through an API token with the “Rulează orice comandă ca root pe serverele mele” (Run any command as root on my servers) permission (servers:exec). It works on the servers you ordered and on the servers of a company for which BLACKBOX has given you management rights. On servers marked “Managed” in the app.blackbox.md panel (view only), the response is not_found.

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

How it works

The assistant sends the server ID, the command and, optionally, the maximum waiting time.
BLACKBOX connects to the server over SSH, as root, with the management key (“Management key (blackbox.md)” in the panel), runs the command and returns the result to the assistant. You don't give the assistant any password or key.
Each call opens a new session, which starts in /root. cd and environment variables are not kept from one command to the next: write linked steps as a single command, joined with &&, or use absolute paths.
Commands don't go through any filter: on the server, the assistant can do everything root can do.

How to ask the assistant to run commands

On blackbox.md, in “Contul meu” (My account) → “Token-uri API” (API tokens), create a token with “Rulează orice comandă ca root pe serverele mele” (Run any command as root on my servers) checked. Also leave “Citește lista și statusul serverelor mele” (Read the list and status of my servers) (servers:read) checked: without it, the assistant can't find out the server ID. Steps: API tokens: creating, copying and revoking.
Add the token to your AI client: Connecting in the Claude app (custom connector) or Connecting from Claude Code, Cursor, VS Code and other clients.
Describe the task in your own words and name the server (its name or IP), for example “Install nginx on my server” or “Show me what is taking up disk space on server SERVER_IP”.
Usually, the AI client asks you to approve run_server_command and shows you the text of the command. Read the command and approve it only if you understand what it does.
The assistant receives the result and tells you what happened.

Parameters and result

Parameter	Values	Note
`server_id`	the ID returned by `list_servers`	a wrong ID gives `invalid_server_id` or `not_found`
`command`	1–8,192 characters	an empty command, one made only of spaces, or a longer one gives `invalid_command`
`timeout_seconds`	1–300 seconds, default 60	a value outside the range is moved to the nearest limit (600 becomes 300); it does not cause an error

Result field	What it contains
`exit_code`	the exit code: `0` = success, any other number = error; `null` if the time ran out
`timed_out`	`true` if the time ran out before the command finished
`stdout`, `stderr`	standard output and error output, at most 64,000 characters each
`stdout_truncated`, `stderr_truncated`	`true` if the output was cut off; the text ends with `...[truncated, N more chars]`. When the time runs out, these fields are missing from the result
`duration_ms`	the duration, in milliseconds

If the process was stopped by a signal, exit_code is the signal number with a minus sign, for example -9 after kill -9, or 128 plus the signal number (137) if the signal was reported by the shell (this depends on how the command is written). You get -1 when the server reports neither the code nor the signal; in that case, stderr ends with [terminated by signal]. An unexpected -9 or 137 usually means the process was forcibly stopped, often because the server ran out of memory.

Commands that don't ask questions

The command runs without a terminal (TTY), and standard input is closed. That's why:

any question such as “Do you want to continue? [Y/n]” and any password prompt fails;
programs with their own screen (nano, vim, top, the mysql console) don't work;
commands that don't finish on their own (tail -f, a server started in the foreground) run until the time runs out.

Instead of	Use
`apt install nginx`	`DEBIAN_FRONTEND=noninteractive apt-get install -y nginx`
`dnf install nginx`	`dnf install -y nginx`
`top`	`top -b -n 1`
`tail -f /var/log/nginx/error.log`	`tail -n 100 /var/log/nginx/error.log`
`journalctl -u nginx -f`	`journalctl -u nginx -n 100 --no-pager`
the `mysql` console	`mysql -e "SHOW DATABASES;"`
editing with `nano`	`sed -i` for a targeted change, or rewriting the whole file

Long commands

By default, the assistant waits 60 seconds for a command and can raise the time to 300 seconds. When the time runs out, the result comes back without an error: timed_out: true, exit_code: null and the output produced up to that point. BLACKBOX does not stop the process: it may keep running on the server.

Important After timed_out: true, don't ask for the same command to be run again: an installation or update started twice can get stuck or break things. First check the process, the log or the service status with a separate command.

For work that takes longer than a few minutes (a system update, a backup, a build), ask the assistant to start it in the background and check the result later.

The --force-confdef and --force-confold options in the Ubuntu and Debian examples keep the configuration files you have modified. Without them, the update stops with an error at the first question about such a file.

With `nohup`

Redirect the output to a file, as in the examples: otherwise, the call waits for the process until the time runs out.

Ubuntu and Debian:

nohup bash -c 'DEBIAN_FRONTEND=noninteractive apt-get update && DEBIAN_FRONTEND=noninteractive apt-get -y -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confold upgrade' > /root/upgrade.log 2>&1 &

AlmaLinux and CentOS Stream:

nohup dnf -y upgrade > /root/upgrade.log 2>&1 &

To check later: if pgrep shows nothing, the job has finished, and the result is at the end of the log:

pgrep -a 'apt-get|dnf'
tail -n 30 /root/upgrade.log

With `systemd-run`

The job becomes a temporary service, and its output goes to the system journal.

Ubuntu and Debian:

systemd-run --unit=upgrade-job bash -c 'DEBIAN_FRONTEND=noninteractive apt-get update && DEBIAN_FRONTEND=noninteractive apt-get -y -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confold upgrade'

AlmaLinux and CentOS Stream:

systemd-run --unit=upgrade-job dnf -y upgrade

To check later: active means the job is still running, inactive that it finished successfully, and failed that it stopped with an error:

systemctl is-active upgrade-job
journalctl -u upgrade-job -n 50 --no-pager

What the server needs

the management key (“Management key (blackbox.md)” in the panel) in /root/.ssh/authorized_keys;
root login with a key allowed: PermitRootLogin prohibit-password (or yes), never no;
the server running and reachable over SSH on port 22. The BLACKBOX connection doesn't use any other port, and a new port may be blocked by the BLACKBOX network filter: before you move SSH or restrict port 22 to your IP address, write to support.

Check the effective setting:

sshd -T | grep -i permitrootlogin

The results permitrootlogin yes, permitrootlogin prohibit-password and permitrootlogin without-password (the old name of the same setting) are fine.

If you ask the assistant to change the SSH settings or the firewall, keep a second SSH session open until you have checked that you can connect again. There is no web or VNC console for customers: if you lose access, only support can help you. What to do if the management key has been deleted: BLACKBOX keys on your server.

Limits and errors

The assistant can run at most 30 commands per minute per account, for all tokens together, and all MCP tools combined have a limit of 120 calls per minute. The command length, the waiting time and the output are limited as described above.

Error	What it means	What to do
`invalid_command`	the command is empty, made only of spaces, or longer than 8,192 characters	check the command; if it is too long, split it into several commands
`ssh_connection_failed`	BLACKBOX could not connect: the server is stopped, rebooting or not responding, the management key has been deleted, or `root` is no longer allowed to log in with a key	check that the server is running (Rebooting, stopping and starting a server) and try once more after a minute; if the error persists, check the requirements above or write to support: How to contact BLACKBOX support
`not_found`, `invalid_server_id`	the server does not exist, is not yours, is view-only, or the ID has a different format	ask the assistant to take the ID from `list_servers`
`rate_limited`	you have gone over one of the limits	wait a minute; calls made while you are limited also count
`missing_scope: this token does not have 'servers:exec'`	the token doesn't have the permission	create a new token; the permissions of an existing token can't be changed

Full list: MCP limits and error codes.

Privacy and safety

BLACKBOX logs only the fact that a command was run: the server, the time, the duration, the exit code, the length of the command and a fingerprint (hash) of it. The command text and the result are not kept, and the panel has no command history. The AI assistant's provider, however, sees the command and everything it returns: don't ask for files with passwords or keys (for example .env) to be displayed without a reason.

Risk A command run as root can delete data or lock you out of the server, and BLACKBOX does not filter commands. Make a backup before important changes: Backup strategy for your server.

BLACKBOX tells the assistant to ask you before actions that cost money, before canceling an order, deleting SSH keys or disabling password login, but not before running commands on the server. Your approval in the AI client is the only check: for run_server_command, don't choose the option that always allows the tool.
Use a separate token for servers:exec, and revoke it when you no longer need it: Token and AI agent security.

Security When the assistant reads content from untrusted sources (web pages, logs, emails, files you've received), the text there can “ask” it to run commands. If a proposed command has nothing to do with your task, reject it.

Frequently asked questions

The assistant says it doesn't have the run_server_command tool. Why? The token doesn't have the servers:exec permission, and tools without permission are not shown to the assistant. Create a new token with “Rulează orice comandă ca root pe serverele mele” (Run any command as root on my servers) checked, and replace the old token in the client.

Do I need to use sudo? No, commands already run as root. To run something as another user:

runuser -u USERNAME -- COMMAND

Can I disable SSH password login with a command? Don't change PasswordAuthentication with commands. Ask the assistant to use the set_server_password_auth tool, or use the “Disable password login” / “Enable password login” buttons in the panel: they check the configuration and won't leave you without access (Enabling and disabling SSH password login).

Can I work interactively or copy files? Not through run_server_command. For rsync, scp or an SSH session in your own terminal, the assistant can request SSH access: SSH access and SSH keys through the AI assistant.