EphemeraAdmin: Import: Help:Ephemera Agent/Installation

2026-04-01T04:29:28Z

Import: Help:Ephemera Agent/Installation

New page

{{DISPLAYTITLE:Ephemera Agent — Installation}}
__TOC__

== 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 <code>server/</code> directory of the release package to your MediaWiki installation directory — the same directory that contains <code>api.php</code>, <code>index.php</code>, and <code>LocalSettings.php</code>.

Files to upload:
* <code>mediawiki-agent.html</code> — the main application UI
* <code>proxy.php</code> — MediaWiki API proxy
* <code>llm-proxy.php</code> — LLM provider proxy
* <code>wiki_api.php</code> — wiki API wrapper (used by agent.php)
* <code>context.php</code> — context assembly pipeline
* <code>classify.php</code> — task classification
* <code>agent.php</code> — main orchestrator

After uploading, verify the proxy is reachable by visiting <code>https://yourwiki.example.com/proxy.php</code>. You should see: <code>{"error":"Origin not allowed: "}</code> — 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.

# Log into your wiki as an administrator
# Go to [[Special:BotPasswords]]
# Enter a name for the bot (e.g. <code>EphemeraAgent</code>)
# 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)
# Click '''Create''' and note the generated password
# Your bot username will be: <code>YourWikiUsername@EphemeraAgent</code>

; XML Import permission
: The <code>importupload</code> right is typically restricted to sysops. To grant it to your bot group, add this to <code>LocalSettings.php</code>:
: <code>$wgGroupPermissions['bot']['importupload'] = true;</code>

== Step 3 — Open the Agent ==

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

== Step 4 — Log In ==

# Click the '''WIKI''' tab in the left sidebar
# Enter your bot username (e.g. <code>Admin@EphemeraAgent</code>) and bot password
# Click '''LOGIN'''
# The green badge in the header confirms success

== Step 5 — Enter an API Key ==

# The sidebar switches to the '''LLM''' tab after login
# Select your preferred AI provider
# Select a model
# Enter your API key, or load a [[Help:Ephemera Agent/Configuration#Keys File|keys file]]
# Type a task in the text area and press '''RUN''' or <kbd>Ctrl+Enter</kbd>

== 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 <code><script></code> 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 <code>WIKI_BASE_URL</code> 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 <code>api.php</code>.

=== Allowed Origins ===

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

== Common Issues ==

; Login fails
: Check that the bot username is in the form <code>User@BotName</code> and that the bot password was copied exactly.

; Proxy returns “Origin not allowed”
: Add your site to the allowed origins list in <code>proxy.php</code> and <code>llm-proxy.php</code>.

; 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 <code>importupload</code> right and that the right is enabled in <code>LocalSettings.php</code>.

[[Category:Help]]
[[Category:EphemeraAgent]]

Help:Ephemera Agent/Installation - Revision history

EphemeraAdmin: Import: Help:Ephemera Agent/Installation