# Linux Installation

Chloros is distributed for Linux as `.deb` packages that install the CLI and backend. The Python SDK is installed separately via pip.

***

## Linux amd64 (x86\_64)

### System Requirements

| Requirement       | Minimum                    | Recommended               |
| ----------------- | -------------------------- | ------------------------- |
| **Distribution**  | Ubuntu 20.04+ / Debian 11+ | Ubuntu 22.04+             |
| **Processor**     | x86\_64 (Intel/AMD)        | Intel Core i7 or better   |
| **Memory (RAM)**  | 8GB                        | 16GB or more              |
| **Graphics Card** | None (CPU processing)      | NVIDIA GPU with 4GB+ VRAM |
| **Storage**       | 2GB free space             | SSD with 10GB+ free space |
| **Python**        | Python 3.7+ (for SDK)      | Python 3.10+              |

### Installation

Download the `.deb` package and install:

```bash
sudo dpkg -i chloros-amd64.deb
```

Verify the installation:

```bash
chloros-cli --version
```

***

## Linux arm64 (NVIDIA Jetson)

### System Requirements

| Requirement      | Minimum                      | Recommended                     |
| ---------------- | ---------------------------- | ------------------------------- |
| **Platform**     | NVIDIA Jetson with JetPack 6 | Jetson Orin NX 16GB or AGX Orin |
| **JetPack**      | JetPack 6.x                  | Latest JetPack 6                |
| **Memory (RAM)** | 8GB (shared GPU/CPU)         | 16GB+ shared                    |
| **Storage**      | 2GB free space               | NVMe SSD with 10GB+ free        |
| **Python**       | Python 3.7+ (for SDK)        | Python 3.10+                    |

### Installation

Download the JetPack 6 `.deb` package and install:

```bash
sudo dpkg -i chloros-arm64-jp6.deb
```

Verify the installation:

```bash
chloros-cli --version
```

For detailed Jetson setup including thermal management and field deployment, see the [NVIDIA Jetson Guide](/chloros/linux-and-edge-computing/nvidia-jetson-guide.md).

***

## Python SDK Installation (All Linux)

The Python SDK is installed separately via pip and works on both amd64 and arm64:

```bash
pip install chloros-sdk
```

To include optional progress streaming support:

```bash
pip install chloros-sdk[progress]
```

Verify the SDK:

```bash
python -c "import chloros_sdk; print(chloros_sdk.__version__)"
```

{% hint style="info" %}
The `.deb` package installs the Chloros CLI and backend. The Python SDK is a separate pip package that communicates with the backend via a local HTTP API.
{% endhint %}

***

## Configuration Directories

Chloros on Linux follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html):

| Purpose                 | Linux Path                | Windows Equivalent         |
| ----------------------- | ------------------------- | -------------------------- |
| **Configuration**       | `~/.config/chloros/`      | `%APPDATA%\Chloros\`       |
| **Data / Projects**     | `~/.local/share/chloros/` | `%LOCALAPPDATA%\Chloros\`  |
| **Cache / Credentials** | `~/.cache/chloros/`       | `%APPDATA%\Chloros\cache\` |

## Backend Executable Locations

The `.deb` package installs the backend to a standard location. The CLI and SDK auto-detect the backend path:

| Installation Method | Backend Path                                 |
| ------------------- | -------------------------------------------- |
| `.deb` package      | `/usr/lib/chloros/chloros-backend`           |
| Manual / custom     | `/opt/mapir/chloros/backend/chloros-backend` |

You can override the backend path with the `--backend-exe` CLI flag or the `backend_exe` SDK constructor parameter.

***

## First-Time Setup

### 1. Activate Your License

A Chloros+ license is required for CLI and SDK access:

```bash
chloros-cli login your@email.com 'your-password'
```

### 2. Check Your License Status

```bash
chloros-cli status
```

### 3. Process Your First Dataset

```bash
chloros-cli process ~/datasets/flight001
```

### 4. Run System Diagnostics

Verify that your system is configured correctly:

```bash
chloros-cli selftest
```

This runs 7 diagnostic checks including version, backend startup, API connectivity, and CUDA/GPU availability.

***

## Bash Scripting Examples

### Process Multiple Datasets

```bash
#!/bin/bash
for dataset in ~/datasets/2026/*/; do
    echo "Processing $(basename "$dataset")..."
    chloros-cli process "$dataset" --format tiff-32
    echo "Done: $(basename "$dataset")"
done
```

### Process with Custom Settings

```bash
#!/bin/bash
chloros-cli process ~/datasets/field_a \
    --output ~/output/field_a \
    --format tiff-32 \
    --indices NDVI NDRE GNDVI \
    --debayer texture-aware \
    --no-vignette
```

### Automated Processing with Cron

Add to your crontab (`crontab -e`) to process new datasets automatically:

```cron
# Process any new datasets at 2 AM daily
0 2 * * * /usr/bin/chloros-cli process /data/incoming --output /data/processed >> /var/log/chloros.log 2>&1
```

### Python SDK Example

```python
from chloros_sdk import process_folder

# One-line processing
result = process_folder(
    "/home/user/datasets/flight001",
    indices=["NDVI", "NDRE"],
    export_format="TIFF (32-bit, Percent)"
)
```

***

## Troubleshooting

### CLI Not Found After Installation

If `chloros-cli` is not found after installing the `.deb` package:

```bash
# Check if the binary exists
which chloros-cli
ls -la /usr/bin/chloros-cli

# If not in PATH, check the installation
dpkg -L chloros-amd64  # or chloros-arm64-jp6

# Reload your shell
source ~/.bashrc
```

### Permission Denied

```bash
# Ensure the binary is executable
sudo chmod +x /usr/bin/chloros-cli
sudo chmod +x /usr/lib/chloros/chloros-backend
```

### Backend Failed to Start

```bash
# Check if port 5000 is already in use
lsof -i :5000

# Kill any existing process on port 5000
kill $(lsof -t -i :5000)

# Try starting with a different port
chloros-cli --port 5001 process ~/datasets/flight001
```

### CUDA Not Detected

```bash
# Check NVIDIA driver installation
nvidia-smi

# Check CUDA availability
nvcc --version

# On Jetson, check JetPack version
cat /etc/nv_tegra_release
```

### Missing Shared Libraries

```bash
# Install common dependencies
sudo apt-get update
sudo apt-get install -f

# Check for missing libraries
ldd /usr/lib/chloros/chloros-backend | grep "not found"
```

***

## Updating Chloros on Linux

Use the built-in update command to check for and install updates:

```bash
# Check for updates without installing
chloros-cli update --check

# Check for and install updates
chloros-cli update
```

***

## Next Steps

* [NVIDIA Jetson Guide](/chloros/linux-and-edge-computing/nvidia-jetson-guide.md) — Jetson-specific optimization and deployment
* [CLI : Command Line](/chloros/cli.md) — Full CLI command reference
* [API : Python SDK](/chloros/api-python-sdk.md) — Full SDK reference
* [Dynamic Compute Adaptation](/chloros/processing-architecture/dynamic-compute-adaptation.md) — How Chloros adapts to your hardware


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mapir.gitbook.io/chloros/linux-and-edge-computing/linux-installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.