Rularea comenzilor pe server prin AI

Cum rulează asistentul comenzi ca root, limitele de timp și de ieșire și regulile pentru comenzi lungi sau interactive.

Cu unealta MCP run_server_command, asistentul AI conectat la contul dvs. prin https://api.app.blackbox.md/mcp (Claude, Cursor, VS Code etc.) rulează comenzi shell ca root pe serverele dvs.: instalează pachete, citește jurnale, repornește servicii. Dreptul se acordă prin token-ul API creat pe blackbox.md → „Contul meu” → „Token-uri API” (/account/api-tokens).

Disponibil pentru: titularul contului blackbox.md, printr-un token API cu permisiunea „Rulează orice comandă ca root pe serverele mele” (servers:exec). Funcționează pe serverele comandate de dvs. și pe serverele unei companii la care BLACKBOX v-a acordat drept de administrare. Pe serverele marcate „Administrat” în panoul app.blackbox.md (doar vizualizare) răspunsul este not_found.

Cum funcționează

Asistentul trimite id-ul serverului, comanda și, opțional, timpul maxim de așteptare.
BLACKBOX se conectează la server prin SSH, ca root, cu cheia de administrare („Cheie de administrare (blackbox.md)” în panou), rulează comanda și îi întoarce rezultatul asistentului. Nu îi dați asistentului nicio parolă și nicio cheie.
Fiecare apel deschide o sesiune nouă, care pornește în /root. cd și variabilele de mediu nu se păstrează de la o comandă la alta: pașii legați între ei se scriu într-o singură comandă, cu &&, sau se folosesc căi absolute.
Comenzile nu trec prin niciun filtru: asistentul poate face pe server tot ce poate face root.

Cum îi cereți asistentului să ruleze comenzi

Pe blackbox.md, în „Contul meu” → „Token-uri API”, creați un token cu „Rulează orice comandă ca root pe serverele mele” bifat. Lăsați bifat și „Citește lista și statusul serverelor mele” (servers:read): fără el asistentul nu poate afla id-ul serverului. Pașii: Token-uri API: creare, copiere și revocare.
Adăugați token-ul în clientul AI: Conectarea în aplicația Claude (connector personalizat) sau Conectarea din Claude Code, Cursor, VS Code și alți clienți.
Descrieți sarcina în cuvinte și numiți serverul (numele sau IP-ul), de exemplu „Instalează nginx pe serverul meu” sau „Arată-mi ce ocupă discul pe serverul IP_SERVER”.
De regulă, clientul AI vă cere aprobarea pentru run_server_command și vă arată textul comenzii. Citiți comanda și aprobați-o doar dacă înțelegeți ce face.
Asistentul primește rezultatul și vă spune ce s-a întâmplat.

Parametri și rezultat

Parametru	Valori	Notă
`server_id`	id-ul primit de la `list_servers`	un id greșit dă `invalid_server_id` sau `not_found`
`command`	1–8192 de caractere	o comandă goală, doar din spații sau mai lungă dă `invalid_command`
`timeout_seconds`	1–300 de secunde, implicit 60	o valoare în afara intervalului se aduce la limita cea mai apropiată (600 devine 300); nu dă eroare

Câmp în rezultat	Ce conține
`exit_code`	codul de ieșire: `0` = succes, alt număr = eroare; `null` dacă timpul a expirat
`timed_out`	`true` dacă timpul a expirat înainte ca comanda să se termine
`stdout`, `stderr`	ieșirea standard și ieșirea de erori, cel mult 64 000 de caractere fiecare
`stdout_truncated`, `stderr_truncated`	`true` dacă ieșirea a fost tăiată; textul se termină cu `...[truncated, N more chars]`. Când timpul a expirat, aceste câmpuri lipsesc din rezultat
`duration_ms`	durata, în milisecunde

