AgentX

Language

Choose the language for the AgentX website.

Appearance

Choose how the AgentX website looks.

AgentX

Run AgentX on your machine.

Remote shell, configuration, upgrade, uninstall, backup and logs. The commands below are what you run on the machine. The hosted console cannot turn remote shell on.

Remote shell starts off.

A new AgentX install does not start a remote shell until its environment has AGENTX_REMOTE_SHELL=on. Unset, off, or any other value leaves it off. It is read once at startup, so a change takes a restart. The console and the config file cannot turn it on. From version 0.184.4, while the switch is off a shell start is refused. After a restart the console follows the switch when AgentX reconnects. On a server that can take up to a minute, and on Docker about 30 seconds. Until then the button can still show the previous state. Before version 0.184.4 AgentX has no switch: the button stays hidden, and a request to start a shell still starts one. On a Linux server, the switch is in AgentX from version 0.184.4.

Linux server, turn on
# /etc/default/agentx
AGENTX_REMOTE_SHELL=on
sudo systemctl restart agentx
Linux server, turn off
# /etc/default/agentx
AGENTX_REMOTE_SHELL=off
sudo systemctl restart agentx

On the Linux desktop package AgentX runs as the login user, and agents run as that same user, who can edit the AgentX service's environment. Open the user unit, add the Service lines below, then restart it. On the desktop package, the switch is in AgentX from version 0.184.4.

systemctl --user edit agentx-daemon
[Service]
Environment=AGENTX_REMOTE_SHELL=on
systemctl --user restart agentx-daemon

On a Mac the installed AgentX is a user LaunchAgent, or a Homebrew service with no user override. It runs as the logged-in user, and agents run as that user, who can edit the AgentX service's environment. Add the two lines below under EnvironmentVariables in ~/Library/LaunchAgents/com.agentx.daemon.plist, then reload the job. For Homebrew, set the same variable on the brew service and restart that job. On a Mac, the switch is in AgentX from 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

On Windows the service is named AgentX and runs as the person. From an elevated prompt, set the service Environment value, then stop and start the service. That command replaces any existing Environment value. To keep another entry, separate entries with \0. On Windows, the switch is in AgentX from 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

For Docker, pass the variable on docker run, or set it under environment: in a compose file. The volumes are agentx-data, agentx-root and agentx-home. Changing the variable means recreating the container. Recreating it without the variable leaves remote shell off from version 0.184.4. An older image starts shells whatever the variable says. For Docker, the switch is in AgentX from version 0.184.4. On an older image, the -e setting has no effect.

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"

If you started AgentX in a terminal, export the variable in that shell, stop AgentX, and start it again from the same shell. For AgentX started in a terminal, the switch is in AgentX from version 0.184.4.

export AGENTX_REMOTE_SHELL=on
agentx-daemon stop

In the hosted console, any signed-in member of the team can start a shell when AgentX has turned remote shell on, including a viewer. It is not limited to the owner.

From version 0.184.4, turning remote shell off stops a new shell. After a restart the button can take up to a minute on a server, and about 30 seconds on Docker, to follow the switch. Until then it can still show the previous state, and a start is refused if the switch is off. From the hosted console, an existing shell can still be resumed, attached, and typed in, and a message can still be sent. Typing into an agent terminal can run commands, for example ! in Claude Code. The switch does not change that.

To stop AgentX connecting to the hosted console, set router.enabled to false in the config file and restart. An environment variable cannot set it. The page on the machine still runs. The bridge address defaults to grpcs://bridge.agentxhq.io:443. AGENTX_BRIDGE_ADDR overrides it, and a non-empty router.bridge_addr in the file wins.

router:
  enabled: false

Configuration file and ports.

The config file is ~/.agentx/config.yaml for a normal user and /etc/agentx/config.yaml for root. Settings in the file are overlaid by environment variables named AGENTX_ plus the setting. AGENTX_REMOTE_SHELL is not one of those settings, and router.enabled cannot be set from the environment. The database defaults to agentx.db in the data directory, and the router state to router-state.json beside it. For root that data directory is /var/lib/agentx. An agent that runs as root keeps its files in /root/.agentx/<name>. An agent with its own account keeps them in that account's home. The commands below copy the account homes. To keep the files of an agent that runs as root, copy /root/.agentx as well.

The web page listens on 127.0.0.1:3333 and the local port on 127.0.0.1:3334, unless you change them. AGENTX_SERVER_ADDR overrides the web address. A non-empty surfaces.web.listen_addr in the config file replaces the web address. The Docker image sets the web address to 0.0.0.0:3333.

Upgrade and uninstall.

Upgrade the same flavor you installed. An upgrade keeps the enrollment, the agents and their files. On a Linux server, install the new package as its own system job so the restart does not depend on the session you are in. Use dnf or pacman the same way when that is the package you have.

