### Install Go Dependencies

Source: https://github.com/icewhaletech/casaos/blob/main/DEVELOPING.md

After setting up the UI, install the Go dependencies for the project.

```bash
go get
```

--------------------------------

### Install CasaOS

Source: https://github.com/icewhaletech/casaos/blob/main/README.md

Run this command on a fresh system installation to install CasaOS. Supports Ubuntu, Debian, Raspberry Pi OS, and CentOS.

```bash
wget -qO- https://get.casaos.io | sudo bash
```

```bash
curl -fsSL https://get.casaos.io | sudo bash
```

--------------------------------

### Install UI Dependencies and Build

Source: https://github.com/icewhaletech/casaos/blob/main/DEVELOPING.md

Navigate into the UI directory, install its dependencies using yarn, and then build the UI. Finally, return to the project root.

```bash
cd UI
yarn install
yarn build
cd ..
```

--------------------------------

### Install and Generate TypeScript/Axios Client

Source: https://context7.com/icewhaletech/casaos/llms.txt

Instructions for installing dependencies and generating the typed TypeScript/Axios client from the OpenAPI specification using yarn.

```bash
# Install dependencies and generate the client
yarn install
yarn generate:local   # uses local openapi-generator-cli
# or
yarn generate:npx     # uses npx (no local install needed)

```

--------------------------------

### Check CasaOS Version

Source: https://github.com/icewhaletech/casaos/blob/main/README.md

Determine the currently installed version of CasaOS from a terminal session.

```bash
casaos -v
```

--------------------------------

### Get Real-time Resource Utilization

Source: https://context7.com/icewhaletech/casaos/llms.txt

Retrieves current CPU, memory, and network statistics. This is useful for monitoring system performance.

```bash
curl -s -H "Authorization: <token>" \
  http://localhost:<port>/v1/sys/utilization | jq .
# {
#   "success": 200,
#   "data": {
#     "cpu": {
#       "percent":     12.5,
#       "num":         4,
#       "temperature": 45.2,
#       "power":       8.1,
#       "model":       "intel"
#     },
#     "mem": {"total": 8589934592, "used": 2147483648, "usedPercent": 25.0},
#     "net": [
#       {"name":"eth0","bytesSent":102400,"bytesRecv":204800,"state":"up","time":1705312800}
#     ]
#   }
# }
```

--------------------------------

### Get Ports in Use

Source: https://context7.com/icewhaletech/casaos/llms.txt

List all TCP and UDP ports currently bound on the host. Helps prevent port conflicts when deploying applications.

```bash
curl -s -H "Authorization: <token>" http://localhost:<port>/v2/casaos/health/ports | jq .
# Expected response:
# {
#   "message": "",
#   "data": {
#     "tcp": [80, 443, 8080],
#     "udp": [53, 5353]
#   }
# }
```

--------------------------------

### Interact with CasaOS API using TypeScript/Axios SDK

Source: https://context7.com/icewhaletech/casaos/llms.txt

Example demonstrating how to use the generated TypeScript/Axios SDK to interact with the CasaOS API. It covers fetching health status, port information, and ZeroTier details, as well as updating ZeroTier network status. Ensure you have the correct BASE_URL and TOKEN.

```typescript
// Using the generated TypeScript/Axios client
import axios from "axios";
import { HealthMethodsApi, FileApi, ZerotierMethodsApi } from "./generate";

const BASE_URL = "http://casaos.local";
const TOKEN    = "your-access-token";

const client = axios.create({
  baseURL: BASE_URL,
  headers: { Authorization: TOKEN },
});

const healthApi    = new HealthMethodsApi(undefined, BASE_URL, client);
const zerotierApi  = new ZerotierMethodsApi(undefined, BASE_URL, client);

async function main() {
  // Check which services are running
  const { data: services } = await healthApi.getHealthServices();
  console.log("Running:",     services.data?.running);
  console.log("Not running:", services.data?.not_running);

  // Get ports in use
  const { data: ports } = await healthApi.getHealthPorts();
  console.log("TCP ports:", ports.data?.tcp);
  console.log("UDP ports:", ports.data?.udp);

  // Get ZeroTier info
  const { data: zt } = await zerotierApi.getZerotierInfo();
  console.log(`ZT network ${zt.name} (${zt.id}) is ${zt.status}`);

  // Set ZeroTier network offline
  await zerotierApi.setZerotierNetworkStatus(zt.id!, { status: "offline" });
}

main().catch(console.error);
```

--------------------------------

### Get Device Hardware Info

Source: https://context7.com/icewhaletech/casaos/llms.txt

Retrieves the device tree model name and CPU architecture. This information is useful for identifying the specific hardware running CasaOS.

```bash
curl -s -H "Authorization: <token>" \
  http://localhost:<port>/v1/sys/hardware/info | jq .
# {
#   "success": 200,
#   "data": {
#     "drive_model": "Raspberry Pi 4 Model B Rev 1.4",
#     "arch":        "arm64"
#   }
# }
```

