One executable, run where the data volume lives.
With no command, aidc-server starts the server. With a command it performs one administrative task against the same data and exits. The data commands read the same AIDC_HUB_* settings as the server and open its database and package storage, so run them inside the running server's container.
The commands version, help, legal and openapi do not open the database or package storage, so they also work on a machine where the server is not deployed. The flags --help and --version are not accepted; use the help and version commands. Exit status 0 means the command completed (for versions refresh, individual tools can still have failed, so read each tool's line). Status 1 means it failed, or consistency check found an error-level problem. Status 2 means the command line was not accepted.
| Command | Purpose | Changes data |
|---|---|---|
keys status, keys list | Show the active signing key and trusted keys with package counts | No |
keys rotate [--description TEXT] | Create a new active signing key | Yes |
versions refresh [--tool NAME] | Refresh upstream version information | Yes |
consistency check [--tool NAME [--version V]] | Report missing or altered packages | No |
recommended sync --file FILE | Replace the server's recommended-versions list | Yes |
prune keep-recommended, prune version, prune no-keep, prune uploads | Apply retention, remove one version, remove every variant of a tool, or remove abandoned upload data | With --execute |
What clients see about upstream releases and vendor keys.
The version request for a tool lists versions with their source: vendor (upstream only), hub (published here) or vendor|hub. A vendor-only version is not evidence that the server holds your archive; check exact package metadata before installing. If the upstream is unreachable at refresh time the response can omit vendor entries while still listing the server's packages.
| Path | When it runs | Covers |
|---|---|---|
| Scheduled refresh | Every 3 hours by default, starting one interval after startup | Every supported tool except ant and playwright |
| On request | When a versions request finds the cached list missing or older than an hour | The requested tool |
| Operator command | When you run aidc-server versions refresh [--tool NAME] | Every supported tool, or one |
The command can exit 0 even when a tool failed, so read each line. For tools released on GitHub, a failing or partial refresh is often rate limiting: set AIDC_GITHUB_TOKEN in the server environment. The server also keeps public verification keys for selected upstream vendors and refreshes them daily where the vendor changes them; there is no command to refresh them on demand.
Health, statistics and the internal monitoring listener.
Health shows that the service answers. Statistics show what clients do: GET /api/v1/stats returns package, download and request totals, and GET /api/v1/stats/suggestions lists requested but unavailable packages. Both need browse access. Downloads count started transfers, including partial requests, not completed installations, and the totals are not an audit ledger. With activity reporting off, statistics answer with zeros and empty lists.
The server also has an internal monitoring listener, on port 9090 by default, meant only for the cluster's monitoring system. Reach it from inside the cluster.
| Metric | Watch for |
|---|---|
aidc_activity_daily_refreshed_timestamp_seconds | More than a few hours behind the current time: the hourly daily-summary refresh has stopped |
aidc_activity_rollup_failures_total | Increasing: summaries are failing; the previous values stay in place |
aidc_telemetry_row_age_seconds | Well beyond the retention period: expired activity details are not being removed |
aidc_telemetry_retention_purge_failures_total | Increasing: the hourly clean-up is failing |
Every metric carries service="aidc-server" and the deployment's channel label, which must be stable, edge or beta. --debug raises log detail. Denied-request logs identify customers; keep them within your operational access controls.
Everything the server needs is on one volume.
The volume at /var/lib/aidc/hub holds package archives and manifests, the package database, signing keys and activity data. Back it up as a whole and consistently, for example from a volume snapshot. A restore from package files alone re-creates the catalogue at the next start, but the server then generates a new signing key, re-signs the recovered packages and loses activity history.
To restore, stop the server, restore the whole volume from one snapshot (never mix files from different backups), and start the server. Then check that aidc-server keys status shows the fingerprint you recorded at install, that aidc-server consistency check reports no errors, and that a client can list the catalogue, download one package and verify its checksum and signature. Tell customers to fetch current keys and metadata before they verify.
Back up first; expect a short interruption.
To upgrade, back up the volume, change image.tag, and run helm upgrade aidc-server ./aidc-server-chart -n aidc -f aidc-values.yaml. For a container, stop and remove it, then start the new image with the same volumes. The old server stops before the new one starts. Verify with the health and catalogue requests from the install page.
helm uninstall removes the server and the volume claim the chart created; whether the data survives depends on your storage class's reclaim policy. To keep data across reinstalls, create the claim yourself and set persistence.existingClaim. With a container, docker rm -f aidc-server leaves /srv/aidc/data in place. Deleting the data permanently removes every package, the catalogue, the signing keys and the activity history.