AgentX
Fjernshell, konfiguration, opgradering, afinstallation, backup og logfiler. Kommandoerne herunder kører du på maskinen. Den hostede konsol kan ikke slå fjernshell til.
En ny AgentX-installation starter ikke et fjernshell, før dens miljø har AGENTX_REMOTE_SHELL=on. Uden værdi, off eller enhver anden værdi lader det være slået fra. Det læses én gang ved opstart, så en ændring kræver en genstart. Konsollen og konfigurationsfilen kan ikke slå det til. Fra version 0.184.4 afvises en shellstart, mens kontakten er slået fra. Efter en genstart følger konsollen kontakten, når AgentX forbinder igen. På en server kan det tage op til et minut, og på Docker omkring 30 sekunder. Indtil da kan knappen stadig vise den forrige tilstand. Før version 0.184.4 har AgentX ingen kontakt: knappen bliver skjult, og en anmodning om at starte et shell starter stadig et. På en Linux-server er kontakten i AgentX fra version 0.184.4.
# /etc/default/agentx AGENTX_REMOTE_SHELL=on sudo systemctl restart agentx
# /etc/default/agentx AGENTX_REMOTE_SHELL=off sudo systemctl restart agentx
På Linux-desktoppakken kører AgentX som login-brugeren, og agenterne kører som den samme bruger, som kan rette AgentX-tjenestens miljø. Åbn brugerenheden, tilføj Service-linjerne nedenfor, og genstart den. På desktoppakken er kontakten i AgentX fra version 0.184.4.
systemctl --user edit agentx-daemon
[Service] Environment=AGENTX_REMOTE_SHELL=on
systemctl --user restart agentx-daemon
På en Mac er den installerede AgentX en LaunchAgent for brugeren, eller en Homebrew-tjeneste uden brugerangivelse. Den kører som den indloggede bruger, og agenterne kører som den bruger, som kan rette AgentX-tjenestens miljø. Tilføj de to linjer nedenfor under EnvironmentVariables i ~/Library/LaunchAgents/com.agentx.daemon.plist, og genindlæs jobbet. For Homebrew sætter du den samme variabel på brew-tjenesten og genstarter det job. På en Mac er kontakten i AgentX fra version 0.184.4.
<key>AGENTX_REMOTE_SHELL</key> <string>on</string>
launchctl bootout gui/$(id -u)/com.agentx.daemon launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.agentx.daemon.plist
På Windows hedder tjenesten AgentX og kører som personen. Fra en prompt med administratorrettigheder sætter du tjenestens Environment-værdi, og stopper og starter tjenesten. Kommandoen erstatter en eksisterende Environment-værdi. For at beholde endnu en post, adskil posterne med \0. På Windows er kontakten i AgentX fra version 0.184.4.
reg add HKLM\SYSTEM\CurrentControlSet\Services\AgentX /v Environment /t REG_MULTI_SZ /d AGENTX_REMOTE_SHELL=on /f sc.exe stop AgentX sc.exe start AgentX
Til Docker sender du variablen med docker run, eller sætter den under environment: i en compose-fil. Volumenerne er agentx-data, agentx-root og agentx-home. En ændring betyder, at containeren oprettes igen. Fra version 0.184.4 er fjernshell slået fra, hvis du opretter den uden variablen. På et ældre image starter et shell, uanset hvad variablen siger. Til Docker er kontakten i AgentX fra version 0.184.4. På et ældre image har -e-indstillingen ingen virkning.
docker run -d --platform linux/amd64 --name agentx --restart unless-stopped -e AGENTX_REMOTE_SHELL=on -p 127.0.0.1:3333:3333 -v agentx-data:/var/lib/agentx -v agentx-root:/root -v agentx-home:/home agentxhq/agentx-daemon:latest
environment: AGENTX_REMOTE_SHELL: "on"
Hvis du startede AgentX i en terminal, skal du eksportere variablen i den skal, stoppe AgentX og starte den igen fra den samme skal. For AgentX startet i en terminal er kontakten i AgentX fra version 0.184.4.
export AGENTX_REMOTE_SHELL=on agentx-daemon stop
I den hostede konsol kan ethvert indlogget medlem af teamet starte et shell, når AgentX har slået fjernshell til, også et medlem med en læserolle. Det er ikke forbeholdt ejeren.
Fra version 0.184.4 stopper det et nyt shell at slå fjernshell fra. Efter en genstart kan knappen bruge op til et minut på en server, og omkring 30 sekunder på Docker, på at følge kontakten. Indtil da kan den stadig vise den forrige tilstand, og en start afvises, hvis kontakten er slået fra. Fra den hostede konsol kan et eksisterende shell stadig genoptages, åbnes igen og skrives i, og en besked kan stadig sendes. Det, der skrives i en agentterminal, kan køre kommandoer, for eksempel ! i Claude Code. Kontakten ændrer ikke det.
For at stoppe AgentX i at forbinde til den hostede konsol, sæt router.enabled til false i konfigurationsfilen og genstart. En miljøvariabel kan ikke sætte den. Siden på maskinen kører stadig. Bridge-adressen er som standard grpcs://bridge.agentxhq.io:443. AGENTX_BRIDGE_ADDR tilsidesætter den, og en udfyldt router.bridge_addr i filen vinder.
router: enabled: false
Konfigurationsfilen er ~/.agentx/config.yaml for en almindelig bruger og /etc/agentx/config.yaml for root. Indstillinger i filen overlægges af miljøvariabler med navnet AGENTX_ plus indstillingen. AGENTX_REMOTE_SHELL er ikke en af de indstillinger, og router.enabled kan ikke sættes fra miljøet. Databasen er som standard agentx.db i datamappen, og router-tilstanden er router-state.json ved siden af. For root er datamappen /var/lib/agentx. En agent, der kører som root, har sine filer i /root/.agentx/<name>. En agent med sin egen konto har dem i den kontos hjemmemappe. Kommandoerne nedenfor kopierer kontoernes hjemmemapper. For at beholde filerne fra en agent, der kører som root, skal du også kopiere /root/.agentx.
Websiden lytter på 127.0.0.1:3333 og den lokale port på 127.0.0.1:3334, medmindre du ændrer dem. AGENTX_SERVER_ADDR tilsidesætter webadressen. En udfyldt surfaces.web.listen_addr i konfigurationsfilen erstatter webadressen. Docker-imaget sætter webadressen til 0.0.0.0:3333.
Opgrader den samme variant, du installerede. En opgradering beholder tilmeldingen, agenterne og deres filer. På en Linux-server installerer du den nye pakke som sit eget systemjob, så genstarten ikke afhænger af den session, du er i. Brug dnf eller pacman på samme måde, når det er den pakke, du har.
sudo systemd-run --unit=agentx-upgrade --collect apt-get install -y "$PWD/<filename>"
Navnet i den kommando er den pakkefil, du har hentet. Hent den på installationssiden. Til Docker kører du opgraderingskommandoen.
På en Mac med Homebrew: brew upgrade agentx, og derefter launchctl kickstart -k af det job, der kører. Uden Homebrew kører du ./install.sh uden --launchd, og kickstarter derefter LaunchAgent. På Windows: Stop-Service AgentX, kopiér de nye programmer til C:\Program Files\AgentX\, og kør Start-Service AgentX. Til Docker henter du imaget og opretter containeren igen med de samme volumer. En ny container beholder ikke Unix-konti for agenter, der har deres egen bruger. Kør useradd og chown igen for hver sådan konto.
Afinstallation stopper AgentX og lader dens filer blive. På en Linux-server: apt remove, eller dnf remove, eller pacman -R, af agentx-server. Desktoppakken er agentx-desktop, og ~/.agentx bliver. På en Mac: agentx-daemon stop, derefter launchctl bootout gui/$(id -u)/com.agentx.daemon, og fjern så plist-filen. brew uninstall agentx er Homebrew-fjernelsen. På Windows: sc.exe stop AgentX og sc.exe delete AgentX. Til Docker:
sudo apt remove agentx-server
docker rm -f agentx
At slette data er et separat trin. Fjern datamappen, eller fjern de tre Docker-volumer. Den sletning er ikke en del af afinstallationen.
docker volume rm agentx-data agentx-root agentx-home
Der er ingen backupkommando. Stop AgentX, kopiér databasen, router-tilstanden, identity.json, konfigurationsfilen og på en server miljøfilen, og start den igen. På den samme maskine, mens Unix-kontiene stadig er der, er den filkopi nok. Backupmappen i serverkommandoen skal findes i forvejen. En fil, der endnu ikke findes, får cp til at melde den og afslutte med en kode, der ikke er nul, og de filer, der findes, bliver stadig kopieret; router-tilstanden findes først efter AgentX' første lagring. /etc/default/agentx er der, hvor serverpakken læser AGENTX_REMOTE_SHELL. Backuppen indeholder AgentX-tjenestens private nøgle. Opbevar den lige så privat som en adgangskode.
sudo systemctl stop agentx sudo cp -a /var/lib/agentx/agentx.db /var/lib/agentx/router-state.json /var/lib/agentx/identity.json /etc/agentx/config.yaml /etc/default/agentx /path/to/backup/ sudo cp -a /root/.agentx /path/to/backup/root-agentx sudo systemctl start agentx
En agent, der blev oprettet med sin egen bruger, skal også have den Unix-konto, med det samme navn, og dens hjemmemappe. Konsollen viser kontonavnet under Run as. Den hjemmemappe indeholder ~/.agentx/<name>, og backuppen kopierer hjemmemappen.
sudo cp -a /home/<account> /path/to/backup/
Gendannelse af AgentX-filerne er den samme kopi den anden vej, mens AgentX er stoppet. En gendannelse af databasen og config.yaml uden /etc/default/agentx lader fjernshell være slået fra, fra version 0.184.4, fordi kontakten som standard er fra. Før den version har AgentX ingen kontakt, og en anmodning om at starte et shell starter stadig et. På en ren maskine genskaber du hver sådan konto og lægger hjemmemappen tilbage. Den hjemmemappe indeholder ~/.agentx/<name>. Hvis den nye konto ikke får den uid, der ejer hjemmemappen, lader useradd alene Start session fejle. chown skal med.
sudo useradd --create-home --home-dir /home/<account> --shell /bin/bash <account> sudo cp -a /path/to/backup/<account>/. /home/<account>/ sudo chown -R <account>: /home/<account> sudo cp -a /path/to/backup/root-agentx/. /root/.agentx/
Til Docker stopper du containeren og kopierer databasen, router-tilstanden og identity.json ud af agentx-data-voluminet, og kopierer agentx-root- og agentx-home-volumenerne, med imagets cp, og starter containeren. På den samme container, mens kontiene stadig er der, er den kopi nok. En ny container beholder ikke Unix-kontiene. En fil, der endnu ikke findes, får cp til at melde den og afslutte med en kode, der ikke er nul, og de filer, der findes, bliver stadig kopieret; router-tilstanden findes først efter AgentX' første lagring.
docker stop agentx docker run --rm --platform linux/amd64 --entrypoint cp -v agentx-data:/var/lib/agentx -v agentx-root:/root -v agentx-home:/home -v "$PWD/backup":/backup agentxhq/agentx-daemon:latest -a /var/lib/agentx/agentx.db /var/lib/agentx/router-state.json /var/lib/agentx/identity.json /root /home /backup/ docker start agentx
På en ny container lægger du filerne tilbage i volumerne før den første start. Start den nye container med den samme docker run -d-kommando, du brugte før, og tag -e AGENTX_REMOTE_SHELL=on med kun, hvis du havde den slået til. Fra version 0.184.4 forbliver kontakten slået fra, når den variabel udelades. På et ældre image starter et shell, uanset hvad variablen siger. Den første start installerer agentværktøjerne og kræver netværk, så vent til den er færdig, før du stopper containeren. Denne kopi tager ikke /var/lib/agentx/tools med, så den nye container installerer agentværktøjerne igen ved første start. Start en session først, når loggene siger agent CLIs are ready.
docker run --rm --platform linux/amd64 --entrypoint sh -v agentx-data:/var/lib/agentx -v agentx-root:/root -v agentx-home:/home -v "$PWD/backup":/backup agentxhq/agentx-daemon:latest -c 'cp -a /backup/agentx.db /backup/router-state.json /backup/identity.json /var/lib/agentx/ && cp -a /backup/root/. /root/ && cp -a /backup/home/. /home/'
På en ren container genskaber du hver konto og giver hjemmemappen tilbage til den bruger. Hvis den nye konto ikke får den uid, der ejer hjemmemappen, lader useradd alene Start session fejle. chown skal med.
docker exec agentx useradd --create-home --home-dir /home/<account> --shell /bin/bash <account> docker exec agentx chown -R <account>: /home/<account>
Hvis AgentX-tjenesten ikke vil starte, er enheden agentx. På Linux-desktop: systemctl --user status agentx-daemon og journalctl --user -u agentx-daemon. På en Mac LaunchAgent læser du ~/.agentx/log/launchd.err.log. På Windows: sc.exe query AgentX.
systemctl status agentx journalctl -u agentx
Hvis den ikke forbinder, eller konsollen viser den offline, er den ikke tilmeldt, router.enabled er false, eller broen kan ikke nås. Tjek at den kører, derefter loggen, derefter konfigurationsfilen.
Server- og desktopenhederne sætter ikke deres egne logfiler, så deres logge er journalen. AgentX startet i baggrunden skriver ~/.agentx/log/agentx.log. En Mac LaunchAgent skriver ~/.agentx/log/launchd.out.log og ~/.agentx/log/launchd.err.log. Homebrew skriver $(brew --prefix)/var/log/agentx.log og $(brew --prefix)/var/log/agentx.err.log. Windows skriver %USERPROFILE%\.agentx\log\agentx.log. Docker er docker logs agentx.