--------------------------------

### Get device hardware info

Source: https://context7.com/icewhaletech/casaos/llms.txt

Retrieves information about the device's hardware, specifically the device tree model name and CPU architecture. This is useful for identifying the device in dashboards.

```APIDOC
## GET /v1/sys/hardware/info — Get device hardware info

### Description
Returns the device tree model name and CPU architecture. Useful for displaying device identity in dashboards.

### Method
GET

### Endpoint
/v1/sys/hardware/info

### Response
#### Success Response (200)
```json
{
  "success": 200,
  "data": {
    "drive_model": "Raspberry Pi 4 Model B Rev 1.4",
    "arch":        "arm64"
  }
}
```
```

--------------------------------

### Get ZeroTier Network Info

Source: https://context7.com/icewhaletech/casaos/llms.txt

Retrieve information about the IceWhale remote-access ZeroTier network controller, including its ID, name, and online/offline status. An empty 'via' route indicates the network is online.

```bash
curl -s -H "Authorization: <token>" \
  http://localhost:<port>/v2/casaos/zt/info | jq .
# {
#   "id":     "a1b2c3d4e5",
#   "name":   "IceWhale-RemoteAccess",
#   "status": "online"
# }
```

--------------------------------

### Check for Updates

Source: https://context7.com/icewhaletech/casaos/llms.txt

Compares the installed CasaOS version with the latest available release to determine if an update is needed.

```APIDOC
## GET /v1/sys/version/check — Check for CasaOS updates

### Description
Compares the currently installed version against the latest published release and returns whether an update is available.

### Method
GET

### Endpoint
/v1/sys/version/check

### Request Example
```bash
curl -s -H "Authorization: <token>" \
  http://localhost:<port>/v1/sys/version/check | jq .
```

### Response
#### Success Response (200)
- **data.need_update** (boolean) - True if an update is available, false otherwise.
- **data.current_version** (string) - The currently installed version of CasaOS.
- **data.version.version** (string) - The latest available version.
- **data.version.change_log** (string) - A description of the changes in the latest version.
```

--------------------------------

### Get Current CasaOS UI Port

Source: https://context7.com/icewhaletech/casaos/llms.txt

Fetches the HTTP port that CasaOS is currently using to serve its web interface. This is a simple GET request.

```bash
curl -s -H "Authorization: <token>" \
  http://localhost:<port>/v1/sys/port
# {"success":200,"message":"Success","data":"80"}
```

--------------------------------

### Get real-time resource utilization

Source: https://context7.com/icewhaletech/casaos/llms.txt

Retrieves current system resource usage, including CPU percentage, core count, temperature, power draw, memory statistics, and network I/O counters for all active network interfaces.

```APIDOC
## GET /v1/sys/utilization — Get real-time resource utilization

### Description
Returns CPU usage percentage, core count, temperature, power draw, memory stats, and network I/O counters for all active interfaces.

### Method
GET

### Endpoint
/v1/sys/utilization

### Response
#### Success Response (200)
```json
{
  "success": 200,
  "data": {
    "cpu": {
      "percent":     12.5,
      "num":         4,
      "temperature": 45.2,
      "power":       8.1,
      "model":       "intel"
    },
    "mem": {"total": 8589934592, "used": 2147483648, "usedPercent": 25.0},
    "net": [
      {"name":"eth0","bytesSent":102400,"bytesRecv":204800,"state":"up","time":1705312800}
    ]
  }
}
```
```

--------------------------------

### Get ports currently in use

Source: https://context7.com/icewhaletech/casaos/llms.txt

Lists all TCP and UDP ports currently bound on the host system. This is helpful for preventing port conflicts when deploying Docker applications.

```APIDOC
## GET /v2/casaos/health/ports — Get ports currently in use

### Description
Returns all TCP and UDP ports currently bound on the host. Useful for avoiding port conflicts when deploying Docker apps.

### Method
GET

### Endpoint
/v2/casaos/health/ports

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - API key for authentication.

### Response
#### Success Response (200)
- **message** (string) - An empty string.
- **data** (object) - Contains lists of used ports.
  - **tcp** (array) - List of used TCP ports.
  - **udp** (array) - List of used UDP ports.

### Request Example
```bash
curl -s -H "Authorization: <token>" http://localhost:<port>/v2/casaos/health/ports | jq .
```

### Response Example
```json
{
  "message": "",
  "data": {
    "tcp": [80, 443, 8080],
    "udp": [53, 5353]
  }
}
```
```

--------------------------------

### Check for CasaOS Updates

Source: https://context7.com/icewhaletech/casaos/llms.txt

Compares the installed CasaOS version with the latest release to determine if an update is available. Provides current and latest version information.

```bash
curl -s -H "Authorization: <token>" \
  http://localhost:<port>/v1/sys/version/check | jq .
```

--------------------------------

### Get ZeroTier network info

Source: https://context7.com/icewhaletech/casaos/llms.txt

