Deployment configuration

Configure a CosmicAC deployment with environment variables in .env and a kubeconfig file. For the deployment steps, see Deploy CosmicAC.

Copy .env.example to .env in the deployment directory, then set the variables your deployment needs. The values on this page are the ones .env.example ships.

Required before the first deployment

Set these before you run task bootstrap for the first time. It uses them to pull the service images, build the worker's Kubernetes config, and register your rack.

Deployment layout

These settings decide where the deployment pulls its images from, where it keeps state on your host, and which port it serves on. Each one has a default, so set only what your host needs.

If you pass a tag on the command line, as in task update TAG=release-1.2.0, that run clears APPNODE_TAG, WRKORK_TAG, PROXY_TAG, K8S_TAG, and UI_TAG.

./compose-deploy.sh --env dev, --env stg, and --env prd read DEV_TAG, STG_TAG, or PRD_TAG instead, and leave the per-service tags in place. Any other value stops the command. The task commands pass no environment, so they always read TAG.

Kubernetes worker

The Kubernetes worker, cosmicac-wrk-server-k8s-nvidia, connects to your cluster's Kubernetes API and creates the resources each job needs. This section calls it the worker.

Job images and defaults

These settings are the image and disk defaults for jobs on your cluster. TAG applies only to the CosmicAC services on your host, so upgrading the stack doesn't change the images in this table. task wire writes these values into config/common.json for cosmicac-wrk-server-k8s-nvidia. task bootstrap and task update both run task wire.

Service settings

These variables configure the CosmicAC services on your host. .env.example sets a working value for each one. If a value doesn't suit your deployment, change it in .env.

Telemetry

cosmicac-wrk-monitor collects logs and metrics from the other services. Each service that sends them is a producer, and every producer starts switched off. All producers share one topic, and a shared secret protects it.

Every producer must use the same secret and topic as cosmicac-wrk-monitor. If one differs, that producer keeps running, but its logs and metrics never reach the monitor.

An inference agent has no telemetry variable of its own. The WRKORK_FACS_CONFIG__JOBS__j0__telemetry variables are the only way to switch its telemetry on. cosmicac-wrk-ork passes the three values into each job as TELEMETRY_ENABLED, TELEMETRY_TOPIC, and TELEMETRY_SECRET_KEY.

After you change any of these, apply the service's config and restart the service. See Task deployment commands for the apply command each service takes.

task bootstrap also runs task wire-monitor, which gives cosmicac-app-node and cosmicac-wrk-monitor each other's RPC keys. If bootstrap reported that the monitor wasn't ready, run task wire-monitor yourself.

Generated values

Leave these blank on a first deployment.

task config-init reads the three topic variables in this section. If one is blank, the command generates a value, writes it into the config/common.json of cosmicac-proxy-inference, and leaves .env unchanged. If you set one yourself, the command keeps your value.

PROXY_AUTOBASE_KEY is the exception. task wire reads it from the running cosmicac-app-node and writes it into .env.

Optional administrator account

A default deployment needs no administrator, because it runs with authentication turned off. These variables take effect only when you run task seed-admin, which task bootstrap doesn't run.

Config overrides

Each service reads its runtime config from the generated JSON files under services/<service>/config/, not from .env. An override variable in .env names one of those files and the values to set in it. Each service has its own apply command, such as task apply-app-node-common-config, and that command writes the values into the file. See Task deployment commands for all five.

Each service has its own prefix.

An override takes one of these forms.

<FILE> names a file under config/facs/ in capitals, such as HTTPD_OAUTH2. The apply command converts that name to lowercase, turns each underscore into a hyphen, and adds .config.json, which gives config/facs/httpd-oauth2.config.json.

The apply command reads a value as JSON when the value is valid JSON, and as a string otherwise. A value of 100 writes a number and true writes a boolean, while cluster-0 writes a string. The command skips an empty variable, and that key keeps its current value.

task wire writes the values in this table. An override on any other path survives.

task bootstrap also runs task wire-monitor, which writes three more values.

• The monitorService block in the config/common.json of cosmicac-app-node, replaced rather than merged.
• The RPC keys allowed to connect, in the config/facs/net.config.json of cosmicac-wrk-monitor.
• APPNODE_COMMON_CONFIG__monitorService__rpcPublicKey in .env.

Model health settings

cosmicac-proxy-inference measures the health of every Managed Inference endpoint and stores the results on disk. These settings live in the modelHealth block of its config/common.json, not in .env. To override one, use PROXY_COMMON_CONFIG__modelHealth__<key>, as described in Config overrides. task wire writes only apiKeySecret into that file, so an override on this block survives.

healthySuccessRatePct and downThresholdMs set the thresholds that decide each replica's health. An endpoint reports Down only when every replica is down, and Degraded while at least one replica still serves requests. For the full status model, see Model health.

Every interval and threshold in this table is in milliseconds. A value of 0, or one that isn't a number, leaves the default in place. For example, setting checkIntervalMs to 0 doesn't turn probing off.

For what these metrics mean and where to read them, see Check Managed Inference endpoint health.

Health check probes

Each health check sends a real inference request to a replica. The request comes from a profile in the config/health-check-probes.json of cosmicac-proxy-inference. CosmicAC picks the profile from the model's input modalities.

Each profile takes the following keys.

CosmicAC uses audioUrl only when the value is a valid HTTP or HTTPS URL. For anything else, including an empty value, it generates a short silent audio file and uploads that instead. It logs a warning when you set a value it can't use.

No .env override reaches this file, because Config overrides write only to common.json and config/facs, and this file sits at the config root. Edit it directly, then restart the service, which reads the profiles at startup.

Kubeconfig requirements

The kubeconfig is a standard Kubernetes YAML file. You pass it to the deployment through KUBECONFIG_SRC. It must set current-context and contain clusters, users, and contexts.

apiVersion: v1
kind: Config
current-context: <context-name>
clusters:
  - name: <cluster-name>
    cluster:
      server: https://<kubernetes-api>
      certificate-authority-data: <base64-ca>
users:
  - name: <user-name>
    user:
      client-certificate-data: <base64-certificate>
      client-key-data: <base64-private-key>
contexts:
  - name: <context-name>
    context:
      cluster: <cluster-name>
      user: <user-name>

Ask your cluster administrator for the file, or export one with kubectl config view --raw --flatten. That command writes the credentials in full instead of as file references.

• CosmicAC accepts certificate-based and token-based user credentials.
• Credentials must use the inline *-data fields, because task config-init reads this file alone. It can't follow a file reference such as certificate-authority, client-certificate, or client-key.
• The file stays on your host, and no image contains it.