Setting Up the Medusa Plugin
Enthusiast provides a plugin for Medusa that integrates AI agents directly into the Medusa admin panel. This enables e-commerce backoffice users to use agents like catalog enrichment, order intake, and documentation search without leaving Medusa.
This guide walks you through setting up Suvereo with Enthusiast, and the plugin in Medusa.
1. Set Up Suvereo with Enthusiast
The first step is to set up a Suvereo deployment with the Enthusiast domain definition. If you don’t have one yet, the easiest way is the Suvereo Starter, a pre-configured Docker Compose setup that includes all required services. If you already run Suvereo, add the packages below to your existing deployment.
Add the Enthusiast Packages
Follow the installation guide to install the domain definition, together with the Medusa integration and the agents you want to use in Medusa:
poetry add enthusiast-domain enthusiast-source-medusa enthusiast-agent-order-intake enthusiast-agent-catalog-enrichmentRegister them in settings_override.py, including the Medusa integration:
CATALOG_INTEGRATION_PLUGINS = [
...
"enthusiast_source_medusa.MedusaIntegration",
]Configure Environment Variables
In the server’s environment (server/config/.env in the Suvereo Starter), set the following:
OPENAI_API_KEY— your OpenAI API key, required for using the language model (or the key for whichever language model provider you use).ECL_DJANGO_ALLOWED_HOSTS— the hosts Suvereo accepts requests for. If your Medusa instance runs inside a Docker container, add"host.docker.internal"to this list. This is the host Medusa uses to communicate with Suvereo.ECL_DJANGO_CORS_ALLOWED_ORIGINS— add your Medusa admin URL (for example"http://localhost:9000"). The plugin opens WebSocket connections with this URL as theOrigin.
Start Suvereo
Build and start Suvereo the way your deployment is run. With the Suvereo Starter:
docker compose build && docker compose upCreate an Admin Service Account
The Medusa plugin authenticates with Suvereo using a service account API key. Create one with:
./manage.py createadminserviceaccount --name MedusaRun it in the server’s environment. With the Suvereo Starter, that means inside the API container:
docker exec -it suvereo-starter-api-1 ./manage.py createadminserviceaccount --name MedusaThe container name
suvereo-starter-api-1may differ in your setup. Rundocker psto find the correct container name for the API service.
Copy the returned API key — you will need it in the next section.
2. Install the Enthusiast Plugin in Medusa
In your Medusa project directory, follow these steps:
Add the Enthusiast Plugin Package
yarn add @upsidelab/medusa-plugin-enthusiastConfigure Environment Variables
Add the following environment variables to your Medusa project:
| Variable | Description |
|---|---|
ENTHUSIAST_API_URL | Suvereo instance base API URL |
ENTHUSIAST_WS_URL | Suvereo instance base WebSocket URL (usually the same as the API URL, with ws:// or wss:// prefix |
ENTHUSIAST_SERVICE_ACCOUNT_TOKEN | Admin service account API key from the previous step |
ENTHUSIAST_INTEGRATION_TYPE | (Optional) Type of the integration registered in Suvereo that Medusa data is synchronized through. Defaults to medusa, which is what enthusiast-source-medusa registers |
ENTHUSIAST_OVERRIDE_EXISTING_INTEGRATION | (Optional) When true, an existing integration of that type in the dataset that the plugin didn’t create is adopted and its config overwritten. When false (default), a new integration is created instead |
ENTHUSIAST_MEDUSA_BACKEND_URL | (Optional) Medusa backend URL that Suvereo sends requests to. Defaults to http://host.docker.internal:9000 |
ENTHUSIAST_MEDUSA_ADMIN_URL | (Optional) Medusa admin URL. Defaults to http://localhost:9000 |
If you’re running Medusa in Docker, it will most likely look like this:
ENTHUSIAST_API_URL=http://host.docker.internal:10000
ENTHUSIAST_WS_URL=ws://host.docker.internal:10000
ENTHUSIAST_SERVICE_ACCOUNT_TOKEN=<generated-service-account-token>
ENTHUSIAST_MEDUSA_BACKEND_URL=http://host.docker.internal:9000
ENTHUSIAST_MEDUSA_ADMIN_URL=http://localhost:9000If you’re running your Medusa instance outside of Docker, you’ll have to change the following two variables:
ENTHUSIAST_API_URL=http://localhost:10000
ENTHUSIAST_WS_URL=ws://localhost:10000Register the Plugin
Now it’s time to register the plugin in Medusa. Add it to your medusa-config.ts:
// medusa-config.ts
const plugins = [{
resolve: "@upsidelab/medusa-plugin-enthusiast",
options: {
enthusiastApiUrl: process.env.ENTHUSIAST_API_URL,
enthusiastWSUrl: process.env.ENTHUSIAST_WS_URL,
enthusiastServiceAccountToken: process.env.ENTHUSIAST_SERVICE_ACCOUNT_TOKEN,
enthusiastIntegrationType: process.env.ENTHUSIAST_INTEGRATION_TYPE,
overrideExistingIntegration: process.env.ENTHUSIAST_OVERRIDE_EXISTING_INTEGRATION === "true",
medusaBackendUrl: process.env.ENTHUSIAST_MEDUSA_BACKEND_URL,
medusaAdminUrl: process.env.ENTHUSIAST_MEDUSA_ADMIN_URL,
}
}]
module.exports = defineConfig({
// ...
plugins
})Run Migrations
yarn medusa db:migrateRestart Your Service
Restart your Medusa instance for the changes to take effect.
3. Start Using Enthusiast in Medusa
Once the plugin is installed and Medusa has been restarted, open the Medusa admin panel at http://localhost:9000/app/.
You should see “Enthusiast” in the sidebar. On first launch, the plugin will prompt you to configure the connection and select a language model.
Once the configuration is complete, you can start interacting with the available agents.
Troubleshooting
Vite cache not updating (dev setups)
In development, Vite’s cache can prevent admin panel changes from appearing after installing or updating packages. Delete the cache folder — it will rebuild on restart:
rm -rf node_modules/.viteDocker node_modules volume issues
If you use a Docker volume mount like:
volumes:
- .:/server
- /server/node_modulesThe anonymous /server/node_modules volume can override dependencies installed during image build. If new packages don’t appear, remove that specific volume:
docker volume ls
docker volume rm <node_modules_volume>