Skip to content

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. /app stores 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:

export OBS_AGENT_IMAGE='pubrepo.guance.com/guance/obs-agent:v0.19.0'

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:

docker ps --filter name=obs-agent
docker logs -f obs-agent

The following log lines indicate that startup succeeded:

obs-agent profile request loaded
obs-agent websocket connected

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.

docker rm -f obs-agent
docker volume rm obs-agent-work obs-agent-profile-cache obs-agent-owl

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:

AGENT_BROWSER_ENABLED=false

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:

config:
  AGENT_BROWSER_ENABLED: "false"

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:

curl -fsSL https://static.guance.com/obs-agent/obs-agent.yml -o obs-agent.yml

Download a specific version of the manifest:

curl -fsSL https://static.guance.com/obs-agent/obs-agent-v0.19.0.yml -o obs-agent.yml

Create the namespace:

kubectl create namespace obs-agent

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.

kubectl -n obs-agent delete -f obs-agent.yml
kubectl delete namespace obs-agent

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:

kubectl create namespace obs-agent

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.

helm uninstall obs-agent -n obs-agent
kubectl delete namespace obs-agent

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_ENDPOINT and OWL_TOKEN values to $OWL_DIR/config.yaml before starting tool services. No new command-line argument is required. Information queries such as -h and --version do not write configuration. The default path is /app/.owl/config.yaml; permissions are 0600, 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, including registry.endpoint and auth.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, or OWL_PROFILE is set to a value other than default, the Agent reports an error and leaves the configuration unchanged. In a maintenance environment, run owl switch default with the same OWL_DIR and clear OWL_PROFILE before starting the container. The Agent does not change named profiles automatically. Invalid state.yaml or a write or replacement failure also stops startup and preserves the original configuration.
  • Docker and Helm cannot use the same AGENT_ID online 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 when OWL_DIR is unset. New Compose, Kubernetes, and Helm templates use /app/.owl. Do not mount both Owl volumes during migration.
  • obs-agent.yml creates 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.

Feedback

Is this page helpful?