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.

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.

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

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

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:/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.8.1"
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:/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

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

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.8.1 \
  --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.8.1

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.

Notes¶

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