Configuration reference
Deployment environment variables and kubeconfig requirements for CosmicAC.
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.
A default deployment runs without authentication
.env.example starts app-node with --noauth true, and the web interface ships with its login routes turned off. Every API request succeeds without a token, and the interface opens without a sign-in. Restrict network access to the deployment.
Required before the first deployment
| Variable | Description |
|---|---|
TAG | Release image tag to deploy, for example release-1.0.1. |
GITHUB_USER, GITHUB_PAT | GitHub Container Registry (GHCR) credentials. The PAT needs the read:packages scope. |
KUBECONFIG_SRC | Absolute host path to the kubeconfig file. See Kubeconfig requirements. |
K8S_RACK_ID | Identifier for the rack this deployment registers, for example rack-0. |
K8S_RACK_LOCATION | Location code reported for the rack, for example IN. Job creation offers it as a location. |
K8S_GPU_PRICE | Hourly price per GPU, read by task register-rack and task migrate-pricing. Defaults to 1. |
Deployment layout
| Variable | Description |
|---|---|
REGISTRY | Image registry host. Defaults to ghcr.io. |
OWNER | Registry namespace the images live under. Defaults to tetherto. |
DATA_ROOT | Host directory holding each service's config and state. Defaults to ./services. |
UI_PORT | Host port for the whole deployment. Caddy serves the web interface there, and proxies /api to app-node and /inference to the inference proxy. Defaults to 5173. |
DOCKER_PLATFORM | Platform to pull images 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. |
WORKER_ENV | Default environment name for services that don't set their own. Defaults to production. |
Kubernetes worker
| Variable | Description |
|---|---|
K8S_NAMESPACE | Namespace for job resources. .env.example sets cosmic-ac. |
K8S_KUBECONFIG | Path to the kubeconfig inside the container. Omit it to use /app/kube/config. |
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. |
Job images and defaults
These settings describe the jobs the Kubernetes worker creates, not the platform services. TAG doesn't reach them, so upgrading the stack leaves them on the tags set here.
task wire writes these values into the worker's config, and task bootstrap and task update both run task wire.
| Variable | Description |
|---|---|
K8S_VMI_IMAGE | KubeVirt image backing every job's virtual machine. Defaults to ghcr.io/tetherto/kubevirt-image:latest. |
K8S_GPU_CONTAINER_IMAGE | Agent image for GPU Container Jobs. Defaults to ghcr.io/tetherto/cosmicac-wrk-agent-instance:latest. |
K8S_INFERENCE_PARAKEET_IMAGE | Agent image for Parakeet Managed Inference Jobs. .env.example ships it commented out. |
K8S_DEFAULT_ROOT_DISK_SIZE | Root disk size for a job that requests none, for example 100Gi. |
K8S_LOG_STORE_ENABLED | Whether the worker writes job logs to the log store. Defaults to false. |
Service settings
Every variable in this section ships with a working value. A deployment that keeps the bundled Redis and the default ports needs none of them.
| Variable | Description |
|---|---|
WRKORK_WORKER_TYPE / WRKORK_WORKER_ENV / WRKORK_WORKER_ARGS | Orchestrator worker type, environment, and arguments, for example wrk-ork-proc-aggr, development, and "--cluster cluster-0". |
APPNODE_WORKER_TYPE / APPNODE_WORKER_ENV / APPNODE_WORKER_ARGS | app-node worker type, environment, and arguments. .env.example ships "--host 0.0.0.0 --noauth true", which turns authentication off. |
APPNODE_PORT | Port app-node listens on, which Caddy proxies /api to. Defaults to 3000. |
PROXY_HTTP_WORKER_TYPE / PROXY_HTTP_WORKER_ENV | Inference HTTP proxy worker type and environment. |
PROXY_HTTP_PORT | Port the inference HTTP proxy listens on, which Caddy proxies /inference to. Defaults to 8000. |
PROXY_HTTP_EXTRA_ARGS | Extra arguments passed to the inference HTTP proxy. |
PROXY_HRPC_WORKER_TYPE / PROXY_HRPC_WORKER_ENV | Inference HRPC proxy worker type and environment. |
PROXY_HRPC_INSTANCE_ID | Instance number for the HRPC proxy. Defaults to 1. |
PROXY_TOPIC_CRYPTO_ALGO | Algorithm securing the inference topic. Defaults to hmac-sha384. |
REDIS_HOST / REDIS_PORT | Redis host and port. Default to the bundled redis service on 6379. |
REDIS_PASSWORD / REDIS_DB | Redis password and database number. Default to no password and database 0. |
Generated values
Leave these blank on a first deployment.
task config-init reads the three topic variables. When one is blank, it generates a value and writes it into the inference proxy's common.json, leaving .env untouched. Setting one pins the value instead.
PROXY_AUTOBASE_KEY works the other way. task wire reads it from the running app-node and writes it back into .env.
| Variable | Description |
|---|---|
PROXY_AUTOBASE_KEY | Autobase key linking the inference proxy to app-node. task wire sets it. |
PROXY_AGENT_INFERENCE_TOPIC | Topic the inference agents publish on. |
PROXY_TOPIC_CAPABILITY | Handshake secret for that topic. |
PROXY_TOPIC_CRYPTO_KEY | Signing key for that topic. |
Optional administrator account
A default deployment needs no administrator, because it runs with authentication turned off. These variables do nothing until you run task seed-admin yourself. task bootstrap doesn't read them.
| Variable | Description |
|---|---|
BOOTSTRAP_ADMIN_EMAIL / BOOTSTRAP_ADMIN_PASSWORD | Credentials for the account task seed-admin creates. Set both, or leave both blank. |
BOOTSTRAP_ADMIN_ROLES | Comma-separated roles for that account. Use * for full access. |
Config overrides
Each service reads its runtime config from generated JSON files under services/<service>/config/, not from .env. An override variable in .env carries a value for one of those files, and the service's apply command writes it into the file the variable names. See Task deployment commands for those commands.
Each service reads one prefix.
| Prefix | Service |
|---|---|
APPNODE_ | app-node |
PROXY_ | proxy-inference |
WRKORK_ | ork |
K8S_ | Kubernetes worker |
An override takes one of these forms.
| Variable | Effect |
|---|---|
<PREFIX>_COMMON_CONFIG__<path> | Sets one value in common.json, with a double underscore for each level down, such as APPNODE_COMMON_CONFIG__pagination__limit=100. |
<PREFIX>_COMMON_CONFIG_OVERRIDES_JSON | Sets each value in a JSON object, in common.json. |
<PREFIX>_FACS_CONFIG__<FILE>__<path> | Sets one value in config/facs/<file>. |
<PREFIX>_FACS_CONFIG_<FILE>_OVERRIDES_JSON | Sets each value in a JSON object, in config/facs/<file>. |
<PREFIX>_FACS_CONFIG_<FILE>_REPLACE_JSON | Replaces the entire contents of config/facs/<file> with a JSON object. |
<FILE> names a file under config/facs/. The command converts the key to lower case, turns each underscore into a hyphen, and adds .config.json, so HTTPD_OAUTH2 targets config/facs/httpd-oauth2.config.json.
task wire writes the values that link the services to each other, and task bootstrap and task update both run it. Each run replaces those values in the config file, so an override you applied to one of them is gone. The variable in .env stays as you set it, and running the apply command again puts the value back. K8S_COMMON_CONFIG overrides are the exception, because task wire applies them after its own writes.
task wire writes these values. An override on any other path survives it.
| File | What task wire writes |
|---|---|
app-node config/common.json | The orks block, replaced rather than merged. |
proxy-inference config/common.json | apiKeySecret, copied from app-node. |
ork config/facs/jobs.config.json | The message queue topic and the inference settings. |
Kubernetes worker config/common.json | The message queue, log store, interconnect, and inference blocks. |
Kubernetes worker config/kube.config.json | The default namespace. |
config/facs/net.config.json, for app-node, the ork, and the Kubernetes worker | The list of RPC keys allowed to connect, and allowLocal. |
.env | PROXY_AUTOBASE_KEY. |
Kubeconfig requirements
The kubeconfig is a standard Kubernetes YAML file, passed to the deployment through KUBECONFIG_SRC. Your cluster administrator normally provides it, or you generate it with kubectl config view --raw --flatten. It must 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>- Certificate-based and token-based user credentials both work.
- Credential paths such as
certificate-authority,client-certificate, andclient-keymust be inline*-datafields, not file references. - The file stays on your host and is never built into an image.