How CasaOS Manages Runtime Paths and Creates the casaos.url File

CasaOS stores temporary runtime data in /var/run/casaos by default, writing the active HTTP listener address to a casaos.url file during startup so that external scripts and services can discover the current endpoint.

CasaOS uses a centralized runtime directory to coordinate between its Go-based service and external system utilities. The platform determines this path through the CasaOS-Common library constants and persists the live API endpoint to disk for consumption by cleanup scripts and systemd units.

How CasaOS Defines the Runtime Directory

The runtime path originates in the CasaOS-Common library, where the constant DefaultRuntimePath is defined as /var/run/casaos. During initialization, the configuration package (pkg/config/init.go) populates the global CommonInfo model with this value:

// pkg/config/init.go
CommonInfo = &model.CommonModel{
    RuntimePath: constants.DefaultRuntimePath,
}

This global configuration object is mapped from the INI configuration file using mapTo("common", CommonInfo), allowing the value to be overridden by user settings while providing a predictable system default.

Creating the casaos.url File During Startup

When the main service launches its HTTP listener, it immediately constructs the path to the runtime directory and writes the listening address to casaos.url. In main.go (lines 92–98), the code composes the full path using filepath.Join and calls a utility to write the content:

// main.go
urlFilePath := filepath.Join(config.CommonInfo.RuntimePath, "casaos.url")
if err := file.CreateFileAndWriteContent(urlFilePath,
    "http://"+listener.Addr().String()); err != nil {
    logger.Error("error when creating address file", zap.Error(err))
}

The file.CreateFileAndWriteContent function creates the file (including parent directories if necessary) and writes the URL string atomically. This ensures that dependent services can read a valid address as soon as the listener is bound.

Consuming the Runtime URL

External components read the casaos.url file to determine the active CasaOS endpoint. For example, the Debian cleanup script references the file directly at its fixed location:

# build/sysroot/usr/share/casaos/cleanup/service.d/casaos/debian/cleanup-casaos.sh

readonly CASA_URL=/var/run/casaos/casaos.url

The runtime path is also passed to downstream services such as the gateway and message bus via service/service.go (lines 48–50), ensuring internal components remain synchronized with the external runtime environment.

Customizing the Runtime Path

You can override the default runtime directory by modifying the CasaOS configuration file (typically located at /etc/casaos/conf/casaos.conf). Add or update the [common] section with your desired path:

[common]
RuntimePath=/custom/runtime/path

After restarting the CasaOS service, the casaos.url file will be created under the new directory instead of /var/run/casaos.

Reading the casaos.url File in Code

To programmatically retrieve the CasaOS URL from within a Go application, join the runtime path from the configuration and read the file contents:

import (
    "os"
    "path/filepath"

    "github.com/IceWhaleTech/CasaOS/pkg/config"
)

func GetCasaOSURL() (string, error) {
    urlPath := filepath.Join(config.CommonInfo.RuntimePath, "casaos.url")
    data, err := os.ReadFile(urlPath)
    if err != nil {
        return "", err
    }
    return string(data), nil
}

For shell scripts, check for the file existence before reading:

#!/usr/bin/env bash
RUNTIME_PATH="/var/run/casaos"
URL_FILE="${RUNTIME_PATH}/casaos.url"

if [[ -f "$URL_FILE" ]]; then
    CASA_URL=$(cat "$URL_FILE")
    echo "CasaOS is listening at $CASA_URL"
else
    echo "CasaOS URL file not found"
fi

Summary

• Default Location: CasaOS uses /var/run/casaos as the default runtime path, defined in CasaOS-Common/utils/constants/constants.go as DefaultRuntimePath.
• Configuration: The pkg/config/init.go file initializes CommonInfo.RuntimePath from this constant, allowing overrides via the [common] section in the INI config.
• File Creation: During startup, main.go writes the HTTP listener address to casaos.url using file.CreateFileAndWriteContent.
• Consumption: External scripts like cleanup-casaos.sh and internal services read this file to discover the active CasaOS endpoint.

Frequently Asked Questions

What is the default CasaOS runtime path?

CasaOS defaults to /var/run/casaos for runtime data. This path is defined by the DefaultRuntimePath constant in the CasaOS-Common library and is loaded into the global CommonInfo model during service initialization.

How does CasaOS create the casaos.url file?

The service creates the file immediately after starting its HTTP listener. In main.go, it constructs the full path by joining config.CommonInfo.RuntimePath with "casaos.url", then calls file.CreateFileAndWriteContent to write the listener address (prefixed with http://) to disk.

Can I change the CasaOS runtime directory?

Yes. Add a RuntimePath key under the [common] section in your CasaOS configuration file (e.g., /etc/casaos/conf/casaos.conf). The configuration loader uses mapTo("common", CommonInfo) to populate the model, so your custom path will override the default /var/run/casaos value after the service restarts.

Which scripts use the casaos.url file?

System maintenance scripts consume this file to locate the running service. For example, build/sysroot/usr/share/casaos/cleanup/service.d/casaos/debian/cleanup-casaos.sh reads /var/run/casaos/casaos.url to determine the CasaOS endpoint before performing cleanup operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}