Application Update

Nekro Agent regularly releases updates, including feature improvements, bug fixes, and security patches. This document will introduce how to safely update your Nekro Agent instance.

🚀 Orchestration Update (Recommended)

Nekro Agent provides convenient orchestration update commands. When a new version is released, you can use the following one-click command to update the application

Notes

If you used Wsl or OrbStack virtual machine deployment, the following commands need to be executed inside the virtual machine

Enter Data Directory

# If you modified the data directory, please set it according to the actual situation
export NEKRO_DATA_DIR=${HOME}/srv/nekro_agent && \
cd ${NEKRO_DATA_DIR}

Update Only Nekro Agent and Sandbox Images (Recommended)

sudo docker pull kromiose/nekro-agent-sandbox:latest && \
sudo docker-compose --env-file .env pull nekro_agent && \
sudo docker-compose --env-file .env up --build -d nekro_agent

Update All Images and Restart Containers (If you need to update NapCat or other data support services at the same time)

This command will update the nekro-agent image and all dependent images, which may cause the Bot to go offline and require re-login

sudo docker pull kromiose/nekro-agent-sandbox:latest && \
sudo docker-compose --env-file .env pull && \
sudo docker-compose --env-file .env up --build -d

🧪 Switch to Preview

If you want early access to the latest features, or want to help test changes that have not yet reached a stable release, you can switch the deployment image from latest to preview.

Notes

• preview tracks the main branch and is updated more frequently, so it may include changes that are not yet fully validated.
• If your instance is used for stable production workloads, staying on latest is recommended.
• The steps below assume you are using the docker-compose.yml generated by the installation script and that it is located in your data directory.

Step 1: Check the current image tag

grep -n "image: kromiose/nekro-agent" docker-compose.yml

If the output already shows kromiose/nekro-agent:preview, you can directly run the upgrade command below.

Step 2: Change the main image tag from latest to preview

sed -i 's|image: kromiose/nekro-agent:latest|image: kromiose/nekro-agent:preview|g' docker-compose.yml

If you are using the built-in macOS sed, use:

sed -i '' 's|image: kromiose/nekro-agent:latest|image: kromiose/nekro-agent:preview|g' docker-compose.yml

Then verify the change:

grep -n "image: kromiose/nekro-agent" docker-compose.yml

Step 3: Pull preview images and upgrade

sudo docker pull kromiose/nekro-agent-sandbox:preview && \
sudo docker-compose --env-file .env pull nekro_agent && \
sudo docker-compose --env-file .env up --build -d nekro_agent

If you also want to update NapCat or other dependent services at the same time, use:

sudo docker pull kromiose/nekro-agent-sandbox:preview && \
sudo docker-compose --env-file .env pull && \
sudo docker-compose --env-file .env up --build -d

Step 4: Confirm the switch succeeded

sudo docker-compose --env-file .env ps

To inspect the main service logs:

sudo docker-compose --env-file .env logs -f nekro_agent

How to switch back to stable

Change the image tag in docker-compose.yml back to latest, then run the stable update command again:

sed -i 's|image: kromiose/nekro-agent:preview|image: kromiose/nekro-agent:latest|g' docker-compose.yml

📝 Update Logs

After each update, you can check the GitHub Releases to view the update logs and understand the changes