Sizing and Capacity Planning
There is no single answer to “I have x users, what resources do I need?”
Rather, resource requirements for Posit Workbench depend on the number of concurrent sessions and the resources each session consumes. Requirements also depend on whether sessions run locally or on an off-host execution backend (Slurm or Kubernetes).
Use the recommendations on this page as starting points and adjust based on monitoring data.
What affects resource needs
Three factors drive Workbench resource requirements: session concurrency, per-session resource consumption, and execution mode.
Session concurrency
The number of simultaneous active sessions is the primary scaling factor for Workbench. A single user can run multiple sessions simultaneously, so the number of concurrent sessions often exceeds the number of active users.
Each IDE session consumes CPU, memory, and file descriptors on the host where it runs.
Per-session resource consumption
Each session’s resource needs depend on the user’s workload. A session that loads a 10 GB data frame and runs a complex model requires far more memory and CPU than one that edits a small script. Because user workloads vary widely, sizing recommendations use moderate defaults. Adjust based on observed usage.
Execution mode
Where sessions run determines which machines need capacity:
- Local execution (single server or high availability (HA)): Sessions run on the Workbench server itself. The server needs enough CPU and memory for all concurrent sessions, plus the Workbench application overhead.
- Off-host execution (Slurm or Kubernetes): Sessions run on the execution cluster. The Workbench node needs enough resources to proxy IDE traffic between the browser and the compute backend. In this mode, concurrent connected users (not concurrent sessions) drive the Workbench node’s resource load, rather than session compute.
Consequences of undersizing
Running Workbench with insufficient resources affects session stability and user experience.
| Resource too low | What happens |
|---|---|
| CPU | Slow session startup, sluggish IDE response, long render times |
| Memory | Sessions killed (out of memory (OOM)), user work lost, new sessions fail to launch |
| Disk | Home directories fill up, RStudio Pro sessions cannot suspend, files cannot save, temporary files cannot be created |
Setting resource guardrails
Resource profiles let you set per-session resource boundaries that prevent both accidental overuse and sessions running with insufficient resources. Set these early, before sizing problems appear.
Administrators can define resource profiles with specific CPU and memory constraints, or allow users to set custom resource parameters within defined bounds. Users then select the appropriate resource profile for their session needs at launch. Each Job Launcher backend also supports maximum CPU and memory limits to prevent any single session from destabilizing the server.
Configure resource profiles for your execution backend:
- Local Launcher Plugin: resource limits
- Kubernetes: user and group profiles
- Slurm: user and group profiles
The audit database records your users’ resource profile selections, giving you visibility into what resources they are typically requesting.
Determining initial size
Initial Workbench sizing depends on execution mode. For local execution (single server and load-balanced or HA), the server must handle both application overhead and session compute. For off-host execution (Kubernetes and Slurm), concurrent connected users drive the Workbench node’s resource load, rather than session compute.
Single server
For deployments where sessions run on the Workbench server, use the following formulas as a starting point:
- CPU: 2 to 6 cores for Workbench overhead + (2 x number of concurrent sessions x CPU per session)
- Memory: 4 GB for Workbench overhead + (number of concurrent sessions x memory per session, minimum 4 GB per session)
- Disk: 20 GB for the Workbench installation + 10 GB or more per user
These formulas reserve 2 to 6 cores and 4 GB for the Workbench application. Use the lower end of the CPU overhead range for smaller deployments, and allocate more, up to 6 cores, as the number of concurrent sessions grows.
If you do not know your per-session resource needs, use the following defaults as minimum starting points:
- RStudio Pro, VS Code, or Jupyter sessions: 1 CPU and 4 GB memory per session
- Positron Pro sessions: 2 CPU and 8 GB memory per session
| Resource | Minimum (5 concurrent sessions) |
Recommended (25 concurrent sessions) |
|---|---|---|
| CPU | 12 cores | 56 cores |
| RAM | 24 GB | 104 GB |
| Disk | 20 GB + 10 GB per user | 20 GB + 10 GB per user |
Both columns use the 1 CPU / 4 GB per-session defaults. For Positron Pro-heavy deployments, recalculate using 2 CPU / 8 GB per session.
For a single-server deployment, the practical session ceiling depends on your instance size. Beyond the recommended range, consider load balancing or off-host execution.
Load-balanced or HA
A load-balanced or HA deployment distributes sessions across multiple nodes. Each node runs sessions locally, so per-node sizing follows the same formulas as single-server, divided across nodes.
For example, 50 concurrent sessions across 2 nodes means sizing each node for 25 sessions.
Per-node specs
Apply the single-server formulas to each node based on the number of sessions it will handle.
| Resource | Minimum (5 concurrent sessions) |
Recommended (25 concurrent sessions) |
|---|---|---|
| CPU | 12 cores | 56 cores |
| RAM | 24 GB | 104 GB |
| Disk | 20 GB | 20 GB |
Both columns use the 1 CPU / 4 GB per-session defaults. For Positron Pro-heavy deployments, recalculate using 2 CPU / 8 GB per session.
Each node needs roughly 20 GB of local disk for the OS, Workbench application, and logs. User home directories should be on shared storage (see Infrastructure requirements), where you plan for 10 GB or more per user.
Infrastructure requirements
In addition to per-node resources, a load-balanced or HA deployment requires the following shared infrastructure.
| Component | Details |
|---|---|
| Shared storage | Network File System (NFS) or equivalent for user home directories, shared project data, and Workbench shared server state (/var/lib/rstudio-server) |
| Load balancer | Workbench includes built-in session routing across nodes. An external load balancer is optional. See Load balancing for configuration details. |
| Clock sync | Network Time Protocol (NTP) across all nodes |
| Database | PostgreSQL for session state and user data |
Database sizing
Workbench stores session state and user data in a single PostgreSQL database. That database requires at least 1 GB of storage. If you run several Posit products against one PostgreSQL instance, give each product its own database.
Those figures size the database. Sizing the instance you provision is a separate concept. In testing, a single AWS db.t3.micro instance with 4 GB of disk handled up to 2,000 concurrent sessions with no notable performance degradation.
Kubernetes and Slurm (off-host execution)
In Kubernetes and Slurm deployments, the Workbench node acts as a reverse proxy, routing IDE traffic between the browser and the compute backend. In these deployments, concurrent connected users drive the Workbench node’s resource load, rather than session compute.
The sizing data in this section comes from load testing at 2,000 concurrent users across 6 proxy nodes (each 8 vCPU (virtual cores) / 16 GB RAM, Slurm backend, light interactive workload).
Per-user proxy overhead
Each connected user adds a small amount of CPU and memory overhead to the proxy node. The table below shows the measured per-user cost under two workload profiles:
- Light: Users run occasional commands with long idle periods between interactions (for example, a batch job running in the background, checking output once per minute). This is representative of most Slurm-offloaded analytical workloads.
- Heavy interactive: Users are actively typing, executing code, and streaming plots or large outputs in near-real time. Use this as a conservative floor when users run interactive notebooks or streaming data workflows.
| Workload type | vCPU per user | RAM per user | Concurrent users per 8 vCPU node |
|---|---|---|---|
| Light | ~0.008 vCPU | ~15 MB | ~300 |
| Heavy interactive | ~0.016 vCPU | ~20-25 MB | ~150 |
Proxy node sizing
Use the per-user overhead above to determine how many proxy nodes your deployment needs. Scale horizontally. Add nodes before sustained CPU utilization exceeds ~70% or RAM exceeds ~80%.
| Total concurrent users | Light workload | Heavy interactive | Min nodes (HA) |
|---|---|---|---|
| 150-300 | 1x (8 vCPU / 16 GB) | 2x (8 vCPU / 16 GB) | 2 |
| 300-600 | 2x (8 vCPU / 16 GB) | 4x (8 vCPU / 16 GB) | 2 |
| 600-2,000 | 6x (8 vCPU / 16 GB) | 12x (8 vCPU / 16 GB) | 2 or more |
Open file descriptor requirement
Workbench needs roughly six persistent connections per concurrent user. These include WebSockets and long-polling for the IDE, session monitor, launcher, and auxiliary services. For 300 concurrent users, this requires a minimum of 1,800 open file descriptors for the Workbench server process (rserver) alone.
Workbench attempts to raise its soft nofile limit to 8192 on startup when running as root, and logs a warning if the attempt is refused. It does not warn if the system’s hard limit is already below 4096 or if rserver is running unprivileged.
Verify that ulimit -n (or the systemd unit’s LimitNOFILE=) meets the sizing above.
For information on Slurm compute node sizing, see the Slurm integration documentation.
Per-session pod resources (Kubernetes)
For sessions running on the Kubernetes cluster, configure resource requests and limits per session pod:
| Resource | Request (starting point) | Limit (starting point) |
|---|---|---|
| CPU | 1 core | 4 cores |
| Memory | 2 GB | 8 GB |
Adjust based on workload. Data science workloads that load large datasets or train models might need significantly more memory. Use resource profiles to let users select appropriate sizes for their work.
Monitoring usage
Once your deployment is running, monitoring helps you understand whether your current resources are sufficient and when it is time to scale. Workbench exposes metrics that track session activity, startup performance, and resource consumption.
Enable monitoring at install time. You cannot backfill metrics that were not recorded.
What to enable
Workbench offers a number of ways to monitor a running deployment:
- A Prometheus endpoint exposes session and server metrics for a Prometheus-compatible system to scrape.
- Posit Chronicle can scrape the Prometheus endpoint to collect session telemetry, audit events, and runtime metrics. It is an embedded service that aggregates these metrics and allows you to query them over time. See Chronicle configuration for setup.
- The audit database records session activity (who started sessions, when, and with which resource profile) for periodic capacity reviews rather than live monitoring. See Reviewing usage patterns below.
Key metrics to watch
The following metrics are the most relevant for capacity planning. Together, they tell you whether session capacity, startup performance, or system resources are becoming a bottleneck.
Workbench exposes the pwb_ metrics through its Prometheus endpoint, and Chronicle retains them over time. System CPU and memory are available through the built-in graphical monitoring or your operating system’s tools.
| Metric | What it tells you |
|---|---|
pwb_sessions |
Active session count. Compare against your sizing target. |
pwb_session_startup_duration_seconds |
Session startup latency. Increasing values suggest resource contention or storage I/O issues. |
pwb_sessions_failed_total |
Sessions failing to launch. Non-zero sustained values need investigation. |
| System CPU utilization | Overall CPU pressure on the Workbench node. Sustained values above 70% indicate it is time to scale. |
| System memory utilization | Overall memory pressure. Sustained values above 80% risk OOM kills. |
For off-host execution deployments, also monitor the execution cluster’s resource utilization (Slurm node load or Kubernetes pod resource usage).
Reviewing usage patterns
Use the historical data collected in the audit database for periodic capacity reviews. For example:
- Are users consistently selecting the smallest resource profile? You might be able to reduce default allocations.
- Are users always selecting the largest resource profile? The default allocation might be too low.
- Are certain users getting frequent killed sessions? They might need more compute, or a workflow change.
When to resize
The metrics above establish a baseline for your deployment. When those numbers start trending in the wrong direction, it might be time to resize. This section walks through the warning signs, your options for scaling, and configuration changes you can try before adding infrastructure.
Signals
Use the metrics from the previous section to identify which resource is under pressure. The table below maps common patterns to their likely cause and recommended response.
| What you see | What it means | What to do |
|---|---|---|
pwb_sessions near your session limit |
Server at session capacity | Increase session limit (if resources allow) or add nodes |
pwb_session_startup_duration_seconds increasing |
Resource contention during startup | Check CPU and disk input/output (I/O). Consider faster storage or more session CPUs |
pwb_sessions_failed_total climbing |
Sessions failing to launch | Check memory (OOM), disk space, and launcher logs |
| System CPU sustained above 70% | CPU saturated | Scale up the Workbench nodes (more cores) or add more nodes |
| System memory sustained above 80% | Memory pressure, OOM risk | Reduce per-session memory or add capacity |
| Users report slow IDE response | Proxy or network bottleneck (off-host execution) or CPU contention (local) | Check proxy node CPU (off-host) or session resource limits (local) |
Scaling options
If the signals above confirm that your current resources are no longer sufficient, the following options go from least to most complex. Start with the simplest option that addresses the bottleneck.
- Tune settings (see What to adjust first): No infrastructure change required.
- Scale vertically: Increase CPU, RAM, or disk on the existing server. This is the most common first step.
- Scale horizontally: Add nodes behind a load balancer. This requires an Enhanced license tier or higher. See Load-balanced or HA for sizing and infrastructure requirements and Load balancing for setup.
- Move to off-host execution: Offload session compute to a Slurm or Kubernetes cluster. This requires an Advanced license tier. See Kubernetes and Slurm for proxy node sizing and the Job Launcher documentation for setup.
What to adjust first
Before adding infrastructure, these configuration changes can help manage demand without hardware changes:
- Resource limits: Set per-session CPU and memory boundaries to prevent runaway processes from affecting other sessions. See Setting resource guardrails for configuration by execution mode.
- Session limit (
session-limit): Cap the number of concurrent sessions per user to prevent a single user from consuming disproportionate resources. - Session timeout (
session-timeout-minutes): Automatically quit or suspend idle sessions to free resources for active users.
See rsession.conf for session-limit and session-timeout-minutes configuration.