Retrieves information about the IceWhale remote-access ZeroTier network, including its ID, name, and online/offline status. An empty `via` route indicates the network is online.

```APIDOC
## GET /v2/casaos/zt/info — Get ZeroTier network info

### Description
Returns the ID, name, and online/offline status of the IceWhale remote-access ZeroTier network controller. An empty `via` route indicates the network is online.

### Method
GET

### Endpoint
/v2/casaos/zt/info

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - API key for authentication.

### Response
#### Success Response (200)
- **id** (string) - The ZeroTier network ID.
- **name** (string) - The name of the ZeroTier network.
- **status** (string) - The online/offline status of the network.

### Request Example
```bash
curl -s -H "Authorization: <token>" \
  http://localhost:<port>/v2/casaos/zt/info | jq .
```

### Response Example
```json
{
  "id":     "a1b2c3d4e5",
  "name":   "IceWhale-RemoteAccess",
  "status": "online"
}
```
```

--------------------------------

### Get CasaOS Service Status

Source: https://context7.com/icewhaletech/casaos/llms.txt

Retrieve the running status of CasaOS systemd services. Useful for liveness checks and dashboards.

```bash
curl -s -H "Authorization: <token>" http://localhost:<port>/v2/casaos/health/services | jq .
# Expected response:
# {
#   "message": "",
#   "data": {
#     "running":     ["casaos-gateway.service", "casaos-app-management.service"],
#     "not_running": ["casaos.service"]
#   }
# }
```

--------------------------------

### Get current CasaOS UI port

Source: https://context7.com/icewhaletech/casaos/llms.txt

Fetches the current HTTP port number that the CasaOS web user interface is using.

```APIDOC
## GET /v1/sys/port — Get current CasaOS UI port

### Description
Returns the HTTP port CasaOS is currently serving its web UI on.

### Method
GET

### Endpoint
/v1/sys/port

### Response
#### Success Response (200)
```json
{
  "success": 200,
  "message": "Success",
  "data": "80"
}
```
```

--------------------------------

### Get CasaOS service status

Source: https://context7.com/icewhaletech/casaos/llms.txt

Retrieves the status of CasaOS systemd services, indicating which are running and which are not. This is useful for liveness checks and monitoring dashboards.

```APIDOC
## GET /v2/casaos/health/services — Get CasaOS service status

### Description
Returns which `casaos-*` systemd services are currently running and which are not. Useful for liveness checks and dashboards.

### Method
GET

### Endpoint
/v2/casaos/health/services

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - API key for authentication.

### Response
#### Success Response (200)
- **message** (string) - An empty string.
- **data** (object) - Contains the status of services.
  - **running** (array) - List of running service names.
  - **not_running** (array) - List of not running service names.

### Request Example
```bash
curl -s -H "Authorization: <token>" http://localhost:<port>/v2/casaos/health/services | jq .
```

### Response Example
```json
{
  "message": "",
  "data": {
    "running":     ["casaos-gateway.service", "casaos-app-management.service"],
    "not_running": ["casaos.service"]
  }
}
```
```

--------------------------------

### Create Directory

Source: https://context7.com/icewhaletech/casaos/llms.txt

Creates a directory at the specified path, including any necessary parent directories.

```bash
curl -s -X POST -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{"path": "/DATA/Projects/2024/Q1"}' \
  http://localhost:<port>/v1/file/mkdir
```

--------------------------------

### Serve Image (Original or Thumbnail)

Source: https://context7.com/icewhaletech/casaos/llms.txt

Serves an image file, either as its original or a 100px-wide thumbnail. Useful for displaying images.

```bash
# Fetch thumbnail
curl -s -H "Authorization: <token>" \
  "http://localhost:<port>/v1/file/image?path=/DATA/Photos/holiday.jpg&type=thumbnail" \
  -o thumb.jpg

# Fetch original
curl -s -H "Authorization: <token>" \
  "http://localhost:<port>/v1/file/image?path=/DATA/Photos/holiday.jpg" \
  -o original.jpg
```

--------------------------------

### Create Directory

Source: https://context7.com/icewhaletech/casaos/llms.txt

Creates a new directory at the specified path, including any necessary parent directories.

```APIDOC
## POST /v1/file/mkdir — Create a directory

### Description
Creates a directory (and all missing parent directories) at the given path.

### Method
POST

### Endpoint
/v1/file/mkdir

#### Request Body
- **path** (string) - Required - The absolute path for the new directory.

### Request Example
```bash
curl -s -X POST -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{"path": "/DATA/Projects/2024/Q1"}' \
  http://localhost:<port>/v1/file/mkdir
```

### Response
#### Success Response (200)
- **data** (null) - Indicates the directory creation was successful.
```

--------------------------------

### Real-time peer and file-operation events

Source: https://context7.com/icewhaletech/casaos/llms.txt

Establishes a WebSocket connection to receive live updates on hardware status, file operation progress, and peer discovery messages for local device-to-device transfers. An optional query parameter `?peer=<id>` can be used to reconnect to a known peer.

