Configuration reference#

conda-presto reads application settings from environment variables when its configuration module is imported. Conda settings come from the active conda context. Command-line flags override only the settings represented by those flags.

Exact environment-variable names, defaults, and scopes are listed in Environment variable reference.

Configuration loading#

Application settings are process configuration. Changing an environment variable after the process imports conda-presto does not update that process.

Integer settings accept decimal integer strings. Boolean settings accept 1, true, or yes and 0, false, or no, without regard to case. Empty values use the default. Ambiguous boolean values and invalid integers fail during application import with a configuration error.

Comma-separated list settings strip surrounding whitespace and omit empty items.

Additional validation rejects:

negative result-cache entry or memory limits
an unknown result-cache backend
negative recorded-request catalog size
candidate persistence with a memory-only backend
a negative refresh interval
a refresh batch size below one
private solver channel or state limits below one
repair suggestion, attempt, or time limits below one

Deployment profiles#

Profile	Process behavior	Public HTTP	Private solver	Scheduled refresh
`conda presto`	One-shot direct rattler solve	no	no	no
`conda presto --serve`	Litestar server with normal request execution	yes	no	no
Docker server	One persistent foreground worker	yes	no	no
Broker service	One persistent foreground worker managed by conda-broker	loopback	loopback	yes

The Docker image sets CONDA_PRESTO_CONCURRENCY=1 and CONDA_PRESTO_PERSISTENT_WORKER=1. Its command fixes the bind host at 0.0.0.0. Its built-in health check always uses container port 8000. See Docker image reference before overriding the application port.

The broker provider injects a loopback host, one foreground request slot, persistent-worker mode, disabled HTTP rate limiting, and enabled conda file locking. It also supplies the broker service identity and allocated endpoint. See Broker service reference for the exact child environment.

Channels and platforms#

CONDA_PRESTO_CHANNELS provides HTTP fallback channels when an input and request do not specify them. The CLI uses it only when conda’s effective channels are empty or exactly defaults and no input file supplies channels. CONDA_PRESTO_PLATFORMS supplies startup warmup targets. It does not become the default target list for an ordinary solve, which uses the host platform when no platform is requested.

The HTTP server checks requested channels against CONDA_PRESTO_ALLOWED_CHANNELS. The default allowlist is the configured fallback channel list. Named channels and multichannels are expanded through conda, then compared by exact credential-free URL, including scheme, authority, and path. This prevents another host or an HTTP downgrade from borrowing an approved canonical channel name. A value of * accepts arbitrary caller-selected HTTP and HTTPS channels, but not local file:// paths. A local channel must be listed explicitly. Use the wildcard only inside an appropriate trust and network-egress boundary.

Startup and readiness#

An ordinary server loads the configured channel and platform metadata during application startup. This primes conda’s on-disk repodata cache, but foreground requests run in fresh child processes and do not reuse the startup process’s indexes. A persistent-worker deployment starts its worker and waits for that worker to load reusable indexes instead.

GET /health reports HTTP 200 after startup when persistent-worker mode is disabled. In persistent-worker mode it reports HTTP 503 whenever the worker is not ready.

The configured channels and platforms affect startup cost. In an ordinary server they should cover metadata worth priming. In a persistent-worker deployment they should cover expected traffic without loading index combinations that the deployment never uses.

Concurrency#

CONDA_PRESTO_CONCURRENCY limits simultaneous foreground solve requests. Ordinary HTTP mode defaults to four. Docker and the broker provider set it to one because they serialize work through a persistent foreground worker.

CONDA_PRESTO_WORKERS controls the process pool used within a multi-platform request. It does not increase the number of foreground requests admitted by the HTTP limiter. Raising it can reduce multi-platform wall time while increasing process and index memory.

Scheduled refresh does not borrow the foreground worker or limiter. It still checks foreground activity before starting work and stops starting requests when foreground work arrives.

Result storage#

The result-cache backend is selected in this order when CONDA_PRESTO_RESULT_CACHE_BACKEND is unset:

Redis when CONDA_PRESTO_RESULT_CACHE_REDIS_URL is set.
File storage when CONDA_PRESTO_RESULT_CACHE_DIR is set.
Memory otherwise.

File storage requires a configured directory. Redis uses redis://localhost:6379/0 when the backend is explicitly set to redis and no URL is supplied. The published server image contains the Redis client.

Public resolve and private solver entries share the in-process entry and byte limits. They use separate persistent key namespaces. See Cache reference for identity, retention, capacity, failure fallback, and invalidation.

HTTP middleware and limits#

The Litestar application configures:

request-body size enforcement
per-client rate limiting when its configured value is nonzero
CORS only when allowed origins are explicitly configured
response compression
structured request logging
solve and parse time limits in the handlers

See Cache reference for cache-specific deadline behavior.

Behind a reverse proxy, uvicorn must trust the intended proxy addresses through --forwarded-allow-ips before forwarded client addresses can be used for rate limiting. TLS, authentication, and public network admission remain deployment responsibilities.

Development workspace#

The Pixi workspace defines these environments:

Environment	Features	Purpose
`dev`	development and server	Editing, linting, and local server work
`test`	test and server	Pytest, coverage, HTTP clients, and server dependencies
`prod`	server	Production HTTP and broker service runtime
`redis`	server	Server runtime with Redis support
`cli`	base	CLI and composite Action local mode
`docs`	documentation	Sphinx and documentation extensions
`release`	release	Isolated package-build environment

The workspace exposes these tasks:

Task	Command	Purpose
`lint`	`pixi run lint`	Check Python with Ruff
`format`	`pixi run format`	Format Python with Ruff
`test`	`pixi run -e test test`	Run pytest with coverage
`bench`	`pixi run -e test bench`	Run pytest-benchmark tests
`serve`	`pixi run serve`	Start a reload-enabled development server
`docs`	`pixi run -e docs docs`	Build the Sphinx site

Changes to Pixi metadata in pyproject.toml require an updated pixi.lock.