Agent Container Installation Manual¶
This document explains how to install obs-agent with Docker and Kubernetes. If you are installing on Kubernetes, prefer Helm.
These examples use v0.19.0. Before using the new image, administrators must complete the Beak CDN configuration upgrade and verify that installation configuration v2 supplies the target brand CDN.
When the container starts, it uses BEAK_WS_URL, AGENT_ID, and AGENT_API_KEY to load runtime configuration from Beak, then starts the agent.
Container installations use environment variables only. They do not read or generate config.toml. Use the Docker, Compose, or Kubernetes environment settings below. Docker can still use --env-file to inject environment variables. Do not pass --config or --env-file file arguments to the Agent.
To search private code repositories, see Use git-rg and configure repository credentials.
Persistent storage is a runtime prerequisite.
/appstores active session/task JSONL history and related data, while the other two directories store profile and Owl data. Docker, Kubernetes YAML, and Helm deployments must provide persistent storage for/app,/var/lib/obs-agent/profile-cache, and/app/.owl. Mount the Owl volume separately at/app/.owl. Otherwise, active sessions/tasks may be unable to continue after a container or Pod rebuild or upgrade.
If the container node cannot access Beak, the LLM, or other public services directly, first read Configure an obs-agent forward proxy.
Execution Permissions and Container Security¶
Agent startup and tool execution no longer require Linux user namespaces or install additional tool seccomp filters. Docker uses its runtime default seccomp profile; Kubernetes YAML and Helm use RuntimeDefault. If an older deployment explicitly set seccomp=unconfined or Unconfined, recreate the container or update the workload security settings. When using Helm --reuse-values, explicitly override securityContext.seccompProfile.type=RuntimeDefault.
Containers run as a non-root user, drop all capabilities, and prevent privilege escalation. Neither --privileged nor SYS_ADMIN is required. These settings still constrain tools; Full Access does not grant root or host privileges. Operations requiring sudo work only where the deployment already grants the required OS permissions and allows privilege escalation. The standard container configuration does not grant these permissions.
Application approval controls whether a tool call runs; operating-system authorization controls file access and sudo. General-purpose Bash, Python, exec, Owl, and local stdio MCP do not provide a process sandbox. Programs with sufficient OS privileges can read or write configuration, so configuration-tool field and role checks are not an isolation boundary that a general-purpose shell cannot bypass.
Skill Dependencies and Online Updates¶
The v0.15.0 and v0.15.1 container images do not include the Skill dependency preparer. A Skill with dependency declarations can remain unavailable even when the git-rg command is installed. Upgrade to v0.15.2 or a newer image.
The fixed image includes a Skill dependency checker and configures it as the default preparer through AGENT_SKILL_DEP_INSTALLER. When the Agent receives a Skill update notification or finds a new Skill during periodic sync, it checks required commands, Debian packages, Python packages, and their versions in the image before making the Skill available. No container restart is required when dependencies are satisfied. Skills without dependency declarations go directly to publication.
This checker does not run apt, pip, or sudo installations in a running container. If a dependency is missing or its version is unsuitable, that Skill is unavailable and does not fall back to the old version. Other ready Skills remain available. Logs identify missing items and request an image update. Add the dependencies to the image and redeploy with the same three persistent volumes. Host installations keep their own dependency installer and can prepare new Skill dependencies within existing OS permissions.
The Agent connects before it prepares Skills one at a time. Chat remains available during dependency checks. Normal synchronization runs about every ten minutes by default. Preparation or status reporting failures retry after 30 seconds; success restores the normal interval. A shorter configured interval also applies to retries. A status reporting failure does not remove a locally prepared Skill or reinstall it when reporting again.
Setting AGENT_SKILL_DEP_INSTALLER in an old container does not add the missing checker. Recreate the container or update the workload with an image that includes it.
Prepare Connection Information¶
Copy these values from the Beak console or installation page. Docker and Kubernetes YAML installations use all three values. Branded Helm Charts already contain the default Beak address and use only AGENT_ID and AGENT_API_KEY unless you need to override that address:
export BEAK_WS_URL='https://agent-api.guance.com'
export AGENT_ID='replace-with-agent-uuid'
export AGENT_API_KEY='replace-with-agent-api-key'
Prepare the image address:
Install with Docker¶
Docker deployments must create and remount the three named volumes shown below. Reuse the same volume names during upgrades and restarts; do not replace them with container-temporary directories. A bind mount managed independently from the container is also supported.
Create an env file:
cat > obs-agent.env <<EOF
BEAK_WS_URL=${BEAK_WS_URL}
AGENT_ID=${AGENT_ID}
AGENT_API_KEY=${AGENT_API_KEY}
EOF
To use a custom OpenAI-compatible model while retaining AIHub Web Search and Mail, have a deployment system outside Beak append the following configuration:
cat >> obs-agent.env <<EOF
LLM_BASE_URL=https://user-llm.example.com/v1
LLM_API_KEY=replace-with-user-llm-api-key
LLM_MODEL=custom-model
EOF
Model requests use LLM_API_KEY; Web Search and Mail use AGENT_API_KEY. At startup, the container obtains model, search, and email endpoints independently from Beak. Each uses a non-empty Connector deployment setting first, then the corresponding Beak SaaS default. Non-empty local settings override the matching platform defaults, so changing only the model does not require repeating search or email endpoints. To use another search or email service, set AGENT_WEB_SEARCH_BASE_URL or AGENT_SEND_EMAIL_BASE_URL separately. Tool endpoints are never derived from the model endpoint.
Before using the new container image, upgrade Beak and configure all three service defaults explicitly, even if they share the same URL. Missing or invalid endpoints returned by Beak cause the container to fail before starting the Agent; local tool endpoints do not replace the required server configuration. To disable a tool, set AGENT_WEB_SEARCH_ENABLED=false or AGENT_SEND_EMAIL_ENABLED=false instead of omitting its endpoint.
Non-empty container environment values take precedence over Beak defaults. Remote install-config is parsed as literal data through a fixed allowlist and is never sourced or executed. Unknown fields, including repeated unknown fields, are silently ignored and are not exported. Conflicting identity fields, duplicate known fields, malformed responses, and incomplete endpoint/credential sources still stop the container before Agent startup without printing secrets.
This behavior is available from the v0.14.1 image. If an older image fails with unsupported Beak install config field, upgrade to v0.14.1 or a newer published image after release, then recreate the Docker container or update the Kubernetes workload while preserving identity settings and data volumes. Restarting an older image does not add this compatibility behavior. Replacing the image does not require the old Agent to start successfully.
Start the container:
docker run -d \
--name obs-agent \
--restart unless-stopped \
--user 10001:10001 \
--cap-drop ALL \
--security-opt no-new-privileges=true \
--env-file ./obs-agent.env \
-v obs-agent-work:/app \
-v obs-agent-profile-cache:/var/lib/obs-agent/profile-cache \
-v obs-agent-owl:/app/.owl \
"${OBS_AGENT_IMAGE}"
Check status:
The following log lines indicate that startup succeeded:
Upgrade the image:
OBS_AGENT_IMAGE="${OBS_AGENT_IMAGE%:*}:v0.19.0"
docker pull "${OBS_AGENT_IMAGE}"
docker rm -f obs-agent
docker run -d \
--name obs-agent \
--restart unless-stopped \
--user 10001:10001 \
--cap-drop ALL \
--security-opt no-new-privileges=true \
--env-file ./obs-agent.env \
-v obs-agent-work:/app \
-v obs-agent-profile-cache:/var/lib/obs-agent/profile-cache \
-v obs-agent-owl:/app/.owl \
"${OBS_AGENT_IMAGE}"
Remove the Docker installation:
The docker volume rm command below permanently deletes session/task history and related data. Run it only after confirming that no task needs to be restored or continued.
Browser Settings¶
Use the standard Agent image. It includes the required shared libraries and Chinese fonts. Browser is enabled by default: an unset or empty AGENT_BROWSER_ENABLED means true. Container startup installs or reuses Browser programs without extra configuration.
To disable Browser, set this in the Docker obs-agent.env file:
Recreate the container with the same image and its three existing persistent volumes. docker restart alone does not read a changed env file. Add the same environment variable to Kubernetes YAML, or set it in Helm values:
First startup needs access to the image's Agent download address and Chrome for Testing (AMD64) or Debian Chromium package downloads (ARM64; old packages can come from Debian Snapshot). The entrypoint verifies and installs fixed versions of agent-browser and the browser as a non-root user. Downloads can take time. Programs are cached in /var/lib/obs-agent/profile-cache/browser-runtime. Restart, recreation, and rollback reuse a complete verified cache that matches the image. A complete cache works offline; first installation or a damaged cache needs network access. Keep the existing profile-cache volume.
Download or health-check failures produce a Browser-unavailable diagnostic, while the ordinary Agent can still start. Sandbox checks are not disabled automatically. If the node restricts Chromium user namespaces, have the administrator check node policy instead of granting container privileges directly.
An explicit AGENT_BROWSER_ENABLED=false prevents downloads and Browser tools even if a cache exists. Existing deployments with an explicit false keep that setting. Set it to true and recreate the container or update the workload to enable Browser again. The cache stores only programs, not website Cookies, login state, or session approvals. This startup switch does not change Browser session approval rules. Native installation remains unchanged.
Install with Kubernetes YAML¶
If you do not use Helm, you can use the base manifest published to OSS directly.
The base manifest creates and mounts three PVCs (20 GiB, 5 GiB, and 5 GiB). Before installation, the cluster must have a default StorageClass for dynamic provisioning or pre-created PVs that the PVCs can bind to. A Pod remains Pending while its PVCs are unbound. Do not replace them with emptyDir, because a Pod rebuild or upgrade would lose active session/task JSONL history and related data.
Download the manifest:
Download a specific version of the manifest:
Create the namespace:
The manifest stores the Beak address and Agent credentials in environment variables. Make sure envsubst is installed, then expand only these three variables so characters such as / and & in URLs or credentials are not interpreted by a replacement command:
envsubst '${BEAK_WS_URL} ${AGENT_ID} ${AGENT_API_KEY}' \
< obs-agent.yml \
| kubectl -n obs-agent apply -f -
obs-agent.yml already includes a Kubernetes Secret. The envsubst command writes the current credentials into these fields:
apiVersion: v1
kind: Secret
metadata:
name: obs-agent-secret
type: Opaque
stringData:
AGENT_API_KEY: "${AGENT_API_KEY}"
AGENT_ID: "${AGENT_ID}"
Check status:
kubectl -n obs-agent get pods
kubectl -n obs-agent get deploy
kubectl -n obs-agent logs -f deploy/obs-agent
When upgrading, download the new obs-agent.yml, keep the current BEAK_WS_URL, AGENT_ID, and AGENT_API_KEY, then run:
envsubst '${BEAK_WS_URL} ${AGENT_ID} ${AGENT_API_KEY}' \
< obs-agent.yml \
| kubectl -n obs-agent apply -f -
Keep and reuse the existing PVCs during an upgrade. Deleting a PVC or namespace may also delete the underlying PV data, depending on the StorageClass reclaim policy.
Remove the YAML installation:
The commands below delete the PVCs created by the manifest. Whether the underlying PV data is retained depends on the StorageClass reclaim policy. Run them only after confirming that no task needs to be restored or continued.
Install with Kubernetes Helm¶
The Helm chart creates and mounts three PVCs (20 GiB, 5 GiB, and 5 GiB) by default. Before installation, configure a default StorageClass or specify three bound PVCs through persistence.work.existingClaim, persistence.profileCache.existingClaim, and persistence.owl.existingClaim. Do not disable these persistence entries, because a Pod rebuild or upgrade would lose active session/task JSONL history and related data.
Set the Helm repository address, then add the repository:
The Helm repository address is different from the container image repository. Do not use the later image.repository path with helm repo add.
export OBS_AGENT_HELM_REPO_URL='https://pubrepo.guance.com/chartrepo/obs-agent'
helm repo add obs-agent "${OBS_AGENT_HELM_REPO_URL}"
helm repo update obs-agent
helm search repo obs-agent
Create the namespace:
Create the agent secret:
kubectl -n obs-agent create secret generic obs-agent-secret \
--from-literal=AGENT_ID="${AGENT_ID}" \
--from-literal=AGENT_API_KEY="${AGENT_API_KEY}"
Branded Helm Charts include the default Beak address for the current brand, so normal installations do not need to set config.BEAK_WS_URL manually.
The Chart sets automountServiceAccountToken: false by default. Current Agent features do not require Kubernetes API credentials. ConfigMap, Secret, and PVC mounts do not depend on this token. If the Agent needs access to the Kubernetes API, add --set automountServiceAccountToken=true to the install or upgrade command and configure the required RBAC permissions for the ServiceAccount.
Install:
helm upgrade --install obs-agent obs-agent/obs-agent \
--namespace obs-agent \
--set image.repository=pubrepo.guance.com/guance/obs-agent \
--set image.tag=v0.19.0 \
--set secret.existingSecret=obs-agent-secret
Append --set-string config.BEAK_WS_URL="${BEAK_WS_URL}" only when using a custom Beak address, upgrading an older Chart without a branded default address, or installing the Chart directly from repository source at docs/examples/helm/obs-agent.
Check status:
kubectl -n obs-agent get pods
kubectl -n obs-agent get deploy -l app.kubernetes.io/instance=obs-agent
kubectl -n obs-agent logs -f deploy/obs-agent
If the Deployment name is not obs-agent, use the actual name from kubectl get deploy to view logs.
Upgrade:
helm upgrade obs-agent obs-agent/obs-agent \
--namespace obs-agent \
--reuse-values \
--set image.tag=v0.19.0 \
--set securityContext.seccompProfile.type=RuntimeDefault
If an older release already saved an incorrect or unresolved Beak address in its values, --reuse-values keeps that value. On the first upgrade to the fixed Chart, also pass --set-string config.BEAK_WS_URL="${BEAK_WS_URL}" to correct it. Later upgrades can continue reusing values.
Remove the Helm installation:
helm uninstall deletes PVCs created by the chart, and kubectl delete namespace also deletes PVCs in that namespace. Whether underlying PV data is retained depends on the StorageClass reclaim policy. Run these commands only after confirming that no task needs to be restored or continued.
View Available Environment Variables¶
All installation methods require AGENT_ID and AGENT_API_KEY. Docker and Kubernetes YAML also require BEAK_WS_URL. Branded Helm Charts provide a default address, so override it only for custom endpoints or older Charts. The remaining variables below are for troubleshooting or overriding defaults.
| Environment Variable | Manual Configuration Required | Description |
|---|---|---|
BEAK_WS_URL |
Docker/YAML: Yes; branded Helm: No | Beak config API address, such as https://agent-api.guance.com. Branded Helm Charts include a default and allow overrides through config.BEAK_WS_URL. |
AGENT_ID |
Yes | Agent instance ID. Each running instance must be unique. |
AGENT_API_KEY |
Yes | Credential used by Agent to access the Beak config API and WebSocket. |
BEAK_ENDPOINT |
No | Fallback address used by the container entrypoint when reading the Beak config API. If unset, BEAK_WS_URL is used. |
HTTP_PROXY / http_proxy |
No | HTTP forward proxy for HTTP and WS requests. Uppercase and lowercase variables must match if both are set. |
HTTPS_PROXY / https_proxy |
No | Proxy for HTTPS and WSS requests; the proxy endpoint still uses http://. |
NO_PROXY / no_proxy |
No | Hosts, domains, IPs, or CIDRs that bypass the proxy. Include at least localhost,127.0.0.1,::1. |
SSL_CERT_FILE / SSL_CERT_DIR |
No | Enterprise CA file or directory when the proxy re-signs TLS certificates. |
AGENT_NAME |
No | Agent display name. If not manually configured, it is delivered by the Beak config API. |
AGENT_WORKDIR |
No | Agent working directory. Container default is /app. |
AGENT_PROFILE_CACHE_DIR |
No | Profile cache directory. Container default is /var/lib/obs-agent/profile-cache. |
AGENT_BROWSER_ENABLED |
No | Default true when unset or empty. Installs or reuses Browser programs before startup and exposes tools after a successful health check. Explicit false disables downloads and Browser. Recreate the container or update the workload after changing it. |
AGENT_LOCAL_TIMEZONE |
No | Agent local timezone. Container default is Asia/Shanghai. |
AGENT_HTTP_ALLOWED_DOMAINS |
No | Restricts domains accessible by HTTP tools, comma-separated. |
AGENT_UPDATE_ENABLED |
No | Containerized deployment keeps self-update disabled. Upgrade by replacing the image or manifest. |
AGENT_UPDATE_HELPER_PATH |
No | Self-update helper path. Usually not used in containerized deployment. |
AGENT_UPDATE_BASE_URL |
No | Self-update release address. Usually not used in containerized deployment. |
AGENT_UPDATE_CHECK_INTERVAL_SECONDS |
No | Self-update check interval. Default is 300. |
AGENT_UPDATE_STATE_PATH |
No | Self-update state file path. |
AGENT_UPDATE_HISTORY_PATH |
No | Self-update history file path. |
AGENT_INSTALL_MODE |
No | Installation mode marker, usually written by the installer. |
AGENT_SELF_HOST_STATE_PATH |
No | Host installation state file path. Usually not used in containerized deployment. |
AGENT_SKILL_DEP_INSTALLER |
No | Skill dependency installer path. Usually provided by the installer or image. |
AGENT_SKILL_DEP_STATE_PATH |
No | Skill dependency state file path. |
AGENT_SKILL_DEP_HISTORY_PATH |
No | Skill dependency history file path. |
LLM_BASE_URL |
No | OpenAI-compatible model endpoint. It can be injected by a deployment system outside Beak. |
LLM_API_KEY |
No | Model API key. It is sent only to LLM_BASE_URL. |
LLM_MODEL |
No | Model name. Set it explicitly for a custom model. |
LLM_TEMPERATURE |
No | LLM temperature. Default is 0.2. |
LLM_MAX_TOKENS |
No | Maximum LLM output tokens. Default 0 means using the model default. |
AGENT_SEND_EMAIL_ENABLED |
No | Whether to enable the Send Email tool. Default: true. |
AGENT_SEND_EMAIL_BASE_URL |
No | Send Email API endpoint. If not set locally, uses the independent email endpoint provided by Beak. |
LOG_LEVEL |
No | Log level. Container default is info. |
LOG_FORMAT |
No | Log format. Container default is text. |
LOG_PATH |
No | Log output location. Container default is stdout. |
AGENT_DIAGNOSTIC_LOG_PATH |
No | Bounded rotating log copy used by bug reports. Containers default to /var/lib/obs-agent/profile-cache/diagnostics/agent.log on the persistent profile-cache volume and fall back to a 4 MiB in-memory tail if the path is not writable. |
LOG_RELATIVE_PATH |
No | Whether the log path is resolved relative to the work directory. Default is true. |
LOG_MAX_SIZE_MB |
No | Maximum size of one log file. Default is 32. |
LOG_MAX_BACKUPS |
No | Number of log backup files. Default is 5. |
OTEL_EXPORTER_OTLP_PROTOCOL |
No | OTEL export protocol. Container default is http/protobuf. |
OTEL_EXPORTER_OTLP_ENDPOINT |
No | OTEL collector endpoint. Delivered by the Beak config API or manually overridden when trace export is required. |
OTEL_EXPORTER_OTLP_HEADERS |
No | OTEL request headers. Delivered by the Beak config API or manually overridden when trace export is required. |
OTEL_LOGS_ENABLED |
No | Legacy variable ignored by the current Agent. Beak's runtime-config API controls metrics, logs, and traces together. |
AGENT_MAX_RUN_DURATION |
No | Soft time budget for each run, default 2h; finish the active model request or tool, then stop new work and try one summary. Approval waits count toward the budget; 0s disables it. |
AGENT_MAX_LLM_MESSAGES |
No | Optional message-count safety limit for a single model request. Default is 0 (disabled). |
AGENT_MAX_LLM_MESSAGE_CHARS |
No | Maximum characters per LLM message. Default is 512000. |
AGENT_MAX_SYSTEM_PROMPT_CHARS |
No | Maximum system prompt characters. Default is 512000. |
AGENT_QUERY_SESSION_CHAT_HISTORY_LIMIT |
No | Query limit for session history. Default is 20. |
AGENT_CONTEXT_BUDGET_TOKENS |
No | Context token budget. Default is 262144. |
AGENT_CONTEXT_BUDGET_CHARS |
No | Context character budget. Default is 262144. |
AGENT_REASONING_DISPLAY_MODE |
No | Reasoning display mode. Supports hidden or raw. Default is hidden. |
AGENT_PROFILE_SYNC_DISABLE |
No | Disable remote Profile synchronization at startup, on periodic checks, and on push notifications. When true, use the local cache. Default: false. |
AGENT_PROFILE_SYNC_INTERVAL |
No | Periodic fallback interval for full Profile synchronization, default 10m. Failures retry after 30 seconds, or the configured interval if shorter. Saving this Agent's Profile, Skill, or MCP binding also triggers targeted synchronization immediately. |
AGENT_DEFAULT_APPROVAL_TTL_SECONDS |
No | Deprecated. Accepted for compatibility with older configurations, but ignored with a one-time startup warning. |
AGENT_WEB_SEARCH_ENABLED |
No | Whether to enable the Web Search tool. Default is true. |
AGENT_PRE_SEARCH_ENABLED |
No | Whether Agents must check available tools, evidence, and the execution route before complex tasks. Default true. Set to false to disable this requirement for both the main Agent and subagents. |
AGENT_WEB_SEARCH_BASE_URL |
No | Web Search API endpoint. If not set locally, uses the independent search endpoint provided by Beak. |
AGENT_WEB_SEARCH_DEFAULT_LIMIT |
No | Default number of Web Search results. Default is 5. |
AGENT_WEB_SEARCH_MAX_LIMIT |
No | Maximum number of Web Search results. Default is 10. |
AGENT_WEB_SEARCH_MAX_CONTENT_CHARS |
No | Maximum content characters per search result. Default is 3000. |
AGENT_WEB_SEARCH_MAX_CONTEXT_CHARS |
No | Maximum search context characters. Default is 12000. |
AGENT_WEB_SEARCH_DEFAULT_MODE |
No | Default Web Search mode. Default is auto. |
AGENT_WEB_SEARCH_TIMEOUT |
No | Web Search timeout. Default is 30s. |
AGENT_MESSAGE_ENCRYPTION_ENABLED |
No | Whether message encryption is enabled. Default is true. |
AGENT_MESSAGE_HPKE_KEY_ID |
No | HPKE key ID. |
AGENT_MESSAGE_HPKE_PRIVATE_KEY |
No | HPKE private key content. |
AGENT_MESSAGE_HPKE_KEY_PATH |
No | HPKE private key file path. |
AGENT_MESSAGE_HPKE_ROTATION_INTERVAL |
No | HPKE key rotation interval. Default 0 means no automatic rotation. |
OWL_BASE_URL |
No | Owl dependency download address. Usually built into the image or delivered by the Beak config API. |
OWL_INSTALL_URL |
No | Owl installation script address. Usually delivered by the Beak config API. |
OWL_REGISTRY_ENDPOINT |
No | Owl registry address, normally supplied by the Beak config API. Normal Agent startup writes it to $OWL_DIR/config.yaml. |
OWL_TOKEN |
No | Owl registry access token, normally supplied by the Beak config API. Startup writes it to auth.api-key in the Owl configuration; it is not added to the tool environment allowlist. |
OWL_DIR |
No | Owl working directory. Container default is ${AGENT_WORKDIR}/.owl, or /app/.owl. obs-agent exposes it as a shared read-only root for read_file and list_dir. Explicit paths from older deployments remain supported. |
AGENT_IMAGE_PRINT_VERSIONS |
No | Whether to print obs-agent and owl versions at container startup. Default is false. |
Notes¶
- During normal container startup, the Agent writes effective
OWL_REGISTRY_ENDPOINTandOWL_TOKENvalues to$OWL_DIR/config.yamlbefore starting tool services. No new command-line argument is required. Information queries such as-hand--versiondo not write configuration. The default path is/app/.owl/config.yaml; permissions are0600, and writes are atomic. Mount a writable Owl directory; a separately mounted read-only configuration file does not support this mode. - Container startup manages the entire root
config.yaml, includingregistry.endpointandauth.api-key. Restart replaces the whole file; custom fields are not preserved, while cache/data remain. Back up the existing configuration before upgrading. If both startup inputs are empty, no file is written; supplying only one stops startup. Nonempty local overrides still take priority, and a custom registry still requires a local token. Host initialization keeps its existing value-priority rules. - If the persistent volume selects a named profile in
state.yaml, orOWL_PROFILEis set to a value other thandefault, the Agent reports an error and leaves the configuration unchanged. In a maintenance environment, runowl switch defaultwith the sameOWL_DIRand clearOWL_PROFILEbefore starting the container. The Agent does not change named profiles automatically. Invalidstate.yamlor a write or replacement failure also stops startup and preserves the original configuration. - Docker and Helm cannot use the same
AGENT_IDonline at the same time. Each running instance needs an independent agent. - For older deployments upgraded by replacing only the image, if the Owl volume remains mounted at
/var/lib/obs-agent/work/.owl, the entrypoint detects and continues using it whenOWL_DIRis unset. New Compose, Kubernetes, and Helm templates use/app/.owl. Do not mount both Owl volumes during migration. obs-agent.ymlcreates a dedicated ServiceAccount and disables Kubernetes service account token auto-mounting.- The container does not run the host installation script and does not depend on systemd.
- Containerized deployment does not enable local self-update. Upgrade by replacing the image tag or digest.
- In production, use an image digest to pin the version.