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

> Learn how CasaOS manages runtime paths and creates the casaos.url file to easily discover the current endpoint for external scripts and services.

- Repository: [IceWhale/CasaOS](https://github.com/IceWhaleTech/CasaOS)
- Tags: internals
- Published: 2026-06-26

---

**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`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/config/init.go)) populates the global `CommonInfo` model with this value:

```go
// 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`](https://github.com/IceWhaleTech/CasaOS/blob/main/main.go) (lines 92–98), the code composes the full path using `filepath.Join` and calls a utility to write the content:

```go
// 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:

```bash

# 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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/casaos/conf/casaos.conf)). Add or update the `[common]` section with your desired path:

```ini
[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:

```go
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:

```bash
#!/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/CasaOS-Common/utils/constants/constants.go) as `DefaultRuntimePath`.
- **Configuration**: The [`pkg/config/init.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/main.go) writes the HTTP listener address to `casaos.url` using `file.CreateFileAndWriteContent`.
- **Consumption**: External scripts like [`cleanup-casaos.sh`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main//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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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.