Skip to Content
DocumentationGetting StartedSetting Up the Medusa Plugin

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-enrichment

Register 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 the Origin.

Start Suvereo

Build and start Suvereo the way your deployment is run. With the Suvereo Starter:

docker compose build && docker compose up

Create an Admin Service Account

The Medusa plugin authenticates with Suvereo using a service account API key. Create one with:

./manage.py createadminserviceaccount --name Medusa

Run 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 Medusa

The container name suvereo-starter-api-1 may differ in your setup. Run docker ps to 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-enthusiast

Configure Environment Variables

Add the following environment variables to your Medusa project:

VariableDescription
ENTHUSIAST_API_URLSuvereo instance base API URL
ENTHUSIAST_WS_URLSuvereo instance base WebSocket URL (usually the same as the API URL, with ws:// or wss:// prefix
ENTHUSIAST_SERVICE_ACCOUNT_TOKENAdmin 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:9000

If 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:10000

Register 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:migrate

Restart 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/.vite

Docker node_modules volume issues

If you use a Docker volume mount like:

volumes: - .:/server - /server/node_modules

The 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>
Last updated on