Plugin System

Voxeltron has a dual-tier plugin system. Tier 1 runs WASM-compiled plugins in a sandboxed runtime. Tier 2 runs JavaScript/TypeScript plugins in a Bun sidecar. Both are hot-reloadable without restarting the daemon.

All plugins declare their required capabilities in a plugin.toml manifest. You must explicitly grant each capability at install time. Nothing runs silently.

Plugin Tiers

Tier 1 — WASM

Any WASM-compilable language
Rust, Go, C, AssemblyScript
Sandboxed via wasmtime + Extism
64MB memory cap
10s wall-clock timeout per call
Best for: performance-critical, trusted plugins

Tier 2 — JS/TS

JavaScript or TypeScript
Runs in a Bun sidecar process
JSON-RPC over Unix domain socket
Hot-reload without daemon restart
Best for: rapid development, scripting

Available Capabilities

Capability	What it allows	Risk
`fs_read`	Read files in the Voxeltron data dir	Low
`fs_write`	Write files in the Voxeltron data dir	Medium
`network_outbound`	Make outbound HTTP/TCP calls	Medium
`docker_read`	Read container state and metadata	Low
`docker_write`	Create/stop/modify containers	High
`secrets_read`	Read decrypted environment variable values	High
`metrics_read`	Read service metrics	Low
`logs_read`	Read service logs	Low
`notify_send`	Send alerts (email, Slack, webhook)	Medium

Plugin Hooks

Plugins respond to lifecycle hooks fired by the daemon:

on_deploy_start — fires when a deploy begins
on_deploy_success — fires on successful deploy
on_deploy_fail — fires when a deploy fails
on_cert_renew — fires when a TLS cert is renewed
on_backup_complete — fires after each backup
on_alert — fires when a monitoring alert triggers

Writing a JS Plugin

Create a directory with two files:

# plugin.toml
[plugin]
name = "deploy-notifier"
version = "1.0.0"
description = "Posts a Slack message on every deploy"
tier = 2  # JS plugin

[capabilities]
required = ["notify_send", "logs_read"]

[hooks]
on_deploy_success = true
on_deploy_fail = true

# index.ts
import type { VoxeltronPlugin, DeployEvent } from "@voxeltron/sdk";

const plugin: VoxeltronPlugin = {
  async on_deploy_success(event: DeployEvent) {
    await fetch("https://hooks.slack.com/...", {
      method: "POST",
      body: JSON.stringify({
        text: `✅ ${event.service} deployed to ${event.domain}`,
      }),
    });
  },

  async on_deploy_fail(event: DeployEvent) {
    await fetch("https://hooks.slack.com/...", {
      method: "POST",
      body: JSON.stringify({
        text: `❌ ${event.service} deploy failed: ${event.error}`,
      }),
    });
  },
};

export default plugin;

Install a Plugin

# From the marketplace
$ voxeltron plugin install deploy-notifier

Plugin: deploy-notifier v1.0.0
Requires capabilities:
  • notify_send (Medium risk)
  • logs_read (Low risk)

Grant these capabilities? [y/N]: y
✓ Plugin installed and enabled

# From a local directory
$ voxeltron plugin install ./my-plugin/