Plugin runtime configuration
local-pool parameters, scheduling boundaries, and environment variables for deployment administrators
This reference is for FastGPT self-hosted administrators. The plugin service manages tool installation, worker processes, and request dispatch. The FastGPT server calls tools through that service. See system tool management for installation and remote debug suite configuration for a development environment.
.pkg Package Protocol
System tools are installed and updated through .pkg files. Administrators receive the author's package and check its source, version, and compatibility with the target environment.
Artifact Layout
The plugin project's build and packaging workflow determines its artifacts and output location. See the package and SDK reference.
Manifest Specification
The build generates the Manifest. See metadata and schemas for author-maintained declarations. Changes to those declarations require a new build and installation package.
local-pool Runtime
FastGPT Plugin uses the local-pool process pool runtime by default. It manages Pod worker processes and request queues per plugin service. A Pod here means a worker process managed by the plugin runtime.
Scheduling Pipeline
- Dispatch requests to ready Pods with available concurrency capacity.
- Start workers on demand when capacity is insufficient and the Pod count is below
maxPods. - Queue requests when capacity is reached or startup backoff is active.
- Continue processing queued requests as Pods release capacity or new workers become ready.
- Requests can be rejected or time out when the queue reaches
maxQueueSizeor the wait exceedsqueueTimeout.
Per-Service Parameters
System administrators can adjust these four fields under Admin → (Commercial Edition: System Resources →) System Tools by opening the target tool's configuration modal and switching to the Runtime Configuration tab. Use the current plugin service values shown in the configuration page, and test changes against host resources and the tool's external API rate limits.
| Parameter | Constraint | Description |
|---|---|---|
Minimum worker nodes (minPods) | Nonnegative integer | Minimum Pods retained for the service |
Maximum worker nodes (maxPods) | Positive integer | Maximum Pods allowed for the service |
Pod timeout (podTimeout) | Positive integer, milliseconds | Per-request execution timeout inside a Pod (idle worker recycling wait time is controlled by POOL_SERVICE_IDLE_TIMEOUT) |
Max concurrent requests per Pod (maxConcurrentRequestsPerPod) | Positive integer | Maximum simultaneous requests handled by one Pod |
minPods must be less than or equal to maxPods. Raising Pod counts and per-Pod concurrency increases resource use and can reach external service rate limits sooner.
Global Environment Variables
The plugin service process reads these variables for global capacity and service defaults. Supported variables and default values depend on the deployed FastGPT Plugin version.
| Variable | Description |
|---|---|
POOL_HEALTH_CHECK_INTERVAL | Interval between Pod health checks in milliseconds |
POOL_MAX_TOTAL_PODS | Total Pod limit across plugin services in the server process |
POOL_SERVICE_MIN_PODS | Default minimum worker nodes per plugin service |
POOL_SERVICE_MAX_PODS | Default maximum worker nodes per plugin service |
POOL_SERVICE_IDLE_TIMEOUT | Idle Pod recycling wait time in milliseconds (controls when idle worker processes are terminated) |
POOL_SERVICE_POD_TIMEOUT | Default per-request Pod execution timeout in milliseconds |
POOL_SERVICE_MAX_CONCURRENT_REQUESTS_PER_POD | Default maximum concurrent requests per Pod |
POOL_SERVICE_MAX_REQUESTS_PER_POD | Maximum cumulative requests handled by one Pod |
POOL_SERVICE_MAX_QUEUE_SIZE | Maximum request queue capacity per plugin service |
POOL_SERVICE_QUEUE_TIMEOUT | Timeout for requests waiting for an available Pod, in milliseconds |
POOL_SERVICE_STARTUP_RETRY_BASE_DELAY | Base delay for Pod startup retry backoff, in milliseconds |
POOL_SERVICE_STARTUP_RETRY_MAX_DELAY | Maximum delay for Pod startup retry backoff, in milliseconds |
POOL_SERVICE_POD_MAX_OLD_SPACE_SIZE_MB | V8 old-space memory limit in MB per Pod worker process |
POOL_SERVICE_POD_ALLOW_NET | Whether Pod worker processes are allowed network access (defaults to false; enable when tools call external APIs) |
POOL_SERVICE_POD_TERMINATION_GRACE_PERIOD | Grace period in milliseconds before a Pod process is forcefully terminated |
Failure Isolation and Circuit Breaking
The plugin service manages worker failures, startup retries, and backoff. Begin troubleshooting with service logs to distinguish tool execution errors, worker startup failures, queue timeouts, and host capacity limits. For repeated startup failures, fix dependencies, plugin code, or the runtime environment before verifying recovery. The deployed service version determines retry and circuit-breaking policies.
Last updated