Routine Operations

Pick the track that matches your deployment mode:

• Single-node Docker deployment, see Single-Node Docker Track.
• K8s cluster deployment, see K8s Cluster Track.
• Inspection items common to both modes, see Common Section.

Single-Node Docker Track

Scripts ship with the offline release package under deploy/scripts/; cd into the package's deploy directory before executing them.

View Service Status and Logs

# Container status
./scripts/fleet.sh ps

# Tail a service's logs
./scripts/fleet.sh logs -f <service-name>

# Use watch-logs for real-time viewing (combined with LOG_FILES)
LOG_FILES=./fleet.log ./scripts/fleet.sh up -d
./scripts/watch-logs.sh -- ./fleet.log

Earlier versions required an edition argument (basic / advance) in the command; that mechanism has been retired: omitting the argument starts the default stack, advance / enterprise now error out immediately, and basic is kept for compatibility but prints a deprecation warning (equivalent to omitting it).

Health Diagnosis

./scripts/doctor.sh          # key services
./scripts/doctor.sh --all    # all services
./scripts/doctor.sh --logs   # include recent logs of key services

doctor.sh checks include: /health of API Gateway (26100), Identity (26101), Orchestrator (26102), AG-UI (26103), AI-Infra-RS (26450); port connectivity of PostgreSQL (26110), TimescaleDB (26111), NATS (26112); as well as 503 path diagnosis and IM channel binding configuration.

Start / Stop / Restart

./scripts/fleet.sh up -d
./scripts/fleet.sh down
./scripts/fleet.sh restart <service-name>

down stops tenant claw containers by default; to keep tenant claws (only stop the platform), add --keep-tenant-claws. up -d triggers tenant claw reconcile by default; to skip, add --no-reconcile.

Config Hot-Reload Boundary

Operation	Requires down + up
Modify LLM model config in the admin console	No (takes effect within ~30 seconds)
Modify ADMIN_EMAILS	Yes
Modify deploy/config/*.yaml	Restart the affected service
Modify docker-compose.override.yml	Yes

LLM model configuration is maintained in the admin console (persisted in the database); changes are delivered via the internal config API and take effect within ~30 seconds - no restart needed. The LLM_* variables in .env serve only as first-startup bootstrap. deploy/config/*.yaml is the runtime configuration for ai-infra-rs; see Operations Configuration for the hot-reload boundary.

K8s Cluster Track

View Service Status and Logs

# Pod status
kubectl -n <ns> get pods -o wide
kubectl -n <ns> get deploy -o wide

# Tail logs
kubectl -n <ns> logs -f <pod> -c <container>
kubectl -n <ns> logs -l app=<svc> --tail=200

# Events
kubectl -n <ns> get events --sort-by=.lastTimestamp

For the full K8s command list, see Service Health Checks.

Health Diagnosis

./scripts/verify-k8s-install.sh
kubectl -n <ns> get pods
kubectl -n <ns> get events --sort-by=.lastTimestamp

verify-k8s-install.sh requires --gateway http://<node-ip>:30001. The script sequentially verifies: cluster access, platform Pod status, PVC binding, claw-fleet-manager /health, tenant claw (Profile B), Restate admin, and gateway HTTP smoke; optionally --e2e runs register/login/Agent SSE.

Start / Stop / Scale

# Scale
kubectl -n <ns> scale deploy/<svc> --replicas=<N>

# Rolling restart
kubectl -n <ns> rollout restart deploy/<svc>

# Helm upgrade
helm upgrade <release> <chart> -n <ns> -f values.yaml

claw Instance Management

./scripts/reconcile-claw-deployments.sh
./scripts/reconcile-claw-deployments.sh --force

reconcile-claw-deployments.sh is used to repair the broken ai_infra_base_url of tenant claws after an offline upgrade or fleet restart: it selectively restarts primary deployments, then triggers identity-service to sync the claw-fleet-manager registry. --force restarts all primary deployments and is recommended after offline upgrades.

Configuration Update

After editing a ConfigMap / Secret, trigger Pod rebuild:

kubectl -n <ns> rollout restart deploy/<svc>

After editing Helm values, use helm upgrade; Helm will trigger a rolling update automatically. If you only changed a Secret/ConfigMap without triggering a template diff, manually rollout restart.

Common Section

Channel Connectivity Inspection

Send a test message to each Feishu/WeCom/DingTalk bot to confirm the connector receives and delivers it. The "IM Channel Bind Config" section of doctor.sh checks whether the bind_base_url and bind_state_secret of identity /internal/config/{feishu,dingtalk,wecom} are complete (requires INTERNAL_SERVICE_TOKEN set in .env).

LLM Quota Monitoring

When AI_INFRA_RS_RPM_PER_USER hits the cap, consider:

• Raise the per-user RPM quota (.env or deploy/config/ai-infra.yaml).
• Investigate whether there are loop calls (check the frequency of event=llm.call in ai-infra-rs logs).
• Contact the LLM provider to raise the upstream quota.

Contract Version Handshake

curl http://<host>:26450/health | jq .contract_version

A non-unknown value is sufficient. See Service Health Checks for details.

Reference Documentation

• K8s Application Layer (Helm)
• Service Health Checks
• Service Log Viewing