Installing a module

Modules are plain DLLs. To install one, drop the build output into Voxta's Modules/ folder and restart. This page covers the exact paths, dependency handling, and what to check when a module doesn't load.

Where Voxta loads modules from

Voxta scans two locations at startup, both relative to its own install folder (the directory containing Voxta.Server.exe):

1. The install folder itself — alongside Voxta.Server.exe and the built-in module DLLs.
2. The Modules/ subfolder inside the install folder.

Any file matching Voxta.Modules.*.dll in either location is treated as a candidate and inspected for a class implementing IVoxtaModule. Only the top level of each folder is scanned — DLLs in nested subfolders are not picked up.

The recommended location for community modules is the Modules/ subfolder. Drop your DLL there:

<Voxta install folder>/
├── Voxta.Server.exe
├── Voxta.Modules.OpenAI.dll              ← built-in modules live alongside the exe
├── Voxta.Modules.ElevenLabs.dll
├── ...
└── Modules/
    └── Voxta.Modules.Hello.dll            ← your module goes here

You can also drop the DLL directly into the install folder, but keeping community modules in Modules/ makes them easy to identify and remove.

Dependencies

Voxta already loads the SDK assemblies (Voxta.Sdk.Modules, Voxta.Model, Voxta.Common, Voxta.Abstractions) and the standard Microsoft.Extensions.* packages. You do not need to copy these alongside your module — drop them and Voxta will warn about duplicate types.

You do need to copy any third-party DLLs you reference that aren't part of the framework. The simplest way:

dotnet publish -c Release -o publish

Then copy from publish/ only the DLLs that aren't already in Voxta's install folder. Both your module DLL and its extra dependencies go in the same location.

If you reference a NuGet package Voxta also references, your DLL will resolve against Voxta's copy — usually fine, but a version mismatch can cause MissingMethodException at runtime. When that happens, either pin to the same version as voxta-server's Directory.Build.props or copy your version alongside the module and accept the duplication.

Verifying it loaded

1. Restart Voxta.
2. Open the Services page.
3. Your module's Label should appear in the catalog, with whatever badges your ServiceDefinition flagged (Experimental, Recommended, etc.).

If it doesn't show up, see Troubleshooting below.

Hot-swap

There is no hot-reload. Voxta loads modules into the main app domain at startup, so changing a DLL requires a full restart. During development, the fastest loop is:

dotnet build -c Debug
# kill Voxta
# copy bin/Debug/net10.0/Voxta.Modules.Yours.dll into the Modules folder
# launch Voxta

A small PowerShell or shell script that copies and relaunches takes most of the friction out.

Troubleshooting

The module doesn't appear in the services list.

• Check the DLL filename — it must start with Voxta.Modules.. Modules with other prefixes are ignored.
• Open Voxta's log file and search for the module name. Load errors (missing dependencies, BadImageFormatException, target framework mismatch) are logged at warning or error level.
• Confirm the target framework matches Voxta's runtime (currently net10.0).

Voxta crashes on startup after installing the module.

• The most likely cause is an exception thrown from IVoxtaModule.Configure. Wrap your registration in a try/catch and log to diagnose, or move suspicious lines out and rebuild.
• A type loaded by your module that conflicts with a Voxta-internal type (e.g. you bundled a different version of Newtonsoft.Json and it's getting picked first). Remove the duplicate.

The module loads but my service doesn't appear in the dropdown for its category.

• Check the Supports dictionary in your ServiceDefinition. The service type must be listed with a non-None score.
• Check the registration call — builder.AddTextGenService<...> for TextGen, builder.AddChatAugmentationsService<...> for ChatAugmentations, etc. If Supports declares a type but no registration call exists for it, the framework can't route to your implementation.

MissingMethodException at runtime.

• A NuGet version mismatch. Identify the assembly from the exception message, check whether Voxta ships a copy in its install folder, and either match its version or copy your version alongside your DLL.