Agent Daily Usage Manual¶

This document is intended for users who have completed the Agent service installation. It explains how to check Agent status, manage the service, modify configurations, view logs, collect a Session Bug Report, 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.

Find Agent Files¶

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

Skill and MCP Updates¶

The Agent loads its base configuration and connects before it prepares Skills and MCP resources one at a time. Chat remains available during dependency preparation. Later requests in existing sessions can use newly prepared capabilities.

Skills with dependencies must pass checks first. Host installations add missing dependencies or versions that meet the requirements. Container images must provide the dependencies. If an update fails, that resource becomes unavailable and does not fall back to the old version. Other ready resources remain available. Normal synchronization runs about every ten minutes by default. Failures retry after 30 seconds; success restores the normal interval. If you configure a shorter interval, retries use that interval.

Check preparation results on the Agent Skill or MCP page. If a local resource is ready but its status has not changed, the reporting connection may have failed. A later synchronization reports it again. You do not need to reinstall or create a session.

Check Agent Status¶

Check if the Agent is running:

systemctl status obs-agent

Check only if the service is active:

systemctl is-active obs-agent

Check the currently installed Agent version:

/usr/local/bin/obs-agent --version

Check the Agent's running user:

systemctl show obs-agent -p User -p Group

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

Start, Stop, or Restart Agent¶

Start the Agent:

sudo systemctl start obs-agent

Stop the Agent:

sudo systemctl stop obs-agent

Restart the Agent:

sudo systemctl restart obs-agent

After modifying configurations, a service restart is usually required for the new configurations to take effect:

sudo systemctl restart obs-agent

View Agent Logs¶

View recent systemd logs:

journalctl -u obs-agent -n 100

Continuously view the latest logs:

journalctl -u obs-agent -f

View the Agent's main log file:

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

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

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

Collect an Offline Local Bug Report¶

When the Agent cannot connect to Beak, model calls fail, or Session tools cannot run, execute this command directly on the Agent host:

obs-agent --bug-report

The default depth is 0. It collects host, process, configuration, logs, all discoverable Sessions, and runtime evidence without exporting deep LLM evidence. The report is written to the current directory by default. Use --bug-report-output to specify a complete ZIP path, not a directory; the destination must not exist and its parent directory must already exist:

obs-agent --bug-report --bug-report-output /var/tmp/report.zip --depth 2

The command does not start the normal Agent runtime, connect WebSocket, call a model, request approval, or upload files. stdout contains exactly one JSON line. status is completed or partial, with the absolute path, size, SHA-256, and stable error codes. Both statuses mean the ZIP passed safety validation and return exit code 0.

For a separate configuration file, add --env-file /etc/obs-agent/agent.env and run as an account that can read the Agent cache and local diagnostic endpoint. Depth is 0..3: depth 1 records call structure; depth 2 adds redacted provider requests, responses, and tool evidence. The running Agent must already use AGENT_DIAGNOSTIC_CHAT_DEPTH=2 or higher; earlier calls cannot be reconstructed. Depth 3 is local-only, is marked UNREDACTED, and preserves unredacted content. Do not share it directly.

Open the report locally with:

obscli bug-report view /var/tmp/report.zip

The Viewer supports basic, historical deep-LLM, and unified reports without uploading the archive.

By default, a running Agent exposes a mode-0600 local diagnostic endpoint at diagnostics/runtime.sock under the profile cache. It collects heap and goroutine profiles, a 30-second CPU profile, a 5-second runtime trace, command line, metrics, and runtime timeline. The endpoint uses only a Unix socket and never listens on TCP. Set AGENT_LOCAL_DIAGNOSTICS_ENABLED=false in agent.env to disable it.

In a container, generate and copy a report with:

docker exec obs-agent obs-agent --bug-report --bug-report-output /app/obs-agent-support.zip
docker cp obs-agent:/app/obs-agent-support.zip ./obs-agent-support.zip

There is no fixed ZIP size limit; collection preserves dynamic free space on the output filesystem. Check size_bytes and sha256 before copying. Depths 0–2 can still contain redacted configuration, Session content, logs, and runtime evidence. Depth 3 contains unredacted content. Files use mode 0600; transfer them only through controlled support channels and delete them after use.

Collect a Session Bug Report¶

When an Agent responds unexpectedly, a tool stalls, or the connection is unstable, you can ask the Agent in the affected Session to collect, sanitize, and upload a diagnostic report. The Agent can also send the temporary download link directly to a designated support email address, so you do not need to download and forward the report manually.

For instructions, permission details, email delivery, and failure handling, see Collect and Send an Agent Bug Report from a Session.

Online collection is limited to the current Session, accepts chat_depth=0..2, defaults to 0, follows Session authorization, and uploads the report. chat_depth=3 is rejected.

Modify Agent Configuration¶

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

/etc/obs-agent/agent.env

It is recommended to back up before modification:

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

Edit the configuration:

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

Common configurations include:

If the Agent must access Beak, an LLM, or release services through an enterprise proxy, configure the proxy variables and enterprise CA as described in Configure an obs-agent forward proxy.

