Overview
This guide covers the day-to-day operation of Vega Runtime: starting and stopping it, using the public CLI, monitoring health and status, reviewing logs, handling common issues, and planning maintenance and upgrades. Operate Vega Runtime through approved procedures and do not infer hidden product behavior from local process state alone.
Concepts
| Term | Meaning |
|---|---|
| Readiness | The Runtime reports it can accept work permitted by its current deployment. |
| Health | A public operational signal about Runtime or Capability condition. |
| Status | Current information about Runtime state, sessions, work, availability, and warnings. |
| Diagnostic | Offline guidance for public configuration, identity, and Runtime data location. |
| Maintenance window | An approved period for controlled updates or operational changes. |
Runtime CLI
Invoke the public CLI as python -m vega.
| Term | Meaning |
|---|---|
| run | Start Vega Runtime. |
| migrate | Prepare Runtime data for the approved normal or development mode. |
| status | Provide status guidance for a running Runtime. |
| diagnostic | Provide offline configuration, identity, and storage-layout guidance. |
Start a reviewed production configuration:
python -m vega run --mode normal \--config /etc/vega/base.yaml \--identity /etc/vega/registration.yaml \--log-level INFO
run supports--mode, repeatable--config,--identity,--log-level,--live-voice, and--audio-device.migratesupports the public mode selection for normal and development operation. Checkpython -m vega --helpfor the options in your installed release.
migrateonly as part of an approved installation or upgrade procedure, after verifying the required backup and deployment targets.Runtime status and health monitoring
Check Runtime status before accepting operational work and after startup, restart, or configuration change. Status can include the Runtime lifecycle state, active session, active tasks, Capability availability, version, and visible warnings. The exact fields depend on release and deployment permissions.
Health monitoring uses Runtime readiness and the health of Capabilities required by the work. A healthy Runtime may still decline a request when no eligible Capability is available or a Capability precondition is unmet.
Monitor readiness, repeated task failures, capability unavailability, storage capacity, and host-level conditions required by the approved deployment.
Metrics and logs
Metrics are operational measurements used to identify trends and alert on conditions that need attention. Use the publicmetrics_enabledconfiguration setting only according to your approved observability policy. The Runtime does not make an internal monitoring design a public contract.
Logs provide operational evidence for startup, configuration, status, and task issues. UseINFOfor routine production logging and temporarily increase logging detail only for approved diagnosis. Centralize logs with access control, retention, and redaction policies.
python -m vega run --mode normal --log-level INFO
Troubleshooting
Use the problem → cause → resolution sequence below.
| Problem | Likely cause | Approved response |
|---|---|---|
| Runtime does not become ready | Configuration, identity, storage, or required credential issue | Check visible status, approved paths, logs, and service environment. |
| Capability is unavailable | Package not installed, not eligible, or unhealthy | Verify the approved Capability set and its operational prerequisites. |
| Recovery needs attention | Prior task outcome is uncertain | Inspect the real-world condition and follow the recovery procedure before retrying. |
| Logs are missing or incomplete | Incorrect log policy or service environment | Verify deployment logging configuration and access-controlled collection. |
Upgrading and maintenance
Plan upgrades as controlled operational changes:
- Review release notes and compatibility for Runtime, configuration, and installed Capabilities.
- Verify a recoverable backup and tested rollback path.
- Stop Runtime cleanly and resolve any active recovery condition.
- Install the approved release and run the required public migration step.
- Start the Runtime and perform a low-risk readiness and Capability check.
- Record the resulting version, time, and verification outcome.