Agent Daily Usage Manual¶

This document is intended for regular users who have completed the Agent service installation. It explains how to check the Agent's running status, manage the service, modify configurations, view logs, manually update, and uninstall the Agent.

The following commands apply to the Linux/systemd installation method. Executing service management, configuration modification, and uninstallation commands typically requires sudo privileges on the host.

Common Paths¶

After default installation, Agent-related files are located in the following locations:

Check Service Status¶

Check if the Agent is running:

systemctl status beak-agent

Check only if the service is active:

systemctl is-active beak-agent

Check the currently installed Agent version:

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

Check the Agent's running user:

systemctl show beak-agent -p User -p Group

By default, the Agent service runs as the beak-agent user, not as root persistently. root is primarily used for host management actions like installation, upgrade, and uninstallation.

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 modifying configurations, a service restart is usually required for the new configurations to take effect:

sudo systemctl restart beak-agent

View Logs¶

View recent systemd logs:

journalctl -u beak-agent -n 100

Continuously view the latest logs:

journalctl -u beak-agent -f

View the Agent's main log file:

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

If the Agent fails to start, it is recommended to first check:

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

Modify Configurations¶

The Agent's runtime configuration is by default written to:

/etc/beak-agent/agent.env

It is recommended to back up before modification:

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

Edit the configuration:

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

Common configurations include:

LLM_MODEL is no longer a required configuration. The new version runtime defaults to using the default model identifier; if an active LLM_MODEL=... remains in the old configuration, it is only recommended to keep it if you indeed need to fix the model. Otherwise, you can delete that line and restart the service.

After modification is complete, restart the service:

sudo systemctl restart beak-agent

If a configuration error causes the service to fail to start, you can restore from 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 via the local updater program by default.

Manually check and update to the latest version in 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

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

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

Check the status of the automatic update timer:

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

If the update fails, prioritize checking:

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

Uninstall Agent¶

The uninstall script by default only shows the uninstall plan and does not delete any content:

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

After confirming it's correct, execute a complete uninstall with --yes:

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

Uninstallation will delete 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
• beak-agent user and user group

Uninstallation will not delete 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 be shared components originally present on the host or may be reused by other services and cannot be removed by the Agent uninstallation process.

Common Checks¶

Agent Shows as Offline in the Page¶

It is recommended to check in order:

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

Agent Configuration Changes Not Taking Effect¶

Confirm if the service has been restarted:

sudo systemctl restart beak-agent

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

journalctl -u beak-agent -n 50

Agent Version Not Changed After Update¶

First check the current version:

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

Then check the update logs:

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

If it's a specified version update, confirm that the version number in the command matches the version number in the release source.