```APIDOC
## WebSocket /v1/file — Real-time peer and file-operation events

### Description
Connect via WebSocket to receive live hardware status broadcasts (every 5 s), file operation progress, and peer discovery messages (for local device-to-device transfer). An optional `?peer=<id>` query parameter reconnects a known peer.

### Method
WebSocket

### Endpoint
/v1/file

### Parameters
#### Query Parameters
- **peer** (string) - Optional - The ID of a known peer to reconnect to.

### Request Example
```javascript
const ws = new WebSocket("ws://casaos.local/v1/file?peer=my-device-id");

ws.onopen = () => {
  // Server immediately sends: {"type":"peers","peers":[...]} 
  // and:                       {"type":"display-name","message":{"displayName":"My PC","deviceName":"DESKTOP-ABC","id":"uuid"}}
  console.log("Connected to CasaOS peer bus");
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case "peers":
      // msg.peers: [{id, name:{displayName,deviceName,model,os,browser}, rtcSupported}]
      console.log("Available peers:", msg.peers);
      break;
    case "peer-joined":
      console.log("New peer:", msg.peer);
      break;
    case "peer-left":
      console.log("Peer disconnected:", msg.peerId);
      break;
    case "ping":
      ws.send(JSON.stringify({ type: "pong" }));
      break;
  }
};

// Send a direct message to another peer
ws.send(JSON.stringify({
  type: "transfer-request",
  to: "target-peer-uuid",
  payload: { fileName: "document.pdf", size: 204800 }
}));
```
```

--------------------------------

### Real-time Peer and File-Operation Events via WebSocket

Source: https://context7.com/icewhaletech/casaos/llms.txt

Connect to this WebSocket endpoint to receive live broadcasts of hardware status, file operation progress, and peer discovery messages. An optional peer ID can be provided to reconnect to a known peer.

```javascript
const ws = new WebSocket("ws://casaos.local/v1/file?peer=my-device-id");

ws.onopen = () => {
  // Server immediately sends: {"type":"peers","peers":[...]} 
  // and:                       {"type":"display-name","message":{"displayName":"My PC","deviceName":"DESKTOP-ABC","id":"uuid"}}
  console.log("Connected to CasaOS peer bus");
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case "peers":
      // msg.peers: [{id, name:{displayName,deviceName,model,os,browser}, rtcSupported}]
      console.log("Available peers:", msg.peers);
      break;
    case "peer-joined":
      console.log("New peer:", msg.peer);
      break;
    case "peer-left":
      console.log("Peer disconnected:", msg.peerId);
      break;
    case "ping":
      ws.send(JSON.stringify({ type: "pong" }));
      break;
  }
};

// Send a direct message to another peer
ws.send(JSON.stringify({
  type: "transfer-request",
  to: "target-peer-uuid",
  payload: { fileName: "document.pdf", size: 204800 }
}));
```

--------------------------------

### Serve Image

Source: https://context7.com/icewhaletech/casaos/llms.txt

Retrieves an image file, either in its original format or as a thumbnail.

```APIDOC
## GET /v1/file/image — Serve image (original or thumbnail)

### Description
Returns a raw image file. With `type=thumbnail` returns a 100px-wide resized version; with `type=original` (default) serves the full image bytes.

### Method
GET

### Endpoint
/v1/file/image

#### Query Parameters
- **path** (string) - Required - The path to the image file.
- **type** (string) - Optional - The type of image to serve: `original` or `thumbnail`. Defaults to `original`.

### Request Example
```bash
# Fetch thumbnail
curl -s -H "Authorization: <token>" \
  "http://localhost:<port>/v1/file/image?path=/DATA/Photos/holiday.jpg&type=thumbnail" \
  -o thumb.jpg

# Fetch original
curl -s -H "Authorization: <token>" \
  "http://localhost:<port>/v1/file/image?path=/DATA/Photos/holiday.jpg" \
  -o original.jpg
```
```

--------------------------------

### Download CasaOS Log Archive

Source: https://context7.com/icewhaletech/casaos/llms.txt

Stream a ZIP archive of all files under `/var/log/casaos`. Useful for bug reporting.

```bash
curl -s -H "Authorization: <token>" \
  http://localhost:<port>/v2/casaos/health/logs \
  -o casaos_logs.zip

# The response is a binary ZIP file; no JSON envelope.
# Content-Disposition: attachment; filename*=utf-8''casaos.zip
```

--------------------------------

### Build Distributable with Yarn

Source: https://context7.com/icewhaletech/casaos/llms.txt

Command to build the distributable package for CasaOS.

```bash
yarn build
```

--------------------------------

### List Directory Contents (Paginated)

Source: https://context7.com/icewhaletech/casaos/llms.txt

Returns a paginated list of directory contents, including file metadata. Useful for browsing directories.

```bash
curl -s -H "Authorization: <token>" \
  "http://localhost:<port>/v1/file/dirpath?path=/DATA&index=1&size=20" | jq .
```

--------------------------------

