Help:Ephemera Agent/Installation

Requirements

• A MediaWiki installation (1.35 or later recommended)
• PHP 7.4+ with the cURL extension enabled (standard on most shared hosts)
• A web host serving PHP (Apache or Nginx)
• An API key from at least one supported AI provider (see Help:Ephemera Agent/LLM Providers)

Step 1 — Upload Server Files

Upload all files from the server/ directory of the release package to your MediaWiki installation directory — the same directory that contains api.php, index.php, and LocalSettings.php.

Files to upload:

• mediawiki-agent.html — the main application UI
• proxy.php — MediaWiki API proxy
• llm-proxy.php — LLM provider proxy
• wiki_api.php — wiki API wrapper (used by agent.php)
• context.php — context assembly pipeline
• classify.php — task classification
• agent.php — main orchestrator

After uploading, verify the proxy is reachable by visiting https://yourwiki.example.com/proxy.php. You should see: {"error":"Origin not allowed: "} — this is correct.

Step 2 — Create a Bot Password

The agent logs into your wiki using a Bot Password — a restricted credential safer than your main admin password.

1. Log into your wiki as an administrator
2. Go to Special:BotPasswords
3. Enter a name for the bot (e.g. EphemeraAgent)
4. Grant the following permissions:
   • Edit existing pages
   • Create, edit, and move pages
   • Delete pages and revisions (optional)
   • Protect pages (optional)
   • Block users (optional)
   • Import pages from file uploads (required for XML import — see note below)
5. Click Create and note the generated password
6. Your bot username will be: YourWikiUsername@EphemeraAgent

XML Import permission

The importupload right is typically restricted to sysops. To grant it to your bot group, add this to LocalSettings.php:

$wgGroupPermissions['bot']['importupload'] = true;

Step 3 — Open the Agent

Navigate to https://yourwiki.example.com/mediawiki-agent.html in your browser. You should see the Ephemera Agent interface.

Step 4 — Log In

1. Click the WIKI tab in the left sidebar
2. Enter your bot username (e.g. Admin@EphemeraAgent) and bot password
3. Click LOGIN
4. The green badge in the header confirms success

Step 5 — Enter an API Key

1. The sidebar switches to the LLM tab after login
2. Select your preferred AI provider
3. Select a model
4. Enter your API key, or load a keys file
5. Type a task in the text area and press RUN or Ctrl+Enter

Adapting to a Different Wiki

To use Ephemera Agent with a wiki other than the default installation:

mediawiki-agent.html

Find these lines near the top of the <script> block: <syntaxhighlight lang="javascript"> var WIKI_BASE_URL = "https://vagabondmedia.net/ephemera"; var WIKI_PROXY_URL = "proxy.php"; var LLM_PROXY_URL = "llm-proxy.php"; var AGENT_PROXY_URL = "agent.php"; </syntaxhighlight>

Change WIKI_BASE_URL to your wiki's base URL.

proxy.php

Find and update the local API URL: <syntaxhighlight lang="php"> $local_api = 'https://vagabondmedia.net/ephemera/api.php'; </syntaxhighlight>

Change it to point to your wiki's api.php.

Allowed Origins

Both proxy.php and llm-proxy.php restrict which domains can call them. Add your domain to the $allowed_origins array in both files.

Common Issues

Login fails

Check that the bot username is in the form User@BotName and that the bot password was copied exactly.

Proxy returns “Origin not allowed”

Add your site to the allowed origins list in proxy.php and llm-proxy.php.

Agent page loads but generation fails

Make sure at least one provider API key is loaded and a Generator model is selected.

XML import is unavailable

Confirm the bot account has the importupload right and that the right is enabled in LocalSettings.php.