Linux server upgrade
sudo systemd-run --unit=agentx-upgrade --collect apt-get install -y "$PWD/<filename>"

The name in that command is the package file you downloaded. Download it from the install page. For Docker, run the upgrade command.

On a Mac with Homebrew, brew upgrade agentx, then launchctl kickstart -k of the job that is running. Without Homebrew, run ./install.sh without --launchd, then kickstart the LaunchAgent. On Windows, Stop-Service AgentX, copy the new programs into C:\Program Files\AgentX\, then Start-Service AgentX. For Docker, pull the image and recreate the container with the same volumes. A new container does not keep Unix accounts of agents that have their own user. Run useradd and chown again for each such account.

Uninstall stops AgentX and leaves its files. On a Linux server: apt remove, or dnf remove, or pacman -R, of agentx-server. The desktop package is agentx-desktop, and ~/.agentx stays. On a Mac, agentx-daemon stop, then launchctl bootout gui/$(id -u)/com.agentx.daemon, then remove the plist. brew uninstall agentx is the Homebrew remove. On Windows, sc.exe stop AgentX and sc.exe delete AgentX. For Docker:

sudo apt remove agentx-server
docker rm -f agentx

Deleting data is a separate step. Remove the data directory, or remove the three Docker volumes. That delete is not part of uninstall.

docker volume rm agentx-data agentx-root agentx-home

Backup and restore.

There is no backup command. Stop AgentX, copy the database, the router state, identity.json, the config file, and on a server the environment file, then start it again. On the same machine, while the Unix accounts are still there, that file copy is enough. The backup folder in the server command has to exist already. A file that does not exist yet makes cp report it and exit non-zero, and the files that do exist are still copied; the router state file exists only after AgentX's first save. /etc/default/agentx is where the server package reads AGENTX_REMOTE_SHELL. The backup contains the AgentX service's private key. Keep it as private as a password.

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

An agent created with its own user also needs that Unix account, with the same name, and its home. The console shows the account name under Run as. That home contains ~/.agentx/<name>, and the backup copies the home.

sudo cp -a /home/<account> /path/to/backup/

Restore of the AgentX files is the same copy in reverse, while AgentX is stopped. A restore of the database and config.yaml without /etc/default/agentx leaves remote shell off from version 0.184.4, because the switch defaults off. Before that version AgentX has no switch, and a request to start a shell still starts one. On a clean machine, recreate each such account and put its home back. That home includes ~/.agentx/<name>. If the new account does not get the uid that owns the home, useradd alone leaves Start session failing. The chown is required.

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/

For Docker, stop the container and copy the database, the router state, and identity.json out of the agentx-data volume, and copy the agentx-root and agentx-home volumes, with the image's cp, then start the container. On the same container, while the accounts are still there, that copy is enough. A new container does not keep the Unix accounts. A file that does not exist yet makes cp report it and exit non-zero, and the files that do exist are still copied; the router state file exists only after AgentX's first save.

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

On a new container, restore the files into the volumes before the first start. Start the new container with the same docker run -d command you used before, and include -e AGENTX_REMOTE_SHELL=on only if you had it on. Leaving that variable out leaves the switch off from version 0.184.4. An older image starts shells whatever the variable says. The first start installs the agent tools and needs network, so wait for it to finish before you stop the container. This copy leaves out /var/lib/agentx/tools, so the new container installs the agent tools again on its first start. Start a session only after the logs say 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/'

On a clean container, recreate each account and give the home back to that user. If the new account does not get the uid that owns the home, useradd alone leaves Start session failing. The chown is required.

docker exec agentx useradd --create-home --home-dir /home/<account> --shell /bin/bash <account>
docker exec agentx chown -R <account>: /home/<account>

If it will not start or connect.

If the AgentX service will not start, the unit is agentx. On the Linux desktop, systemctl --user status agentx-daemon and journalctl --user -u agentx-daemon. On a Mac LaunchAgent, read ~/.agentx/log/launchd.err.log. On Windows, sc.exe query AgentX.

systemctl status agentx
journalctl -u agentx

If it does not connect, or the console shows it offline, it is not enrolled, router.enabled is false, or the bridge cannot be reached. Check that it is running, then the log, then the config file.

Where the logs are.

The server and desktop units do not set their own log files, so their logs are the journal. AgentX started in the background writes ~/.agentx/log/agentx.log. A Mac LaunchAgent writes ~/.agentx/log/launchd.out.log and ~/.agentx/log/launchd.err.log. Homebrew writes $(brew --prefix)/var/log/agentx.log and $(brew --prefix)/var/log/agentx.err.log. Windows writes %USERPROFILE%\.agentx\log\agentx.log. Docker is docker logs agentx.