### Download Files (Single or Archived)

Source: https://context7.com/icewhaletech/casaos/llms.txt

Downloads a single file directly or multiple files/folders as a compressed archive (zip, tar, or tar.gz).

```bash
# Download a single file
curl -s -H "Authorization: <token>" \
  "http://localhost:<port>/v1/file/download?files=/DATA/report.pdf" \
  -o report.pdf

# Download multiple files as a zip archive
curl -s -H "Authorization: <token>" \
  "http://localhost:<port>/v1/file/download?format=zip&files=/DATA/a.txt,/DATA/b.txt" \
  -o archive.zip
```

--------------------------------

### Download Files

Source: https://context7.com/icewhaletech/casaos/llms.txt

Allows downloading a single file or multiple files/folders as a compressed archive.

```APIDOC
## GET /v1/file/download — Download files (single or archived)

### Description
Downloads a single file directly or multiple files/folders as a compressed archive (zip, tar, or tar.gz).

### Method
GET

### Endpoint
/v1/file/download

#### Query Parameters
- **files** (string) - Required - A comma-separated list of file paths to download. For a single file, provide only one path.
- **format** (string) - Optional - The desired archive format: `zip`, `tar`, or `tar.gz`. If not specified and multiple files are requested, defaults to `zip`.

### Request Example
```bash
# Download a single file
curl -s -H "Authorization: <token>" \
  "http://localhost:<port>/v1/file/download?files=/DATA/report.pdf" \
  -o report.pdf

# Download multiple files as a zip archive
curl -s -H "Authorization: <token>" \
  "http://localhost:<port>/v1/file/download?format=zip&files=/DATA/a.txt,/DATA/b.txt" \
  -o archive.zip
```
```

--------------------------------

### Copy or Move Files

Source: https://context7.com/icewhaletech/casaos/llms.txt

Initiates an asynchronous copy or move operation for specified files or directories.

```APIDOC
## POST /v1/file/operate — Copy or move files

### Description
Enqueues an async copy or move operation. Progress is reported via WebSocket notifications.

### Method
POST

### Endpoint
/v1/file/operate

#### Request Body
- **type** (string) - Required - The operation type: `copy` or `move`.
- **to** (string) - Required - The destination path for the operation.
- **item** (array) - Required - An array of objects, each specifying an item to operate on.
  - **from** (string) - Required - The source path of the item.

### Request Example
```bash
curl -s -X POST -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "copy",
    "to": "/DATA/Backup",
    "item": [
      {"from": "/DATA/Movies/film.mp4"},
      {"from": "/DATA/Music/song.flac"}
    ]
  }' \
  http://localhost:<port>/v1/file/operate
```

### Response
#### Success Response (200)
- **data** (null) - Indicates the operation was successfully enqueued.
```

--------------------------------

### Set ZeroTier Network Status

Source: https://context7.com/icewhaletech/casaos/llms.txt

Enable or disable a specific ZeroTier network by setting its status to 'online' or 'offline'.

```bash
curl -s -X PUT -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "offline"}' \
  http://localhost:<port>/v2/casaos/zt/a1b2c3d4e5/status | jq .
```

--------------------------------

### Uninstall CasaOS (Pre-v0.3.3)

Source: https://github.com/icewhaletech/casaos/blob/main/README.md

Command to uninstall CasaOS for versions prior to 0.3.3.

```bash
curl -fsSL https://get.icewhale.io/casaos-uninstall.sh | sudo bash
```

--------------------------------

### Copy or Move Files

Source: https://context7.com/icewhaletech/casaos/llms.txt

Enqueues an asynchronous copy or move operation for specified files. Progress is reported via WebSocket.

```bash
curl -s -X POST -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "copy",
    "to": "/DATA/Backup",
    "item": [
      {"from": "/DATA/Movies/film.mp4"},
      {"from": "/DATA/Music/song.flac"}
    ]
  }' \
  http://localhost:<port>/v1/file/operate
```

--------------------------------

### Uninstall CasaOS (v0.3.3+)

Source: https://github.com/icewhaletech/casaos/blob/main/README.md

Command to uninstall CasaOS for versions 0.3.3 and newer.

```bash
casaos-uninstall
```

--------------------------------

### Clone CasaOS Repository

Source: https://github.com/icewhaletech/casaos/blob/main/DEVELOPING.md

Clone the CasaOS repository with its submodules. Ensure you replace `<your GitHub Username>` with your actual GitHub username.

```bash
git clone --recurse-submodules --remote-submodules https://github.com/<your GitHub Username>/CasaOS.git
```

--------------------------------

### List Directory Contents

Source: https://context7.com/icewhaletech/casaos/llms.txt

Provides a paginated listing of a directory's contents, including file metadata.

