feat: implement multi-core concurrency and automatic CPU detection for SimuNet

CLAUDE.md

@@ -73,7 +73,16 @@ uv sync
 uv run agent
 
 # Start simulation network service (SSH servers on configured ports)
+# Default: auto-detects CPU cores and uses (cores - 2) workers, minimum 1
 uv run simunet
+
+# Specify custom number of workers
+NUM_WORKERS=4 uv run simunet
+# or
+uv run simunet --workers 4
+
+# Force single worker mode (enables auto-reload for development)
+NUM_WORKERS=1 uv run simunet
 ```
 
 ### Testing
@@ -97,9 +106,42 @@ uv run pytest tests/bases/netdriver/agent/test_cisco_nexus.py
 Configuration files in `config/`:
 
 - `config/agent/agent.yml` - Agent service settings (logging, session timeouts, SSH parameters, profiles)
-  - Logs are written to `logs/netdriver_agent.log`
+ - Logs are written to `logs/netdriver_agent.log`
 - `config/simunet/simunet.yml` - Simulated device definitions and logging settings
-  - Logs are written to `logs/netdriver_simunet.log`
+ - Logs are written to `logs/netdriver_simunet.log`
+ - In multi-worker mode: `logs/netdriver_simunet_worker_0.log`, `logs/netdriver_simunet_worker_1.log`, etc.
+
+### Multi-Process Mode
+
+Simunet **automatically** uses multi-process mode for improved performance:
+
+**Default Behavior:**
+- Automatically detects CPU cores: `workers = max(1, cpu_cores - 2)`
+- Example: 8-core system → 6 workers, 4-core → 2 workers, 2-core → 1 worker
+- Reserves 2 cores for system and other processes
+- **Smart adjustment**: If worker count exceeds device count, automatically adjusts to match device count
+
+**Override Default:**
+```bash
+# Specify custom number of workers
+NUM_WORKERS=4 uv run simunet
+# or
+uv run simunet --workers 4
+
+# Force single worker (enables auto-reload)
+NUM_WORKERS=1 uv run simunet
+```
+
+**Performance Guidelines:**
+- Small scale (< 10 devices): 1-2 workers
+- Medium scale (10-30 devices): 2-4 workers
+- Large scale (> 30 devices): 4-8 workers
+
+**Notes:**
+- Multi-worker mode (workers > 1) does not support auto-reload
+- Single worker mode supports auto-reload for development
+- Each worker handles a portion of devices automatically
+- Separate log files are created for each worker: `logs/simunet_worker_N.log`
 
 ## Development Guidelines
 

README.md

@@ -51,6 +51,7 @@ Features:
 - 📋 **Command Queue** : Ensures sequential command execution on devices, preventing configuration errors and failures caused by concurrent modifications
 - ⚡ **AsyncSSH Foundation** : Superior concurrency capabilities through asynchronous SSH implementation
 - 🔌 **Plugin Architecture** : Simplified and accelerated development of new vendor support
+- 🚀 **Multi-Process Support** : Automatic worker detection based on CPU cores for optimal performance (SimuNet)
 
 ## Comparison
 

docs/quick-start-simunet.md

@@ -118,8 +118,27 @@ python -c "import netdriver.simunet; print('NetDriver Agent installed successful
 
 #### Run
 
+**Basic Usage**:
+
+```bash
+# Start SimuNet service (auto-detects CPU cores and sets workers)
+simunet
+
+# Start without auto-reload (production)
+simunet --no-reload
+
+# Start with specific number of workers
+simunet --workers 4 --no-reload
+```
+
+**Custom Configuration**:
+
 ```bash
-uvicorn netdriver.agent.main:app --host 0.0.0.0 --port 8001
+# Use custom config file
+simunet --config /path/to/simunet.yml --port 8001
+
+# Set workers via environment variable
+NUM_WORKERS=4 simunet --no-reload
 ```
 
 ### Option 2: Install via Docker
@@ -181,6 +200,93 @@ ssh admin@localhost -p 18020
 
 After successful connection, you can execute commands as you would on a real device:
 
+## Advanced Configuration
+
+### Multi-Process Mode
+
+SimuNet automatically uses multi-process mode based on your CPU cores to improve performance. Each worker process handles a portion of the devices.
+
+#### Default Behavior
+
+**Automatic Worker Detection:**
+- SimuNet automatically detects CPU cores and uses `CPU cores - 2` workers (minimum 1)
+- Example: 8-core CPU → 6 workers, 4-core CPU → 2 workers, 2-core CPU → 1 worker
+- This leaves resources for the system and other processes
+
+**Override Default:**
+
+```bash
+# Use specific number of workers via environment variable
+NUM_WORKERS=4 simunet
+
+# Use specific number of workers via command line
+simunet --workers 4
+
+# Force single worker mode
+NUM_WORKERS=1 simunet
+# or
+simunet --workers 1
+```
+
+#### Performance Recommendations
+
+- **Small Scale (< 10 devices)**: 1-2 workers
+- **Medium Scale (10-30 devices)**: 2-4 workers  
+- **Large Scale (> 30 devices)**: 4-8 workers
+
+Each worker should ideally manage 5-10 devices for optimal performance.
+
+**Note**: 
+- Multi-worker mode (workers > 1) does not support auto-reload
+- Single worker mode supports auto-reload for development
+
+#### Docker Deployment with Multi-Process
+
+```bash
+# Default (auto-detect workers)
+docker run -d \
+  --name netdriver-simunet \
+  --network host \
+  -v $(pwd)/config:/app/config \
+  -v $(pwd)/logs:/app/logs \
+  ghcr.io/opensecflow/netdriver/netdriver-simunet:latest
+
+# Specify worker count
+docker run -d \
+  --name netdriver-simunet \
+  --network host \
+  -e NUM_WORKERS=4 \
+  -v $(pwd)/config:/app/config \
+  -v $(pwd)/logs:/app/logs \
+  ghcr.io/opensecflow/netdriver/netdriver-simunet:latest
+```
+
+#### How Device Distribution Works
+
+When using multi-process mode, devices are automatically distributed among workers:
+
+- Worker 0 handles devices 0 to N/W-1
+- Worker 1 handles devices N/W to 2N/W-1
+- ...
+- Last worker handles remaining devices
+
+**Example 1: 21 devices, 3 workers**
+- Worker 0: devices 0-6 (7 devices, ports 18020-18025)
+- Worker 1: devices 7-13 (7 devices, ports 18026-18031)
+- Worker 2: devices 14-20 (7 devices, ports 18032-18040)
+
+**Example 2: 4 devices, 8 workers (auto-adjusted)**
+- System: 10 CPU cores → 8 workers by default
+- SimuNet automatically adjusts to 4 workers (matches device count)
+- Worker 0: device 0 (1 device)
+- Worker 1: device 1 (1 device)
+- Worker 2: device 2 (1 device)
+- Worker 3: device 3 (1 device)
+
+**Important:** If worker count exceeds device count, it's automatically adjusted to match device count to avoid empty workers.
+
+Each worker creates a separate log file: `logs/simunet_worker_0.log`, `logs/simunet_worker_1.log`, etc.
+
 ## Next Steps
 
 Now that you have SimuNet running, you can set up [NetDriver Agent](./quick-start-agent.md) to connect to SimuNet