UpNext is configured via environment variables with the UPNEXT_ prefix. Some settings can also be passed directly to Worker and Api constructors where applicable.
Core settings
| Variable | Default | Description |
|---|
UPNEXT_REDIS_URL | — | Redis connection URL (required for workers and real-time server streams) |
UPNEXT_URL | http://localhost:8000 | UpNext server URL (for dashboard reporting) |
UPNEXT_API_KEY | — | Static bearer token for self-hosted server authentication |
UPNEXT_DEBUG | false | Enable debug mode |
UPNEXT_ENV | development | Environment name (development/dev or production/prod) |
Server settings
Backend-first: set UPNEXT_BACKEND explicitly when starting the server.
| Variable | Default | Description |
|---|
UPNEXT_BACKEND | redis | Server persistence backend: redis, sqlite, or postgres |
UPNEXT_DATABASE_URL | — | SQL connection URL used only when UPNEXT_BACKEND=sqlite or postgres |
UPNEXT_AUTH_ENABLED | false | Enable the self-hosted bearer-token gate |
UPNEXT_CLEANUP_RETENTION_HOURS | backend-dependent | Job/artifact cleanup retention window in hours |
Persistence backend behavior
UPNEXT_BACKEND | UPNEXT_DATABASE_URL behavior | Migrations |
|---|
redis | Ignored for persistence | Not used |
sqlite | Optional; defaults to sqlite+aiosqlite:///upnext.db | Not required (tables auto-create at startup) |
postgres | Required | Required before startup (upnext server db upgrade head) |
UPNEXT_BACKEND=redis is ideal for simple/low-scale deployments with no SQL dependency.
UPNEXT_BACKEND=postgres is the recommended path for longer-term, higher-scale persistence needs.
Authentication model
- Self-hosted: optional single-token auth using
UPNEXT_AUTH_ENABLED=true and UPNEXT_API_KEY.
Cleanup retention defaults
UPNEXT_BACKEND=redis defaults UPNEXT_CLEANUP_RETENTION_HOURS to 6.UPNEXT_BACKEND=sqlite and UPNEXT_BACKEND=postgres default it to 168.
Queue tuning
Queue behavior can be tuned with environment variables.
| Variable | Default | Description |
|---|
UPNEXT_QUEUE_BATCH_SIZE | 4 | Number of jobs fetched/flushed per batch |
UPNEXT_QUEUE_INBOX_SIZE | 4 | In-memory fetch buffer size (minimum batch size) |
UPNEXT_QUEUE_OUTBOX_SIZE | 10000 | In-memory completion buffer size |
UPNEXT_QUEUE_FLUSH_INTERVAL_MS | 5.0 | Max delay before flushing completion updates |
UPNEXT_QUEUE_JOB_TTL_SECONDS | 86400 | Job data TTL (24 hours) |
UPNEXT_QUEUE_CLAIM_TIMEOUT_MS | 30000 | Job claim timeout (30 seconds) |
UPNEXT_QUEUE_STREAM_MAXLEN | 0 | Stream trim cap (0 = unbounded) |
UPNEXT_QUEUE_DISPATCH_EVENTS_STREAM_MAXLEN | 10000 | Dispatch diagnostics stream max length |
Status stream settings
| Variable | Default | Description |
|---|
UPNEXT_STATUS_STREAM_MAX_LEN | 50000 | Status event stream max length |
UPNEXT_STATUS_PUBLISH_RETRY_ATTEMPTS | 3 | Retries for publishing status events |
UPNEXT_STATUS_PUBLISH_RETRY_BASE_MS | 25.0 | Base retry delay (ms) |
UPNEXT_STATUS_PUBLISH_RETRY_MAX_MS | 500.0 | Max retry delay (ms) |
UPNEXT_STATUS_PENDING_BUFFER_SIZE | 10000 | In-memory pending buffer capacity |
UPNEXT_STATUS_PENDING_FLUSH_BATCH_SIZE | 128 | Pending buffer flush batch size |
UPNEXT_STATUS_DURABLE_BUFFER_ENABLED | true | Enable Redis-backed durable buffer |
UPNEXT_STATUS_DURABLE_BUFFER_MAXLEN | 10000 | Durable buffer max entries |
UPNEXT_STATUS_SHUTDOWN_FLUSH_TIMEOUT_SECONDS | 2.0 | Timeout for flushing on shutdown |
UPNEXT_STATUS_PUBLISH_STRICT | false | Fail-closed on publish errors |
Progress settings
| Variable | Default | Description |
|---|
UPNEXT_PROGRESS_MIN_DELTA | 0.01 | Minimum progress change to publish (1%) |
UPNEXT_PROGRESS_MIN_INTERVAL_SECONDS | 0.2 | Minimum time between progress updates |
API tracking settings
| Variable | Default | Description |
|---|
UPNEXT_API_TRACKING_NORMALIZE_PATHS | true | Normalize path parameters in tracking |
UPNEXT_API_TRACKING_REGISTRY_REFRESH_SECONDS | 60 | Route registry refresh interval |
UPNEXT_API_REQUEST_EVENTS_ENABLED | true | Enable request event tracking |
UPNEXT_API_REQUEST_EVENTS_SAMPLE_RATE | 1.0 | Sampling rate for request events (0.0-1.0) |
UPNEXT_API_REQUEST_EVENTS_SLOW_MS | 500.0 | Threshold for slow request logging (ms) |
UPNEXT_API_REQUEST_EVENTS_STREAM_MAX_LEN | 50000 | Request event stream max length |
Artifact storage
| Variable | Default | Description |
|---|
UPNEXT_ARTIFACT_STORAGE_BACKEND | local | Storage backend: local or s3 |
UPNEXT_ARTIFACT_STORAGE_LOCAL_ROOT | ~/.upnext/artifacts | Local storage directory |
