Skip to content

Commit 552dca2

Browse files
committed
docs(satellite): update README with idle process management details
1 parent dfe44f0 commit 552dca2

File tree

1 file changed

+10
-0
lines changed

1 file changed

+10
-0
lines changed

services/satellite/README.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,23 +122,27 @@ MCP_PROCESS_IDLE_TIMEOUT_SECONDS=180 # Idle timeout in seconds before terminatin
122122
These limits control resource allocation for MCP server processes running in nsjail isolation:
123123

124124
**NSJAIL_MEMORY_LIMIT_MB** (Default: 50)
125+
125126
- Memory limit per MCP server process in megabytes
126127
- Prevents memory exhaustion attacks
127128
- Recommended range: 50-500 MB depending on MCP server requirements
128129
- Example: Set to 100 for memory-intensive MCP servers
129130

130131
**NSJAIL_CPU_TIME_LIMIT_SECONDS** (Default: 60)
132+
131133
- CPU time limit per MCP server process in seconds
132134
- Protects against CPU-bound infinite loops
133135
- Recommended range: 30-300 seconds
134136
- Note: This is CPU time, not wall-clock time
135137

136138
**NSJAIL_MAX_PROCESSES** (Default: 50)
139+
137140
- Maximum number of child processes per MCP server
138141
- Prevents fork bombs and process exhaustion
139142
- Recommended range: 10-100 depending on MCP server needs
140143

141144
**Development Mode:**
145+
142146
- These limits are **not enforced** in development mode (direct spawn without isolation)
143147
- Allows easier debugging on macOS, Windows, and Linux
144148
- Full isolation only active in production Linux deployments
@@ -150,30 +154,35 @@ These limits control resource allocation for MCP server processes running in nsj
150154
Automatically terminates idle stdio MCP server processes to save resources. Dormant processes are transparently respawned when API calls arrive.
151155

152156
**How It Works:**
157+
153158
- Background job checks all stdio processes every 30 seconds
154159
- Processes idle longer than threshold are gracefully terminated
155160
- Process configurations stored in memory for automatic respawning
156161
- When API call arrives for dormant process, it respawns automatically (1-3s latency)
157162

158163
**Benefits:**
164+
159165
- **Memory Savings**: ~50-100MB per dormant process
160166
- **CPU Savings**: Zero overhead for idle processes
161167
- **Transparent**: MCP clients unaware of sleep/wake cycle
162168
- **Team Isolation**: Maintained (separate processes per team)
163169

164170
**Configuration Options:**
171+
165172
- `180` (default): 3 minutes idle timeout
166173
- `60`: 1 minute idle timeout (aggressive, for high-density deployments)
167174
- `600`: 10 minutes idle timeout (conservative, for frequently-used servers)
168175
- `0`: Disable idle timeout (processes never sleep)
169176

170177
**Edge Cases Handled:**
178+
171179
- Only terminates processes with `status=running`
172180
- Skips processes with active requests in flight
173181
- Prevents concurrent respawn attempts
174182
- Dormant processes excluded from heartbeat reports
175183

176184
**Monitoring:**
185+
177186
```bash
178187
# Check idle process activity
179188
grep "idle_process_check_completed" logs/satellite.log
@@ -186,6 +195,7 @@ grep "dormant_process_respawned" logs/satellite.log
186195
```
187196

188197
**When to Adjust:**
198+
189199
- **High-density deployments**: Lower timeout (60-120s) to maximize resource savings
190200
- **Frequently-used servers**: Higher timeout (300-600s) to avoid unnecessary respawns
191201
- **Development/testing**: Disable (0) to avoid respawn delays during debugging

0 commit comments

Comments
 (0)