Skip to main content
The Kernel discovers services from ServiceDir. A service package is a .plg file. The Kernel scans that directory, reads each package’s info.yaml, and uses the service configuration to decide whether to start it.

​
Install a service

Arupa does not upload service packages through the management API. To install a service:
  1. Place its .plg package in the configured ServiceDir.
  2. Make sure the Kernel can write to ServiceTempDir, which it uses while loading service packages.
  3. Scan the directory through the API, or restart Arupa so it scans the directory during startup.
  4. Start the service if its effective Restart setting does not enable automatic startup.
The default directories are:
The package must be a valid service archive with a root-level info.yaml. That metadata must provide the service name, version, runtime type (wasm, grpc, or static), contract version, and, for wasm and grpc services, a command to start. Files that are not .plg packages are ignored during a scan. See Service configuration for automatic startup, execution users, access groups, and service parameters.

​
Management API

All service management endpoints are under /api/services and require an authenticated user. They return the standard JSON response shape used by Arupa: success, message, and data.

​
List service state

This endpoint scans the configured ServiceDir before returning the result, so the list always reflects the current contents of that directory; there is no separate scan endpoint. The response includes the configured service_dir and service_temp_dir, a discovered list, and a running list. Discovered entries include package metadata, effective configuration, and lifecycle status. Running entries include the routes and transports registered by each running service.

​
Start, stop, or restart a service

Use the same request body for all three actions:
  • start starts a previously scanned service by name.
  • stop unloads a running service and removes its live host bindings, including every transport and route it registered.
  • restart stops the running instance, then loads the latest scanned package for that service name.
The name field is required. These actions do not accept a package path; the service must already be present in the scan results. A static service has no process to start or stop in the operating-system sense, but it still goes through the same lifecycle: starting it registers its declared transports and routes, and stopping it removes them.

​
Read service directory configuration

The response returns the current service_dir and service_temp_dir.

​
Update service directory configuration

Both fields are required. The API creates the directories before saving the configuration, updates the manager, and scans the new service directory. Changing service_dir takes effect for scanning immediately. Changing service_temp_dir is reported with temp_dir_requires_restart: true because the service manager initializes its extraction directory when it starts.

​
Authentication and access

Every endpoint in this page uses the Kernel’s authentication middleware. An unauthenticated request is rejected before the handler runs. You can add a group restriction for these paths with Route.Allow; see Access control.