Task deployment commands
Reference for the task commands that deploy and operate the CosmicAC stack.
The CosmicAC deployment repository uses Task to deploy and operate the stack. Run a command as task <name> from the deployment directory. task with no argument lists every command.
Commands read variables from .env and the command line. The configuration reference lists the .env variables.
Deploy
| Command | What it does |
|---|---|
task bootstrap | Deploys the whole stack from scratch in one command, for example task bootstrap TAG=release-1.0.0. Runs config-init, start, wire, autobase-connect, register-rack, and migrate-pricing. Generates the service secrets and wires the shared ones, including copying app-node's apiKeySecret to proxy-inference. |
task config-init | Writes each service's config under services/<service>/config/ from the examples in that service's image. Generates the app-node secrets and the proxy HRPC keypair. |
task pull | Pulls all images at the resolved TAG. |
task up | Creates and starts the stack. task bootstrap handles a first deployment. |
Lifecycle
| Command | What it does |
|---|---|
task start | Starts containers stopped by task stop. |
task stop | Stops containers without removing them. |
task restart | Recreates every container in the stack, even if unchanged. |
task down | Stops and removes the containers and network. Keeps the config and state directories. |
task update | Upgrades to a new image tag. Pulls the images, adds the config keys the new images introduce, recreates the services, and runs task wire. Reads TAG and the optional SERVICES, for example task update TAG=release-1.0.0. |
task recreate-ui | Rebuilds the UI assets and recreates Caddy. |
Status and debugging
| Command | What it does |
|---|---|
task | Lists the available commands. |
task ps | Shows container status. |
task logs | Follows logs. SERVICES limits the output, for example task logs SERVICES="cosmicac-ui". |
task config | Renders the effective Compose config for debugging. |
Authentication
| Command | What it does |
|---|---|
task login | Logs in to GitHub Container Registry (GHCR). Uses GITHUB_PAT and GITHUB_USER, or prompts for them. |
task ensure-login | Logs in to GHCR only if no credentials are present. Other commands use it as a dependency. |
Keys and wiring
| Command | What it does |
|---|---|
task wire | Derives runtime keys from the service status files and updates the Compose configs and .env. Links the services' shared keys, including the proxy-inference apiKeySecret. |
task ork-key | Prints the ork RPC public key. |
task app-node-key | Prints app-node's autobase bootstrap key. |
task autobase-connect | Registers every worker's autobase writer key into app-node. |
task register-rack | Registers the Kubernetes NVIDIA rack with the ork. |
task migrate-pricing | Applies K8S_GPU_PRICE to the GPU types on registered racks. |
task seed-admin | Creates or updates the first-run UI login from the BOOTSTRAP_ADMIN_* variables. |
Configuration
Four services keep config under DATA_ROOT, which defaults to services/. Each one's settings live in services/<service>/config/common.json, with more files under config/facs/. The cosmicac-ui service serves a static site and has no config directory.
Each service's image carries a *.example file for each of its config files. task config-init copies those examples into services/<service>/config/. If a live file is missing, it creates the file from the example. If the live file exists, it adds each key the example has and the live file lacks, taking the value from the example, and leaves every key the live file already has unchanged. task bootstrap and task update both run task config-init.
Each command below reads the .env variables that carry its prefix and writes their values into that one service's config/common.json and config/facs/*.json. A variable replaces the value at the path it names and leaves the rest of the file unchanged. The command starts no containers.
| Command | Service | .env prefix |
|---|---|---|
task apply-app-node-common-config | app-node | APPNODE_ |
task apply-proxy-inference-common-config | proxy-inference | PROXY_ |
task apply-wrk-ork-common-config | ork | WRKORK_ |
task apply-wrk-server-k8s-nvidia-common-config | Kubernetes worker | K8S_ |
An override takes one of these forms, where <PREFIX> is the service's .env prefix.
| 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.
The command logs a warning and applies nothing from a variable that carries the prefix but matches none of these forms.
--dry-run writes nothing and prints the files the command would produce. --show-config is a second spelling of the same flag, not a separate mode. task passes an argument to the underlying script only after a -- separator.
task apply-app-node-common-config -- --dry-runtask wire applies the Kubernetes worker's overrides during its own run. For app-node, proxy-inference, and the ork, only the apply commands read the overrides.
task wire regenerates the values it manages, such as the cross-service keys and the ork's generated allowlist. A value an apply command wrote for one of those settings doesn't survive task wire. task bootstrap and task update both run task wire.
Backup
| Command | What it does |
|---|---|
task backup | Copies each service's config and state directories to ./backups/<timestamp>. |
Destructive commands
Neither command takes a backup first, and no command restores what they delete. To keep a copy of the config and state directories they remove, run task backup before either one.
| Command | What it removes | Asks first |
|---|---|---|
task clean-state | The status and store directories for the worker services named in SERVICES. They refill on the next task up. | Yes |
task clean | The containers, the Compose volumes, every service's generated data under DATA_ROOT, and the locally built images. | No |
task clean-state requires SERVICES, for example task clean-state SERVICES="cosmicac-wrk-ork". Without SERVICES, the command stops without deleting anything.
task clean deletes all of those items as soon as it runs. The Taskfile calls the underlying script with --yes, so the script's confirmation prompt returns without waiting for an answer. task bootstrap redeploys from the state it leaves behind.