Dacă procesul a fost oprit de un semnal, exit_code este numărul semnalului cu minus, de exemplu -9 după kill -9, sau 128 plus numărul semnalului (137), dacă semnalul a fost raportat de shell (depinde de cum este scrisă comanda). -1 primiți când serverul nu raportează nici codul, nici semnalul; atunci stderr se termină cu [terminated by signal]. Un -9 sau un 137 neașteptat înseamnă de obicei că procesul a fost oprit forțat, adesea din lipsă de memorie.

Comenzi fără întrebări

Comanda rulează fără terminal (TTY), iar intrarea standard este închisă. De aceea:

orice întrebare de tipul „Do you want to continue? [Y/n]” și orice cerere de parolă eșuează;
programele cu ecran propriu (nano, vim, top, consola mysql) nu funcționează;
comenzile care nu se termină singure (tail -f, un server pornit în prim-plan) rulează până la expirarea timpului.

În loc de	Folosiți
`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`
consola `mysql`	`mysql -e "SHOW DATABASES;"`
editarea cu `nano`	`sed -i` pentru o modificare punctuală sau rescrierea fișierului întreg

Comenzi lungi

Implicit, asistentul așteaptă o comandă 60 de secunde și poate mări timpul până la 300 de secunde. Când timpul expiră, rezultatul vine fără eroare: timed_out: true, exit_code: null și ieșirea produsă până atunci. BLACKBOX nu oprește procesul: acesta poate rula în continuare pe server.

Important După timed_out: true nu cereți repetarea aceleiași comenzi: o instalare sau o actualizare pornită de două ori se poate bloca sau strica. Verificați întâi, cu o comandă separată, procesul, jurnalul sau starea serviciului.

Pentru lucrări mai lungi de câteva minute (actualizarea sistemului, un backup, o compilare), cereți asistentului să le pornească în fundal și să verifice rezultatul mai târziu.

Opțiunile --force-confdef și --force-confold din exemplele pentru Ubuntu și Debian păstrează fișierele de configurare pe care le-ați modificat. Fără ele, actualizarea se oprește cu eroare la prima întrebare despre un astfel de fișier.

Cu `nohup`

Redirecționați ieșirea într-un fișier, ca în exemple: altfel apelul așteaptă procesul până la expirarea timpului.

Ubuntu și 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 și CentOS Stream:

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

Verificarea, mai târziu. Dacă pgrep nu afișează nimic, lucrarea s-a terminat, iar rezultatul este la sfârșitul jurnalului:

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

Cu `systemd-run`

Lucrarea devine un serviciu temporar, iar ieșirea ajunge în jurnalul sistemului.

Ubuntu și 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 și CentOS Stream:

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

Verificarea, mai târziu. active înseamnă că lucrarea rulează încă, inactive că s-a terminat cu succes, iar failed că s-a oprit cu eroare:

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

Ce trebuie să existe pe server

cheia de administrare („Cheie de administrare (blackbox.md)” în panou) în /root/.ssh/authorized_keys;
conectarea lui root cu cheie permisă: PermitRootLogin prohibit-password (sau yes), niciodată no;
serverul pornit și accesibil prin SSH pe portul 22. Conexiunea BLACKBOX nu folosește alt port, iar un port nou poate fi blocat de filtrul de rețea BLACKBOX: înainte să mutați SSH sau să limitați portul 22 la adresa dvs. IP, scrieți suportului.

Verificați setarea efectivă:

sshd -T | grep -i permitrootlogin

Rezultatele permitrootlogin yes, permitrootlogin prohibit-password și permitrootlogin without-password (numele vechi al aceleiași setări) sunt în regulă.

Dacă îi cereți asistentului să schimbe setările SSH sau firewall-ul, păstrați deschisă o a doua sesiune SSH până verificați că vă puteți conecta din nou. Pentru clienți nu există consolă web sau VNC: dacă pierdeți accesul, vă poate ajuta doar suportul. Ce faceți dacă cheia de administrare a fost ștearsă: Cheile BLACKBOX de pe serverul dvs..

Limite și erori