```APIDOC
## GET /v1/file/dirpath — List directory contents (paginated)

### Description
Returns a paginated listing of a directory, including file name, size, type, modification date, and extension metadata (e.g., share and mount state for paths under `/mnt` or `/media`).

### Method
GET

### Endpoint
/v1/file/dirpath

#### Query Parameters
- **path** (string) - Required - The path to the directory.
- **index** (integer) - Required - The starting index for pagination.
- **size** (integer) - Required - The number of items to return per page.

### Request Example
```bash
curl -s -H "Authorization: <token>" \
  "http://localhost:<port>/v1/file/dirpath?path=/DATA&index=1&size=20" | jq .
```

### Response
#### Success Response (200)
- **data.content** (array) - An array of objects, each representing a file or directory.
  - **name** (string) - The name of the file or directory.
  - **size** (integer) - The size of the file in bytes.
  - **is_dir** (boolean) - True if the item is a directory, false otherwise.
  - **path** (string) - The absolute path to the item.
  - **modified** (string) - The last modification date and time.
  - **extensions** (object) - Additional metadata, such as mount status.
- **data.total** (integer) - The total number of items in the directory.
- **data.index** (integer) - The current pagination index.
- **data.size** (integer) - The number of items returned in this response.
```

--------------------------------

### Write Content to File

Source: https://context7.com/icewhaletech/casaos/llms.txt

Overwrites the content of an existing file while preserving its original permission mode.

```bash
curl -s -X PUT -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/DATA/config.yaml", "file_content": "key: value\nfoo: bar\n"}' \
  http://localhost:<port>/v1/file/update
```

--------------------------------

### Read File Content

Source: https://context7.com/icewhaletech/casaos/llms.txt

Retrieves the text content of a specified file on the host filesystem.

```bash
curl -s -H "Authorization: <token>" \
  "http://localhost:<port>/v1/file/read?path=/etc/casaos/casaos.conf"
```

--------------------------------

### Download CasaOS log archive

Source: https://context7.com/icewhaletech/casaos/llms.txt

Streams a ZIP archive containing all files from `/var/log/casaos`. This is useful for debugging and bug reports.

```APIDOC
## GET /v2/casaos/health/logs — Download CasaOS log archive

### Description
Streams a ZIP archive of all files under `/var/log/casaos` as a binary octet-stream attachment. Useful for bug reports.

### Method
GET

### Endpoint
/v2/casaos/health/logs

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - API key for authentication.

### Response
#### Success Response (200)
- The response is a binary ZIP file; no JSON envelope.
- **Content-Disposition** (string) - Attachment header with filename.

### Request Example
```bash
curl -s -H "Authorization: <token>" \
  http://localhost:<port>/v2/casaos/health/logs \
  -o casaos_logs.zip
```
```

--------------------------------

### Trigger CasaOS System Update

Source: https://context7.com/icewhaletech/casaos/llms.txt

Use this endpoint to initiate a download and application of a newer CasaOS version. The update process runs in the background.

```bash
curl -s -X POST -H "Authorization: <token>" \
  http://localhost:<port>/v1/sys/update
# {"success":200,"message":"Success","data":null}
```

--------------------------------

### Delete Files or Directories

Source: https://context7.com/icewhaletech/casaos/llms.txt

Deletes one or more files or directories. This operation refuses to delete mounted paths.

```bash
curl -s -X DELETE -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '["/DATA/old_backup", "/DATA/temp.log"]' \
  http://localhost:<port>/v1/file/delete
```

--------------------------------

### Write Content to File

Source: https://context7.com/icewhaletech/casaos/llms.txt

Updates the content of an existing file, preserving its original permissions.

```APIDOC
## PUT /v1/file/update — Write content to a file

### Description
Overwrites the content of an existing file while preserving its permission mode.

### Method
PUT

### Endpoint
/v1/file/update

#### Request Body
- **file_path** (string) - Required - The absolute path to the file to update.
- **file_content** (string) - Required - The new content for the file.

### Request Example
```bash
curl -s -X PUT -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/DATA/config.yaml", "file_content": "key: value\nfoo: bar\n"}' \
  http://localhost:<port>/v1/file/update
```

### Response
#### Success Response (200)
- **data** (null) - Indicates the file update was successful.
```

--------------------------------

### Read File Content

Source: https://context7.com/icewhaletech/casaos/llms.txt

Retrieves the text content of a specified file from the host filesystem.

```APIDOC
## GET /v1/file/read — Read a file's content

### Description
Returns the text content of any file on the host filesystem.

### Method
GET

### Endpoint
/v1/file/read

#### Query Parameters
- **path** (string) - Required - The absolute path to the file.

### Request Example
```bash
curl -s -H "Authorization: <token>" \
  "http://localhost:<port>/v1/file/read?path=/etc/casaos/casaos.conf"
```

### Response
#### Success Response (200)
- **data** (string) - The content of the file.
```

--------------------------------

### Upload File Chunk

Source: https://context7.com/icewhaletech/casaos/llms.txt

Uploads a single chunk of a multipart file. Chunks are automatically spliced into the final file upon receipt. For single-chunk files, the file is written directly.

