> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arupa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin configuration

> Configure plugin startup, execution, access, and parameters.

The `[Plugins]` section controls how the Kernel discovers and runs each
plugin. A plugin is identified by the name declared in its package metadata.
The configuration for that name is then used when the plugin is loaded.

```toml theme={null}
[Plugins]
  [Plugins.default]
    Restart = "no"
    RunAsUser = ""

  [Plugins.hello]
    Restart = "no"
    RunAsUser = ""
    Allow = ["staff"]

    [Plugins.hello.Params]
      greeting = "env://HIHI?"
```

## Default configuration

`[Plugins.default]` provides a base configuration for discovered plugins. A
`[Plugins.<name>]` table is merged on top of that base to produce the effective
configuration for one plugin.

The merge rules are:

* a non-empty `Restart` value replaces the default;
* a non-empty `RunAsUser` value replaces the default;
* a non-empty `Allow` list replaces the default group list; and
* `Params` are merged by key, with the per-plugin value taking precedence.

An empty or omitted per-plugin value does not clear an inherited default for
these fields. In particular, setting `Allow = []` does not remove a non-empty
default `Allow` list in the current implementation.

Only a plugin with a matching name receives its named configuration. If a name
appears in `[Plugins]` but no matching package is found in `PluginDir`, the
Kernel reports that configured plugin as missing during its scan.

## `Restart`

Despite its name, `Restart` currently controls whether the plugin starts
automatically when the Kernel starts. It is not a general crash-restart loop.

The following values enable automatic startup, ignoring case and surrounding
whitespace:

```text theme={null}
always, yes, true, on, enable, enabled, 1
```

Other values, including `no`, `false`, and `off`, disable automatic startup.
A disabled plugin can still be discovered by the plugin manager and started by
an explicit management action.

Changing `Restart` in the configuration does not by itself start or stop an
already running plugin. It is used when the Kernel decides which discovered
plugins to start during its startup sequence.

## `RunAsUser`

`RunAsUser` selects the operating-system user used to run a gRPC plugin
process. An empty value means that the plugin runs as the current Arupa process
user.

```toml theme={null}
[Plugins.ssh]
  RunAsUser = "arupa-plugin"
```

This setting applies to gRPC plugin processes. The Kernel must have the
operating-system permissions required to start a process as the selected user.
If you leave the value empty, the Kernel does not switch users.

## `Allow`

`Allow` is the plugin-wide access restriction. It contains group names from
the [`Groups`](./config-users) configuration:

```toml theme={null}
[Plugins.hello]
  Allow = ["staff"]
```

An empty list leaves the plugin open at this layer. A non-empty list allows a
user who belongs to at least one listed group. The policy applies to every
resource owned by the plugin, including HTTP routes, static mounts, Socket.IO
namespaces, and events.

Plugin-wide access is combined with host route rules and resource-level
policies. Every applicable policy must allow the request. See [Access
control](./config-access) for the complete permission
model.

## `Params`

`Params` contains arbitrary string settings passed to the plugin during
registration:

```toml theme={null}
[Plugins.hello.Params]
  greeting = "hello"
  endpoint = "https://example.com"
```

Parameters from `[Plugins.default.Params]` form the base. Keys in
`[Plugins.<name>.Params]` override matching default keys, while unrelated
default keys remain available to the plugin.

### Environment references

A parameter value can refer to an environment variable instead of storing the
value directly in `config.toml`:

```toml theme={null}
[Plugins.hello.Params]
  required_secret = "env://ARUPA_SECRET"
  optional_label = "env://ARUPA_LABEL?"
```

The Kernel resolves these references when the plugin registers:

* `env://NAME` requires the environment variable to exist. If it is missing,
  plugin loading fails.
* `env://NAME?` is optional. If the variable is missing, the plugin receives
  an empty string.
* Values without the `env://` prefix are passed through unchanged.

The `?` must be the final character of the reference, and the environment
variable name must not contain surrounding whitespace.

## Configuration changes

The Kernel can reload the plugin configuration without rebuilding the HTTP
server. A reload updates the effective configuration held by the plugin
manager and refreshes the `Allow` groups for loaded plugins. Changes to
`Params`, `RunAsUser`, or startup behavior are used when the plugin is next
loaded or started; they do not rewrite an already running plugin process.