Asistentul poate rula cel mult 30 de comenzi pe minut pe cont, pentru toate token-urile împreună, iar toate uneltele MCP la un loc au o limită de 120 de apeluri pe minut. Lungimea comenzii, timpul de așteptare și ieșirea sunt limitate ca mai sus.

Eroare	Ce înseamnă	Ce faceți
`invalid_command`	comanda este goală, doar din spații sau are peste 8192 de caractere	verificați comanda; dacă este prea lungă, împărțiți-o în mai multe comenzi
`ssh_connection_failed`	BLACKBOX nu s-a putut conecta: serverul este oprit, repornește sau nu răspunde, cheia de administrare a fost ștearsă ori `root` nu mai are voie să intre cu cheie	verificați că serverul rulează (Repornirea, oprirea și pornirea serverului) și reîncercați o dată după un minut; dacă eroarea rămâne, verificați condițiile de mai sus sau scrieți suportului: Cum contactați suportul BLACKBOX
`not_found`, `invalid_server_id`	serverul nu există, nu este al dvs., este doar de vizualizare sau id-ul are alt format	cereți asistentului să ia id-ul din `list_servers`
`rate_limited`	ați depășit una dintre limite	așteptați un minut; apelurile făcute cât sunteți limitat se numără și ele
`missing_scope: this token does not have 'servers:exec'`	token-ul nu are permisiunea	creați un token nou; permisiunile unui token existent nu se pot schimba

Lista completă: Limite și coduri de eroare MCP.

Confidențialitate și siguranță

BLACKBOX înregistrează doar faptul că a fost rulată o comandă: serverul, momentul, durata, codul de ieșire, lungimea comenzii și o amprentă (hash) a ei. Textul comenzii și rezultatul nu se păstrează, iar panoul nu are un istoric al comenzilor. Furnizorul asistentului AI vede însă comanda și tot ce întoarce ea: nu cereți afișarea fișierelor cu parole sau chei (de exemplu .env) fără motiv.

Risc O comandă rulată ca root poate șterge date sau bloca accesul la server, iar BLACKBOX nu filtrează comenzile. Faceți backup înainte de modificări importante: Strategia de backup pentru serverul dvs..

BLACKBOX îi cere asistentului să vă întrebe înainte de acțiunile care costă bani, de anularea unei comenzi, de ștergerea cheilor SSH sau de dezactivarea autentificării cu parolă, dar nu și înainte de a rula comenzi pe server. Aprobarea din clientul AI este singura verificare: nu alegeți pentru run_server_command opțiunea de a permite unealta întotdeauna.
Folosiți un token separat pentru servers:exec și revocați-l când nu mai aveți nevoie de el: Securitatea token-urilor și a agenților AI.

Securitate Când asistentul citește conținut din surse nesigure (pagini web, jurnale, emailuri, fișiere primite), textul de acolo îi poate „cere” să ruleze comenzi. Dacă o comandă propusă nu are legătură cu sarcina dvs., refuzați-o.

Întrebări frecvente

Asistentul spune că nu are unealta run_server_command. De ce? Token-ul nu are permisiunea servers:exec, iar uneltele fără permisiune nu îi sunt arătate asistentului. Creați un token nou cu „Rulează orice comandă ca root pe serverele mele” și înlocuiți-l în client.

Trebuie să folosesc sudo? Nu, comenzile rulează deja ca root. Pentru a rula ceva ca alt utilizator:

runuser -u NUME_UTILIZATOR -- COMANDA

Pot dezactiva autentificarea SSH cu parolă printr-o comandă? Nu modificați PasswordAuthentication cu comenzi. Cereți asistentului să folosească unealta set_server_password_auth sau folosiți în panou butoanele „Dezactivează login cu parolă” / „Activează login cu parolă”: ele verifică configurația și nu vă lasă fără acces (Activarea și dezactivarea autentificării SSH cu parolă).

Pot lucra interactiv sau copia fișiere? Nu prin run_server_command. Pentru rsync, scp sau o sesiune SSH în terminalul dvs., asistentul poate cere acces SSH: Acces SSH și chei SSH prin asistentul AI.