```bash
# Split a file and upload chunk 1 of 3
CHUNK=$(dd if=bigfile.iso bs=10M count=1 skip=0 2>/dev/null)

curl -s -X POST -H "Authorization: <token>" \
  http://localhost:<port>/v2/casaos/file/upload \
  -F "path=/DATA" \
  -F "relativePath=/DATA/bigfile.iso" \
  -F "filename=bigfile.iso" \
  -F "chunkNumber=1" \
  -F "totalChunks=3" \
  -F "chunkSize=10485760" \
  -F "currentChunkSize=10485760" \
  -F "totalSize=31457280" \
  -F "identifier=bigfile.iso" \
  -F "file=@/tmp/chunk1.bin"
# {"message":"","data":"ok"}
```

--------------------------------

### Upload a file chunk

Source: https://context7.com/icewhaletech/casaos/llms.txt

Uploads a single chunk of a file as part of a multipart upload process. Once all chunks are received, they are automatically assembled into the final file. For single-chunk files, the file is written directly.

```APIDOC
## POST /v2/casaos/file/upload — Upload a file chunk

### Description
Uploads one chunk of a multipart file. When all chunks are received they are automatically spliced into the final file. For single-chunk files the file is written directly.

### Method
POST

### Endpoint
/v2/casaos/file/upload

### Parameters
#### Form Data Parameters
- **path** (string) - Required - The destination directory path.
- **relativePath** (string) - Required - The relative path for the file.
- **filename** (string) - Required - The name of the file.
- **chunkNumber** (integer) - Required - The current chunk number.
- **totalChunks** (integer) - Required - The total number of chunks.
- **chunkSize** (integer) - Required - The size of each chunk.
- **currentChunkSize** (integer) - Required - The size of the current chunk.
- **totalSize** (integer) - Required - The total size of the file.
- **identifier** (string) - Required - An identifier for the file upload.
- **file** (file) - Required - The file chunk to upload.
#### Header Parameters
- **Authorization** (string) - Required - API key for authentication.

### Response
#### Success Response (200)
- **message** (string) - An empty string.
- **data** (string) - "ok" indicating successful upload.

### Request Example
```bash
# Split a file and upload chunk 1 of 3
CHUNK=$(dd if=bigfile.iso bs=10M count=1 skip=0 2>/dev/null)

curl -s -X POST -H "Authorization: <token>" \
  http://localhost:<port>/v2/casaos/file/upload \
  -F "path=/DATA" \
  -F "relativePath=/DATA/bigfile.iso" \
  -F "filename=bigfile.iso" \
  -F "chunkNumber=1" \
  -F "totalChunks=3" \
  -F "chunkSize=10485760" \
  -F "currentChunkSize=10485760" \
  -F "totalSize=31457280" \
  -F "identifier=bigfile.iso" \
  -F "file=@/tmp/chunk1.bin"
```

### Response Example
```json
{"message":"","data":"ok"}
```
```

--------------------------------

### Check Resumable Upload Chunk

Source: https://context7.com/icewhaletech/casaos/llms.txt

Verify if a file chunk has already been received before uploading. Returns 200 if the chunk exists (skip) or 204 if missing (upload).

```bash
curl -s -H "Authorization: <token>" \
  "http://localhost:<port>/v2/casaos/file/upload?\
path=/DATA&relativePath=/DATA/test.log&filename=test.log&\
chunkNumber=1&totalChunks=3"
# 200 → chunk already uploaded, skip
# 204 → chunk missing, proceed to POST
```

--------------------------------

### Rename File or Directory

Source: https://context7.com/icewhaletech/casaos/llms.txt

Changes the name or location of a file or directory.

```APIDOC
## PUT /v1/file/rename — Rename a file or directory

### Description
Renames or moves a file/directory by specifying old and new absolute paths.

### Method
PUT

### Endpoint
/v1/file/rename

#### Request Body
- **old_path** (string) - Required - The current absolute path of the file or directory.
- **new_path** (string) - Required - The desired new absolute path.

### Request Example
```bash
curl -s -X PUT -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{"old_path": "/DATA/draft.txt", "new_path": "/DATA/final.txt"}' \
  http://localhost:<port>/v1/file/rename
```

### Response
#### Success Response (200)
- **data** (null) - Indicates the rename operation was successful.
```

--------------------------------

### Delete Files or Directories

Source: https://context7.com/icewhaletech/casaos/llms.txt

Removes one or more files or directories from the filesystem.

```APIDOC
## DELETE /v1/file/delete — Delete files or directories

### Description
Deletes one or more files/directories. Refuses to delete paths that are currently mounted.

### Method
DELETE

### Endpoint
/v1/file/delete

#### Request Body
- (array of strings) - Required - An array of absolute paths to the files or directories to delete.

### Request Example
```bash
curl -s -X DELETE -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '["/DATA/old_backup", "/DATA/temp.log"]' \
  http://localhost:<port>/v1/file/delete
```

### Response
#### Success Response (200)
- **data** (null) - Indicates the deletion request was processed.
```

--------------------------------

