Skip to content

obs-agent Container Installation Manual

This document explains how to install obs-agent with Docker and Kubernetes. If you are installing on Kubernetes, prefer Helm.

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.

Prepare Connection Information

Copy these three values from the Beak console or installation page:

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.4.0'

Install with Docker

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

Start the container:

docker run -d \
  --name obs-agent \
  --restart unless-stopped \
  --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:/var/lib/obs-agent/work/.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.4.0"
docker pull "${OBS_AGENT_IMAGE}"
docker rm -f obs-agent
docker run -d \
  --name obs-agent \
  --restart unless-stopped \
  --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:/var/lib/obs-agent/work/.owl \
  "${OBS_AGENT_IMAGE}"

Remove the Docker installation:

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

Install with Kubernetes YAML

If you do not use Helm, you can use the base manifest published to OSS directly.

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.4.0.yml -o obs-agent.yml

Create the namespace:

kubectl create namespace obs-agent

Replace placeholders in the manifest with the current agent information:

sed -i.bak \
  -e "s#replace-with-beak-ws-url#${BEAK_WS_URL}#g" \
  -e "s#replace-with-agent-uuid#${AGENT_ID}#g" \
  -e "s#replace-with-agent-api-key#${AGENT_API_KEY}#g" \
  obs-agent.yml

obs-agent.yml already includes a Kubernetes Secret. You can also edit this section directly:

apiVersion: v1
kind: Secret
metadata:
  name: obs-agent-secret
type: Opaque
stringData:
  AGENT_API_KEY: "replace-with-agent-api-key"
  AGENT_ID: "replace-with-agent-uuid"

Install:

kubectl -n obs-agent apply -f obs-agent.yml

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:

kubectl -n obs-agent apply -f obs-agent.yml

Remove the YAML installation:

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

Install with Kubernetes Helm

Set the Helm repository address, then add the repository:

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}"

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.4.0 \
  --set-string config.BEAK_WS_URL="${BEAK_WS_URL}" \
  --set secret.existingSecret=obs-agent-secret

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.4.0

Remove the Helm installation:

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

View Available Environment Variables

The installation steps only require BEAK_WS_URL, AGENT_ID, and AGENT_API_KEY. The variables below are used for troubleshooting or overriding defaults. Do not set them unless you have a specific need.

Environment Variable Manual Configuration Required Description
BEAK_WS_URL Yes Beak config API address, such as https://agent-api.guance.com.
BEAK_ENDPOINT No Fallback address used by the container entrypoint when reading the Beak config API. If unset, BEAK_WS_URL is used.
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.
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_PERMISSION_MODE No Tool permission mode. Container default is standard.
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_SELF_HOST_HISTORY_PATH No Host installation history 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 Delivered by the Beak config API.
LLM_API_KEY No Delivered by the Beak config API. Defaults to AGENT_API_KEY.
LLM_MODEL No No manual configuration is required. If unset, agent uses the default 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.
AI_HUB_BASE_URL No AI Hub address. If unset, LLM_BASE_URL is used.
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.
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 Whether to export OTEL logs. By default it follows whether OTEL_EXPORTER_OTLP_ENDPOINT is configured.
AGENT_MAX_TOOL_CALL_ITERATIONS No Maximum tool-call rounds for one task. Default is 128.
AGENT_MAX_LLM_MESSAGES No Maximum number of LLM context messages. Default is 256.
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_RECENT_CHAT_HISTORY_MESSAGES No Number of recent chat history messages. Default is 20.
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_CONTEXT_COMPACT_THRESHOLD No Context compaction threshold. Default is 0.6.
AGENT_TOOL_LOOP_RECENT_INTERACTIONS No Tool loop detection window. Default is 4.
AGENT_TOOL_SAME_ERROR_LIMIT No Limit for repeated identical tool errors. Default is 20.
AGENT_TOOL_TOTAL_FAILED_LIMIT No Limit for total tool failures. Default is 50.
AGENT_TOOL_SAME_ACTION_LIMIT No Limit for repeated identical tool actions. Default is 3.
AGENT_TOOL_MALFORMED_ARGUMENTS_LIMIT No Limit for malformed tool arguments. Default is 2.
AGENT_REASONING_DISPLAY_MODE No Reasoning display mode. Supports hidden or raw. Default is hidden.
AGENT_PROFILE_SYNC_DISABLE No Whether to disable profile sync. Default is false.
AGENT_PROFILE_SYNC_INTERVAL No Profile sync interval. Default is 5m.
AGENT_DEFAULT_APPROVAL_TTL_SECONDS No Default approval TTL. Default is 300 seconds.
AGENT_WEB_SEARCH_ENABLED No Whether to enable the Web Search tool. Default is true.
AGENT_WEB_SEARCH_BASE_URL No Web Search service address. Required when Web Search is enabled.
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. Usually delivered by the Beak config API.
OWL_TOKEN No Owl registry access token. Usually delivered by the Beak config API.
OWL_DIR No Owl working directory. Container default is /var/lib/obs-agent/work/.owl.
AGENT_IMAGE_PRINT_VERSIONS No Whether to print obs-agent and owl versions at container startup. Default is false.

Notes

  • Docker and Helm cannot use the same AGENT_ID online at the same time. Each running instance needs an independent agent.
  • 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? ×