> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trainy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings

> Configure pluto behavior using environment variables and runtime settings

Settings allow you to customize how pluto behaves during initialization and runtime. You can configure settings through environment variables or by passing parameters directly to `pluto.init()`.

<Note>
  **Performance**: pluto is designed to be fast and non-blocking. Settings allow you to customize behavior without impacting your training performance.
</Note>

<Info>
  **Source**: These settings are available in pluto version 0.1.0+. Make sure you're using the latest version: `pip install pluto-ml`
</Info>

## List of Environment Variables

Configure pluto behavior by setting these environment variables before running your script:

| Variable                            | Type    | Description                                                                                                                                    |
| ----------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `PLUTO_DEBUG_LEVEL`                 | str/int | Controls logging verbosity. Accepts: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` (case-insensitive) or numeric values (10, 20, 30, 40, 50) |
| `PLUTO_URL_APP`                     | str     | Override the default application URL (default: `https://pluto.trainy.ai`)                                                                      |
| `PLUTO_URL_API`                     | str     | Override the default API URL (default: `https://pluto-api.trainy.ai`)                                                                          |
| `PLUTO_URL_INGEST`                  | str     | Override the default ingest URL (default: `https://pluto-ingest.trainy.ai`)                                                                    |
| `PLUTO_URL_PY`                      | str     | Override the default Python API URL (default: `https://pluto-py.trainy.ai`)                                                                    |
| `PLUTO_THREAD_JOIN_TIMEOUT_SECONDS` | int     | Set the timeout in seconds for background thread joins during shutdown (default: `30`)                                                         |

## Setting Environment Variables

### Option 1: Export in Shell

Set environment variables before running your Python script:

```bash theme={null}
export PLUTO_DEBUG_LEVEL=DEBUG
export PLUTO_URL_APP=https://custom-pluto.example.com
python train.py
```

### Option 2: Inline with Command

```bash theme={null}
PLUTO_DEBUG_LEVEL=INFO python train.py
```

### Option 3: In Python Script

```python theme={null}
import os
os.environ['PLUTO_DEBUG_LEVEL'] = 'DEBUG'

import pluto
run = pluto.init(project="my-project", name="experiment-1")
```

<Warning>
  When setting environment variables in Python, make sure to set them **before** importing pluto for them to take effect.
</Warning>

## Customizing Settings via Code

You can also pass settings directly when initializing pluto, which will override environment variables.

pluto logger officially supports customizing the following settings:

| **Parameter**                          | **Type** | **Description**                                                                                                                                                                                                                                           |
| -------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `host`                                 | `str`    | Set the host address for the logger for self-hosted instances.                                                                                                                                                                                            |
| `disable_iface`                        | `bool`   | Disable the network interface exposed to the logger.                                                                                                                                                                                                      |
| `disable_store`                        | `bool`   | Disable the local data store.                                                                                                                                                                                                                             |
| `x_sys_label`                          | `str`    | Set the log group label for system metrics.                                                                                                                                                                                                               |
| `x_grad_label`                         | `str`    | Set the log group label for model gradients.                                                                                                                                                                                                              |
| `x_param_label`                        | `str`    | Set the log group label for model parameters.                                                                                                                                                                                                             |
| `x_sys_sampling_interval`              | `int`    | Set the sampling interval for the system metrics.                                                                                                                                                                                                         |
| `x_log_level`                          | `int`    | Set the log level for the logger.                                                                                                                                                                                                                         |
| `x_file_stream_max_conn`               | `int`    | Set the maximum number of connections allowed for API calls.                                                                                                                                                                                              |
| `x_file_stream_max_size`               | `int`    | Set the maximum size of individual connections.                                                                                                                                                                                                           |
| `x_file_stream_timeout_seconds`        | `int`    | Set the timeout in seconds for individual connections.                                                                                                                                                                                                    |
| `x_file_stream_retry_max`              | `int`    | Set the maximum number of retries for REST API calls.                                                                                                                                                                                                     |
| `x_file_stream_retry_wait_min_seconds` | `int`    | Set the minimum wait time in seconds between retries.                                                                                                                                                                                                     |
| `x_file_stream_retry_wait_max_seconds` | `int`    | Set the maximum wait time in seconds between retries.                                                                                                                                                                                                     |
| `x_thread_join_timeout_seconds`        | `int`    | Set the timeout in seconds for background thread joins during shutdown. Prevents indefinite hangs when worker threads get stuck (e.g., from S3 upload retries). A warning is logged if threads fail to terminate within the timeout. Default: 30 seconds. |

### Using Dictionary

```python theme={null}
import pluto

settings = {
    'x_log_level': 10,  # DEBUG level
    'url_app': 'https://custom-pluto.example.com',
    'url_api': 'https://custom-api.example.com'
}

run = pluto.init(
    project="my-project",
    name="experiment-1",
    settings=settings
)
```