### Set ZeroTier network status

Source: https://context7.com/icewhaletech/casaos/llms.txt

Enables or disables a specific ZeroTier network by updating its status to either "online" or "offline".

```APIDOC
## PUT /v2/casaos/zt/{network_id}/status — Set ZeroTier network status

### Description
Enables or disables a specific ZeroTier network by setting its status to `"online"` or `"offline"`.

### Method
PUT

### Endpoint
/v2/casaos/zt/{network_id}/status

### Parameters
#### Path Parameters
- **network_id** (string) - Required - The ID of the ZeroTier network to modify.
#### Request Body
- **status** (string) - Required - The desired status: `"online"` or `"offline"`.
#### Header Parameters
- **Authorization** (string) - Required - API key for authentication.
- **Content-Type** (string) - Required - Set to `application/json`.

### Request Example
```bash
curl -s -X PUT -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "offline"}' \
  http://localhost:<port>/v2/casaos/zt/a1b2c3d4e5/status | jq .
```
```

--------------------------------

### Rename File or Directory

Source: https://context7.com/icewhaletech/casaos/llms.txt

Renames or moves a file or directory by specifying its old and new absolute paths.

```bash
curl -s -X PUT -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{"old_path": "/DATA/draft.txt", "new_path": "/DATA/final.txt"}' \
  http://localhost:<port>/v1/file/rename
```

--------------------------------

### Trigger CasaOS system update

Source: https://context7.com/icewhaletech/casaos/llms.txt

Initiates a check for a newer version of CasaOS. If an update is available, it will be downloaded and applied in the background.

```APIDOC
## POST /v1/sys/update — Trigger CasaOS system update

### Description
If a newer version is available, downloads and applies the update in the background.

### Method
POST

### Endpoint
/v1/sys/update

### Request Example
```bash
curl -s -X POST -H "Authorization: <token>" \
  http://localhost:<port>/v1/sys/update
```

### Response
#### Success Response (200)
```json
{
  "success": 200,
  "message": "Success",
  "data": null
}
```
```

--------------------------------

### Check resumable upload chunk

Source: https://context7.com/icewhaletech/casaos/llms.txt

Verifies if a specific chunk of a file has already been uploaded. Returns `200` if the chunk exists (indicating it can be skipped) or `204` if it's missing (requiring upload).

```APIDOC
## GET /v2/casaos/file/upload — Check resumable upload chunk

### Description
Before uploading a chunk, verify whether it has already been received. Returns `200` if the chunk exists (skip it) or `204` if it is missing (upload it). Used by resumable/chunked upload clients.

### Method
GET

### Endpoint
/v2/casaos/file/upload

### Parameters
#### Query Parameters
- **path** (string) - Required - The destination directory path.
- **relativePath** (string) - Required - The relative path for the file.
- **filename** (string) - Required - The name of the file.
- **chunkNumber** (integer) - Required - The current chunk number.
- **totalChunks** (integer) - Required - The total number of chunks.
#### Header Parameters
- **Authorization** (string) - Required - API key for authentication.

### Response
#### Success Response (200)
- Chunk already uploaded, skip.
#### Success Response (204)
- Chunk missing, proceed to POST.

### Request Example
```bash
curl -s -H "Authorization: <token>" \
  "http://localhost:<port>/v2/casaos/file/upload?\
path=/DATA&relativePath=/DATA/test.log&filename=test.log&\chunkNumber=1&totalChunks=3"
```
```

--------------------------------

### Change CasaOS UI Port

Source: https://context7.com/icewhaletech/casaos/llms.txt

Modifies the HTTP port CasaOS listens on. The API verifies that the new port is not already in use before making the change.

```bash
curl -s -X PUT -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{"port": "8080"}' \
  http://localhost:<port>/v1/sys/port
# {"success":200,"message":"Success","data":null}
```

--------------------------------

### Update CasaOS

Source: https://github.com/icewhaletech/casaos/blob/main/README.md

Update CasaOS to the latest release from a terminal session. This command can be run via SSH or a direct terminal connection.

```bash
wget -qO- https://get.casaos.io/update | sudo bash
```

```bash
curl -fsSL https://get.casaos.io/update | sudo bash
```

--------------------------------

### Change CasaOS UI port

Source: https://context7.com/icewhaletech/casaos/llms.txt

Modifies the HTTP port on which CasaOS listens for incoming connections. The API verifies that the new port is not already in use before making the change.

```APIDOC
## PUT /v1/sys/port — Change CasaOS UI port

### Description
Changes the HTTP port CasaOS listens on (after verifying the new port is not already occupied).

### Method
PUT

### Endpoint
/v1/sys/port

### Parameters
#### Request Body
- **port** (string) - Required - The new port number for the CasaOS UI.

### Request Example
```bash
curl -s -X PUT -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{"port": "8080"}' \
  http://localhost:<port>/v1/sys/port
```

### Response
#### Success Response (200)
```json
{
  "success": 200,
  "message": "Success",
  "data": null
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.