Skip to main content
Local sessions are the default and production-recommended session store. With no external dependencies to manage — no Redis, no database, no distributed cache — they provide the simplest path to production. The Orchestrator stores session data in process memory with LRU eviction when capacity is reached.
Console terminology: In the Maverics Console, Orchestrator instances and configuration delivery are managed through Deployments. When working directly with YAML, configuration is managed as files delivered via the -config flag or MAVERICS_CONFIG environment variable.

​
Overview

Session data is stored in-memory and bounded by a configurable capacity limit. When the limit is reached, the oldest sessions are evicted using LRU (Least Recently Used) eviction. Session data is lost on restart and cannot be shared across multiple Orchestrator instances. For session lifetime, cookie, and general configuration options, see the Sessions overview.

​
Multi-Node Deployments

When a deployment includes more than one Orchestrator instance, the local session store requires sticky sessions (session affinity) on your load balancer. Because sessions are stored in each node’s local memory, a user’s requests must consistently reach the same Orchestrator instance that holds their session.
Without sticky sessions, users will be repeatedly redirected to re-authenticate as their requests land on different Orchestrator nodes that don’t have their session data.
Use cookie-based affinity targeting the session cookie (maverics_session by default). Cookie-based affinity is more reliable than IP-based affinity because it works correctly when multiple users share the same IP address (e.g., behind a corporate NAT) or when a user’s IP changes mid-session (e.g., switching networks on a mobile device). If you have customized the cookie name, configure your load balancer to use that custom name instead. If an Orchestrator node goes down, sessions on that node are lost. However, end users typically experience seamless continuity — the Orchestrator redirects the user to the upstream IdP, which recognizes the user’s existing IdP session and completes authentication silently without prompting for credentials. The Orchestrator then creates a new session transparently.
If your deployment requires any node to serve any user’s request without sticky sessions, see Cluster Sessions (experimental).

​
Configuration

The local store is the default — no store configuration is required for single-node deployments. For multi-node deployments, the only local-specific setting is the session capacity: 
session:
  store:
    type: local
    local:
      capacity: 50000
When no session store is configured, the Orchestrator defaults to the local store with a capacity of 50,000 sessions.

​
Configuration Reference

​
Local Store Fields

KeyTypeDefaultRequiredDescription
session.store.typestring"local"NoMust be "local" for local session storage
session.store.local.capacityinteger50000NoMaximum sessions stored in memory (LRU eviction when exceeded)
Session lifetime, cookie, and dynamic expiration settings apply to all session stores and are documented on the Sessions overview page.

​
Troubleshooting

  • Sessions lost on restart — the local session store does not persist sessions across Orchestrator restarts or node failures. This is expected behavior. In practice, session loss is typically transparent to end users: the Orchestrator redirects the user to the upstream IdP, which recognizes the user’s existing IdP session and completes authentication silently (no login prompt). The Orchestrator then creates a new session. The user experiences a brief redirect but is not asked to log in again.
  • Sessions evicted unexpectedly — if the capacity limit is reached, the oldest sessions are evicted via LRU. Increase the capacity or shorten session lifetimes.
  • Sessions not shared across nodes — the local store is node-local. For multi-node deployments, configure sticky sessions (session affinity) on your load balancer using cookie-based affinity on the session cookie. See Multi-Node Deployments above.
  • Cookie domain issues — if sessions are lost when navigating between subdomains, set the cookie domain to the parent domain (e.g., .example.com).
Setting the cookie domain to a parent domain (e.g., .example.com) makes the session cookie accessible to all subdomains under that domain, including staging environments, blogs, and any third-party tools hosted on subdomains. If any subdomain application is compromised, an attacker can read the session cookie and hijack user sessions. Scope the cookie domain as narrowly as possible — only set it to the parent domain if cross-subdomain session sharing is explicitly required. If parent domain scoping is necessary, audit all subdomains to ensure they are trusted.

Sessions

Overview, Console UI walkthrough, and shared configuration reference (cookie, lifetime, store type)

Cluster Sessions

Experimental distributed session storage via Orchestrator clustering

Scale for Production

Configure multi-node deployments with sticky sessions and Redis caching