Configuration

You can configure the Plexus agent in three ways. Values are resolved in this order (highest priority first):

Constructor parameters — passed directly to Plexus()
Environment variables — set in your shell or .env file
Config file — saved at ~/.plexus/config.json

Config File

The agent reads from ~/.plexus/config.json. Create this file manually or use plexus pair to generate it.

{
  "api_key": "plx_xxxxx",
  "endpoint": "https://app.plexus.company",
  "source_id": "test-rig-01",
  "source_name": "Test Rig A",
  "org_id": null,
  "command_allowlist": null,
  "command_denylist": null
}

Note: The config file only stores connection and identity settings. Buffer, timeout, and retry parameters are constructor-only — pass them to Plexus() directly.

Environment Variables

Variable	Description	Default
`PLEXUS_API_KEY`	API key (starts with `plx_`)	none
`PLEXUS_ENDPOINT`	Platform URL	`https://app.plexus.company`
`PLEXUS_ORG_ID`	Organization ID	none

export PLEXUS_API_KEY=plx_xxxxx
export PLEXUS_ENDPOINT=https://app.plexus.company

Constructor Parameters

Pass configuration directly when creating the client. Constructor parameters override environment variables and the config file.

from plexus import Plexus
from plexus.config import RetryConfig
 
px = Plexus(
    api_key="plx_xxxxx",
    endpoint="https://app.plexus.company",
    source_id="test-rig-01",
    timeout=10.0,
    max_buffer_size=10000,
    persistent_buffer=True,
    retry_config=RetryConfig(
        max_retries=3,
        base_delay=1.0,
        max_delay=30.0,
        exponential_base=2.0,
        jitter=True,
    ),
)

Parameter Reference

Parameter	Type	Default	Description
`api_key`	`str`	env / config	Your API key.
`endpoint`	`str`	`https://app.plexus.company`	Platform URL. Change for self-hosted deployments.
`source_id`	`str`	`source-{uuid}` (auto-generated)	Unique identifier for this device.
`timeout`	`float`	`10.0`	HTTP request timeout in seconds.
`retry_config`	`RetryConfig`	see below	Retry behavior for failed requests.
`max_buffer_size`	`int`	`10000`	Maximum number of points held in the buffer before dropping oldest.
`persistent_buffer`	`bool`	`False`	Write buffer to SQLite instead of memory. Survives restarts and power loss.
`buffer_path`	`str`	`~/.plexus/buffer.db`	Custom path for SQLite persistent buffer file. Only used when `persistent_buffer=True`.

Retry Configuration

When a send fails (network error, server error), the client retries with exponential backoff. Configure the retry behavior with a RetryConfig dataclass:

from plexus.config import RetryConfig
 
px = Plexus(
    retry_config=RetryConfig(
        max_retries=3,            # Number of retries (4 total attempts)
        base_delay=1.0,           # Seconds before first retry
        max_delay=30.0,           # Maximum delay between retries
        exponential_base=2.0,     # Multiply delay by this each retry
        jitter=True,              # Add randomized jitter to delays
    )
)

Field	Type	Default	Description
`max_retries`	`int`	`3`	Number of retries before giving up (data stays in buffer). 3 retries = 4 total attempts.
`base_delay`	`float`	`1.0`	Seconds to wait before the first retry.
`max_delay`	`float`	`30.0`	Cap on the delay between retries.
`exponential_base`	`float`	`2.0`	Multiplier applied to the delay after each failed attempt.
`jitter`	`bool`	`True`	Add randomized jitter to retry delays to avoid thundering herd.

With the defaults, retry delays are approximately: 1s, 2s, 4s (with jitter applied).

Persistent Buffer

When persistent_buffer=True, the client writes every data point to a local SQLite database at ~/.plexus/buffer.db before sending. Use buffer_path to override the default location. This protects against:

Network outages
Process crashes
Power loss (on devices with storage)

px = Plexus(persistent_buffer=True)
 
# Check how many points are waiting to be sent
print(px.buffer_size())
 
# Force-send all buffered data
px.flush_buffer()

The buffer file is automatically cleaned up after successful delivery.

Example: Production Configuration

from plexus import Plexus
from plexus.config import RetryConfig
 
px = Plexus(
    source_id="rig-A",
    persistent_buffer=True,
    max_buffer_size=50000,
    timeout=60,
    retry_config=RetryConfig(
        max_retries=10,
        base_delay=2.0,
        max_delay=60.0,
        exponential_base=2.0,
        jitter=True,
    ),
)

Next Steps

Sending Data — Start sending telemetry
CLI Reference — Run the agent from the command line

Installation Commands