### Using Settings Object

```python theme={null}
import pluto

settings = pluto.Settings()
settings.x_log_level = 10  # DEBUG level
settings.url_app = 'https://custom-pluto.example.com'

run = pluto.init(
    project="my-project",
    name="experiment-1",
    settings=settings
)
```

## Debug Levels

The `PLUTO_DEBUG_LEVEL` environment variable controls how much logging information pluto outputs:

| Level      | Value | Use Case                                                        |
| ---------- | ----- | --------------------------------------------------------------- |
| `DEBUG`    | 10    | Detailed diagnostic information, enables failed request logging |
| `INFO`     | 20    | Confirmation that things are working as expected                |
| `WARNING`  | 30    | Something unexpected happened, but still working                |
| `ERROR`    | 40    | More serious problem, some functionality may not work           |
| `CRITICAL` | 50    | Serious error, program may not be able to continue              |

**Default**: INFO (20)

### Failed Request Logging

When `PLUTO_DEBUG_LEVEL` is set to `DEBUG`, pluto automatically logs failed requests to:

```text theme={null}
~/.pluto/failed_requests.log
```

Each failed request entry includes:

* Timestamp (UTC)
* Request type and URL
* Payload information
* Error details
* Number of retries attempted

This is useful for debugging network issues or investigating why certain metrics weren't logged.

## URL Configuration

Override default Pluto URLs for:

* **Self-hosted deployments**: Point pluto to your own infrastructure
* **Development/staging environments**: Test against non-production servers

## Example: Self-Hosted Server Setup

You can run Pluto on your own infrastructure and configure the client to connect to it.

### Running the Server

Start the Pluto server using Docker Compose provided in the [server repo](https://github.com/Trainy-ai/pluto-server) and updating the `.env.example`:

```bash theme={null}
docker compose --env-file .env up --build
```

<Note>
  Make sure you have Docker and Docker Compose installed on your machine before running this command.
</Note>

### Configuring the Client

Once your server is running, configure the pluto client to connect to your self-hosted instance by setting the URL environment variables:

```bash theme={null}
export PLUTO_URL_APP=http://localhost:3000
export PLUTO_URL_API=http://localhost:3001
export PLUTO_URL_INGEST=http://localhost:3003
export PLUTO_URL_PY=http://localhost:3004
python train.py
```

Or configure it directly in your Python code and pass into `pluto.init`:

```python theme={null}
import pluto

settings = pluto.Settings()
settings.update({
    'url_app': 'http://localhost:3000',
    'url_api': 'http://localhost:3001',
    'url_ingest': 'http://localhost:3003',
    'url_py': 'http://localhost:3004',
})
# Test basic logging functionality
config = {
    'lr': 0.001,
    'epochs': 10,
    'batch_size': 32,
    'test': f'test-ci-commit-{commit_hash}'
}

run = pluto.init(
    project='test-ci',
    name=f'integration-test-commit-{commit_hash}',
    config=config,
    settings=settings
)
```

<Warning>
  Adjust the port numbers according to your server's configuration. Check your `.env` file or Docker Compose configuration for the correct ports.
</Warning>

## Settings Precedence

When the same setting is specified in multiple places, pluto uses this priority order (highest to lowest):

1. **Direct parameters** to `pluto.init(settings=...)`
2. **Environment variables** (`PLUTO_*`)
3. **Default values**

### Example

```python theme={null}
# Environment: PLUTO_DEBUG_LEVEL=WARNING
import pluto

# This will use DEBUG (parameter overrides environment variable)
run = pluto.init(
    project="my-project",
    settings={'x_log_level': 10}  # DEBUG
)
```

## Common Use Cases

### Debugging Failed Uploads

```bash theme={null}
export PLUTO_DEBUG_LEVEL=DEBUG
python train.py
# Check ~/.pluto/failed_requests.log for details
```

## Example: Host with High Availability on EKS

See our guide for deploying the pluto server stack on EKS with terraform here:

[https://github.com/Trainy-ai/pluto-server/tree/main/terraform](https://github.com/Trainy-ai/pluto-server/tree/main/terraform)

Prerequisites:

* An existing clickhouse instance
* A domain you own to house your stack (i.e. `example.com` )
  * `pluto.example.com`
  * `pluto-api.example.com`
  * `pluto-ingest.example.com`
  * `pluto-py.example.com`
* Either Google or Github OAuth2 credentials

The terraform deploys:

* A dedicated VPC
* An RDS Postgres instance
* An EKS auto cluster
* An S3 bucket for storing media files
* The 4 pluto services as k8s deployments
  * frontend - 2 replica default
  * backend - 3 replicas default
  * ingest - 3 replicas default
  * py - 1 replica default
* Redis