---
title: Plugins
description: Extend Octopus with plugins
---

# Plugins

Plugins extend Octopus functionality without modifying core code.

## Overview

Octopus supports two types of plugins:

1. **Static Plugins**: Compiled into the binary
2. **Dynamic Plugins**: Loaded at runtime from `.so`/`.dylib`/`.dll` files

<Callout type="warn" title="The plugin config array is not consumed yet">
  The plugin SDK, lifecycle runtime, and dynamic loader are implemented and
  tested, but the gateway **does not yet load plugins from your configuration**.
  The top-level `plugins:` array is parsed and validated, then ignored — the
  server constructs an empty `PluginManager` with a `TODO: Load plugins from
  config.plugins`, and no plugin runs on the request path today. Treat plugins as
  a stable foundation for authoring, not an end-to-end runtime feature. For
  request/response logic that *is* wired today, use [middleware](/docs/octopus/middleware)
  or [scripting](/docs/octopus/plugins/scripting). See [Plugins & Scripting](/docs/octopus/plugins)
  for the honest, source-verified status.
</Callout>

## Plugin Capabilities

Plugins can provide:

- **Middleware**: Process requests and responses
- **Protocol Handlers**: Support custom protocols
- **Admin Routes**: Extend admin dashboard
- **Metrics**: Custom metrics collection
- **Storage**: Persist plugin state

## The `plugins` configuration array

Each entry deserializes into a `PluginConfig` with these fields: `name`,
`plugin_type` (`static` or `dynamic`, default `static`), `enabled` (default
`true`), `priority` (ordering hint, higher runs first), and a free-form `config`
map passed to the plugin's `init`:

```yaml
plugins:
  - name: my-plugin
    plugin_type: static
    enabled: true
    priority: 100
    config:
      some_key: some_value
```

<Callout type="info">
  This is the real schema, but the array is not yet wired into request handling
  (see the warning above). Configuring a plugin here has no runtime effect today.
  `builtin: true` and a bare `path:` are **not** fields — delivery is selected via
  `plugin_type`. See [Plugins & Scripting](/docs/octopus/plugins).
</Callout>

## Developing Plugins

See [Writing a Plugin](/docs/octopus/plugins/writing-plugins) for creating custom plugins
against the `octopus-plugin-api` SDK.

## Plugin Lifecycle

1. **Load**: Plugin binary loaded
2. **Configure**: Configuration applied
3. **Start**: Plugin starts processing
4. **Running**: Plugin active
5. **Shutdown**: Plugin cleanup

## Next Steps

- [Writing a Plugin](/docs/octopus/plugins/writing-plugins) - Create plugins
- [Plugins & Scripting](/docs/octopus/plugins) - The plugin model and honest status
- [Built-in Plugins](/docs/octopus/plugins/built-in) - What ships in the box today
- [Scripting](/docs/octopus/plugins/scripting) - The embedded Rhai engine