LLM_MODEL is optional. The default is auto routing. Existing LLM_MODEL=default settings load as auto; the Agent does not change the file. Set a real model ID only when you need a fixed model. Otherwise, remove the line and restart the service. BYOK uses its catalog default and is not affected by this environment variable.

After modification is complete, restart the service:

sudo systemctl restart obs-agent

If a configuration error causes the service to fail to start, you can restore from the backup:

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

Personal Owl Key Mode¶

The Agent uses its installation Owl credentials by default. In personal Owl Key mode, ordinary sessions use the session creator's personal Open API Key. Scheduled tasks and user Webhooks use the configuration creator's Key. Follow-up questions do not switch to the sender's Key. IM and its derived delegation keep installation credentials. A missing, disabled, or deleted personal Key rejects execution without an installation-credential fallback.

First upgrade the matching Beak, Backend/Connector, Owl, and Agent components. Confirm that the creator's personal Key is synchronized. Owl must support runtime-profile/v1; installation checks its actual capability. Save the installation setting in the matching frontend, then explicitly reinstall the Agent to apply AGENT_OWL_USER_TOKEN_ENABLED=true. Its default is false. Ordinary upgrades preserve the local mode. Saving the setting or restarting does not apply a new installation mode.

Each identity uses isolated Owl Profile and query-result directories. Historical results from the default directory are not copied. Key rotation or revocation cancels running and queued work that uses the old Key. Send a new request when needed. For access denials, check the creator's role and query permissions in the target workspace. Do not use other credentials to bypass the denial. Profile isolation does not provide an operating-system sandbox for arbitrary scripts under the same system user.

Review Backend outbox database changes before deployment. Deploy Beak with this mode disabled, then Backend/Connector, Owl with the new capability and the complete Agent distribution, and the frontend. Save the setting and reinstall to enable it. Before rollback, disable the mode and reinstall. Preserve credential revision watermarks and existing encryption settings so old credentials cannot overwrite new state.

Manually Update or Roll Back Agent¶

From v0.16.0, hosts that support the new maintenance protocol finish existing work before stopping the old process, installing the complete distribution, and validating startup and the running executable version. Sessions show maintenance, success, failure, and recovery results. Messages submitted during maintenance remain in Beak and resume automatically after reconnection. Usable dependencies remain installed; missing dependencies are added. Download or validation failures restore the previous distribution through the existing recovery flow.

The internal version convergence loop, obscli agent pin-version, and POST /api/v1/agents/{id}/version:pin are removed. AGENT_UPDATE_ENABLED and AGENT_UPDATE_CHECK_INTERVAL_SECONDS no longer apply. The local systemd timer triggers automatic upgrades, controlled by AGENT_LOCAL_AUTO_UPDATE_ENABLED. Existing updater invocations remain supported. --target-version selects the target for one operation and does not create a persistent version pin.

The Agent can switch versions through the local updater.

Older updaters can use the existing upgrade commands without manual replacement. Agents that support idle protection wait for active tasks to finish. New conversations accepted by Beak during an upgrade are retried automatically after reconnection. Older Agents without the idle protocol restart directly during their first transition, which may interrupt active conversations. Subsequent upgrades use idle protection.

If a managed upgrade fails, the installer attempts to restore the previous binary, configuration, and service while retaining failure diagnostics. Retries for the same target follow the existing backoff policy; a new target does not inherit the previous target's delay.

Update to the latest version in the release source:

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

Even if the Agent is already on latest, this command performs a complete upgrade to retry installation of components such as the matching Browser runtime. Background timer checks do not reinstall these components when the version is unchanged.

Install a specific version:

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

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

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

Check the status of the automatic update timer:

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

If the update fails, prioritize checking:

• Whether AGENT_UPDATE_BASE_URL in /etc/obs-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 obs-agent-update-check.service -n 100;
• Whether there are startup or restart errors in journalctl -u obs-agent -n 100.

Automatic updates read proxy variables from /etc/obs-agent/agent.env. For proxy-specific checks, see Keep automatic updates on the proxy.

Uninstall Agent¶

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

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

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

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

Uninstallation will delete the following fixed objects:

• /usr/local/bin/obs-agent
• /usr/local/bin/obs-agent-updater
• /usr/local/bin/obs-agent-update-check
• /etc/obs-agent
• /var/lib/obs-agent
• /var/log/obs-agent
• obs-agent.service
• obs-agent-update-check.service
• obs-agent-update-check.timer
• /etc/sudoers.d/obs-agent
• obs-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 obs-agent
2. Can the host network access the service address;
3. Whether BEAK_WS_URL, AGENT_API_KEY, AGENT_ID in /etc/obs-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 obs-agent

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

journalctl -u obs-agent -n 50

Agent Version Not Changed After Update¶

First check the current version:

/usr/local/bin/obs-agent --version

Then check the update logs:

journalctl -u obs-agent-update-check.service -n 100
journalctl -u obs-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.