Agent Daily Operations Guide¶

This guide is for users who have already installed the Agent service. It explains how to check runtime status, manage the service, edit configuration, view logs, update manually, and uninstall the Agent.

The following commands apply to Linux/systemd installations. Service management, configuration changes, and uninstall operations usually require sudo privileges on the host.

Common Paths¶

After installation, Agent files are located in the following default paths:

Check Service Status¶

Check whether the Agent is running:

systemctl status beak-agent

Check only whether the service is active:

systemctl is-active beak-agent

Check the installed Agent version:

/usr/local/bin/beak-agent --version

Check the runtime user:

systemctl show beak-agent -p User -p Group

By default, the Agent service runs as the beak-agent user instead of staying resident as root. root is mainly used for host management actions such as installation, upgrade, and uninstall.

Start, Stop, and Restart¶

Start the Agent:

sudo systemctl start beak-agent

Stop the Agent:

sudo systemctl stop beak-agent

Restart the Agent:

sudo systemctl restart beak-agent

After changing configuration, restart the service to apply the new settings:

sudo systemctl restart beak-agent

View Logs¶

View recent systemd logs:

journalctl -u beak-agent -n 100

Follow new logs:

journalctl -u beak-agent -f

View the Agent main log file:

tail -n 100 /var/log/beak-agent/log

If the Agent cannot start, check these first:

systemctl status beak-agent
journalctl -u beak-agent -n 100

Edit Configuration¶

The Agent runtime configuration is stored by default at:

/etc/beak-agent/agent.env

Back up the file before editing:

sudo cp /etc/beak-agent/agent.env /etc/beak-agent/agent.env.bak

Edit the configuration:

sudo vi /etc/beak-agent/agent.env

Common settings:

LLM_MODEL is no longer required. Newer runtimes use default as the model identifier. If an old active LLM_MODEL=... entry remains in the configuration, keep it only when you intentionally want to pin a model; otherwise remove that line and restart the service.

Restart the service after editing:

sudo systemctl restart beak-agent

If an incorrect configuration prevents the service from starting, restore the backup:

sudo cp /etc/beak-agent/agent.env.bak /etc/beak-agent/agent.env
sudo systemctl restart beak-agent

Manual Update and Rollback¶

The Agent can switch versions through the local updater.

Check and update to the latest version from the release source:

sudo /usr/local/bin/beak-agent-updater

Install a specific version:

sudo /usr/local/bin/beak-agent-updater --target-version v0.2.0

Rollback uses the same command. For example, roll back to v0.1.9:

sudo /usr/local/bin/beak-agent-updater --target-version v0.1.9

Check the automatic update timer:

systemctl status beak-agent-update-check.timer
systemctl list-timers beak-agent-update-check.timer

If the update fails, check:

• whether AGENT_UPDATE_BASE_URL in /etc/beak-agent/agent.env is correct;
• whether install.sh, the target package, and checksum files exist under the release address;
• whether journalctl -u beak-agent-update-check.service -n 100 contains download, verification, or scheduling errors;
• whether journalctl -u beak-agent -n 100 contains startup or restart errors.

Uninstall Agent¶

By default, the uninstall script only shows the uninstall plan and does not delete anything:

curl -fsSL https://static.guance.com/beak/uninstall.sh | sudo bash

After confirming the plan, run with --yes to uninstall:

curl -fsSL https://static.guance.com/beak/uninstall.sh | sudo bash -s -- --yes

The uninstall process removes the following fixed objects:

• /usr/local/bin/beak-agent
• /usr/local/bin/beak-agent-updater
• /usr/local/bin/beak-agent-update-check
• /etc/beak-agent
• /var/lib/beak-agent
• /var/log/beak-agent
• beak-agent.service
• beak-agent-update-check.service
• beak-agent-update-check.timer
• /etc/sudoers.d/beak-agent
• the beak-agent user and group

The uninstall process does not remove skill runtime dependencies installed or checked by skill-dep.sh, such as system commands, language runtimes, Python/Node packages, fonts, or other system packages. These dependencies may already exist on the host or be shared by other services, so the Agent uninstall flow must not remove them.

Common Checks¶

Agent Shows Offline on the Page¶

Check the following in order:

1. Whether the host service is running: systemctl status beak-agent
2. Whether the host network can access the service address;
3. Whether BEAK_WS_URL, AGENT_API_KEY, and AGENT_ID in /etc/beak-agent/agent.env are correct;
4. Whether recent logs contain authentication failures, network connection failures, or DNS resolution failures.

Configuration Changes Do Not Take Effect¶

Confirm that the service has been restarted:

sudo systemctl restart beak-agent

Then check logs to confirm that the new process has started:

journalctl -u beak-agent -n 50

Agent Version Does Not Change After Update¶

Check the current version first:

/usr/local/bin/beak-agent --version

Then check update logs:

journalctl -u beak-agent-update-check.service -n 100
journalctl -u beak-agent -n 100

For a specified-version update, confirm that the version in the command matches the version available in the release source.