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().

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

Source: These settings are available in pluto version 0.1.0+. Make sure you’re using the latest version: pip install pluto-ml

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:

export PLUTO_DEBUG_LEVEL=DEBUG
export PLUTO_URL_APP=https://custom-pluto.example.com
python train.py

Option 2: Inline with Command

PLUTO_DEBUG_LEVEL=INFO python train.py

Option 3: In Python Script

import os
os.environ['PLUTO_DEBUG_LEVEL'] = 'DEBUG'

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

When setting environment variables in Python, make sure to set them before importing pluto for them to take effect.

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

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

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:

~/.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 and updating the .env.example:

docker compose --env-file .env up --build

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

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:

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:

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
)

Adjust the port numbers according to your server’s configuration. Check your .env file or Docker Compose configuration for the correct ports.

Settings Precedence

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

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

Example

# 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

export PLUTO_DEBUG_LEVEL=DEBUG
python train.py
# Check ~/.pluto/failed_requests.log for details

Get Started

Core

Migrate

List of Environment Variables

Setting Environment Variables

Option 1: Export in Shell

Option 2: Inline with Command

Option 3: In Python Script

Customizing Settings via Code

Using Dictionary

Using Settings Object

Debug Levels

Failed Request Logging

URL Configuration

Example: Self-Hosted Server Setup

Running the Server

Configuring the Client

Settings Precedence

Example

Common Use Cases

Debugging Failed Uploads

Get Started

Core

Migrate

​List of Environment Variables

​Setting Environment Variables

​Option 1: Export in Shell

​Option 2: Inline with Command

​Option 3: In Python Script

​Customizing Settings via Code

​Using Dictionary

​Using Settings Object

​Debug Levels

​Failed Request Logging

​URL Configuration

​Example: Self-Hosted Server Setup

​Running the Server

​Configuring the Client

​Settings Precedence

​Example

​Common Use Cases

​Debugging Failed Uploads

List of Environment Variables

Setting Environment Variables

Option 1: Export in Shell

Option 2: Inline with Command

Option 3: In Python Script

Customizing Settings via Code

Using Dictionary

Using Settings Object

Debug Levels

Failed Request Logging

URL Configuration

Example: Self-Hosted Server Setup

Running the Server

Configuring the Client

Settings Precedence

Example

Common Use Cases

Debugging Failed Uploads