Configuration Reference

Deployment environment variables, service config keys, and kubeconfig requirements for CosmicAC.

This page lists the configuration you set when you deploy CosmicAC. For the deployment steps, see Deploy CosmicAC.

Environment variables

Set these variables in the .env file in the deployment directory.

Variable	Description
`TAG`	Release image tag to deploy, for example `release-1.0.0`.
`GITHUB_USER`, `GITHUB_PAT`	GitHub Container Registry (GHCR) credentials. The PAT needs the `read:packages` scope.
`DOCKER_PLATFORM`	Docker platform to build for, for example `linux/amd64`.
`CONTAINER_UID` / `CONTAINER_GID`	Container user and group IDs. Use `0:0` for rootless Docker, or the host `UID:GID` for rootful.
`KUBECONFIG_SRC`	Absolute host path to the kubeconfig file. Required.
`K8S_KUBECONFIG`	Custom in-container path. Omit it to use `/app/kube/config`.
`K8S_NAMESPACE`	Kubernetes namespace for job resources. Defaults to `cosmic-ac`.
`K8S_WORKER_TYPE` / `K8S_WORKER_ENV` / `K8S_WORKER_ARGS`	Worker type, environment, and arguments, for example `wrk-server-rack-kv`, `development`, and `"--rack rack-0"`.
`K8S_MQ_TOPIC`	Message queue topic, in the form `job-workflow-<env>`, for example `job-workflow-dev`.
`K8S_RACK_ID` / `K8S_RACK_LOCATION` / `K8S_GPU_PRICE`	Rack ID, location, and GPU price, for example `rack-0`, `IN`, and the hourly price.
`BOOTSTRAP_ADMIN_EMAIL` / `BOOTSTRAP_ADMIN_PASSWORD`	First-run UI login seeded by `task bootstrap`. Optional.
`BOOTSTRAP_ADMIN_ROLES`	Roles for the bootstrap admin. Use `*` for full access.
`PROXY_AUTOBASE_KEY`	Leave blank. `wire` or `bootstrap` sets it automatically.

config-init pulls each image and writes its default config to services/<repo>/config/*.json. It auto-generates the app-node secrets and the proxy HRPC keypair, and at bootstrap the wire step links the services' shared keys. Set the keys below after config-init runs.

proxy-inference

In config/common.json, set the following keys.

Key	Description
`topicConf.capability`	Handshake secret for Hyperswarm topic authentication. Authorizes nodes to join the P2P network topic.
`topicConf.crypto.key`	HMAC-SHA384 secret key. Ensures message integrity and authentication between connected peers.

Kubeconfig requirements

The kubeconfig is a standard Kubernetes YAML file. Your cluster administrator normally provides it, or you can generate it with kubectl config view --raw --flatten. It must contain the following.

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>

Token-based user credentials also work. Flatten paths such as certificate-authority, client-certificate, and client-key into inline *-data fields so they stay valid after task bootstrap copies the file into the container.

Bootstrap reads the kubeconfig from the absolute host path in KUBECONFIG_SRC, copies it to services/cosmicac-wrk-server-k8s-nvidia/kube/config, and flattens it into the clusters/users/contexts structure the worker requires. The file stays on your host and is never built into an image.

Stack lifecycle

You manage the deployment with task commands. Each command operates on the Compose stack as follows.

Command	Behavior
`task bootstrap`	Generates the service config, starts and wires the services, then runs the post-deploy tasks. Used for a new or reset installation.
`task stop`	Stops the containers without deleting them.
`task start`	Restarts the stopped containers.
`task down`	Removes the containers and the Compose network. Configuration and worker state under `services/` are preserved.
`task up`	Recreates the containers. Does not generate config or wire services, so it is not used for a new installation.
`task update TAG=<tag>`	Upgrades the stack to a new image release. Preserves configuration and state.

task bootstrap logs in to GHCR only to pull a missing image, so a locally built stack deploys offline.

Upgrade behavior

task update TAG=<tag> upgrades the platform stack to a new image release. It preserves configuration and state, which live as host bind mounts under services/<repo>/.

compose pull explicitly refreshes the selected tag. Without it, pull_policy: missing keeps the stale local image.
config-init adds only new config files. New keys in existing files are not merged automatically; the updated services/<repo>/config/*.example files show the current keys.
A normal upgrade resets no state. Public runtime keys appear in status/, while persistent Hypercore, Autobase, and HyperMQ data lives under store/. Both directories are host bind mounts and survive container recreation. Deleting store/ during an upgrade loses persistent data.
task update scopes to the whole stack by default. To scope to one service, set SERVICES, for example task update TAG=<tag> SERVICES="cosmicac-app-node". The automation includes cosmicac-ui and Caddy when app-node is scoped, so the public route is refreshed.

task update upgrades only the Compose platform stack, not the GPU and inference images that run as jobs inside your Kubernetes cluster. Kubernetes pulls those from private GHCR images (interconnect.vmi_image and containerImages.{INFERENCE_VLLM,GPU_CONTAINER}), so the Compose GHCR login does not cover them. The cluster needs its own imagePullSecret in the job namespace (for example cosmic-ac-<env>), or public mirrors. To change their versions, bump those tags in the cluster's config/common.json.