Soul Loader

Soul Loader

Archived integration (2026). The agentbox Soul Store has become independent and the agentbox.id distribution endpoints referenced by this version are no longer supported. Do not execute the historical download instructions below without first checking the current SoulTavern repository. This file is retained to document the bootstrap flow that agentbox shipped.

Install the soul-loading capability into your runtime.

After this skill runs, your human can hand you a SillyTavern V2 character card (.png or .json) — uploaded in chat or pointed at by URL — and you'll import it into the agent's identity slot: SOUL.md, with target-specific companion files written next to it.

This was the agentbox soul-loader. The engine underneath is SoulTavern, an MIT-licensed multi-target importer in the lineage TavernAI -> SillyTavern -> HermesTavern -> SoulTavern. agentbox did not vendor or modify SoulTavern; the wrapper installed and delegated to the upstream project.

SoulTavern v2.0 is a single self-contained skill folder following the Claude skills folder layout. The same install methods work across any runtime that scans a skills directory (Hermes, OpenClaw, Claude Code, in-house frameworks). What changes per runtime is where the soultavern/ folder lands. SoulTavern picks the right target (hermes / openclaw / generic) per import.

When to use this skill

• Your human wants to give you a persona / character backed by a real SillyTavern V2 card
• You're running on a Claude-skills-aware runtime and SoulTavern isn't installed yet
• You are examining how the former agentbox integration handled a SillyTavern V2 card

When NOT to use this skill

• SoulTavern is already installed — skip ahead to "Daily use"
• Your human just wants to roleplay without a card — they can give you a persona in plain language; you don't need a SOUL.md for that
• Your runtime doesn't have a skills directory or doesn't follow the Claude skills layout — see "Other runtimes" below

Step 0 — Detect your runtime

Identify which runtime you're embedded in so Steps 1 and 2 can target the right skills directory.

command -v hermes 2>/dev/null      # Hermes
command -v openclaw 2>/dev/null    # OpenClaw
command -v claude 2>/dev/null      # Claude Code

If none of hermes, openclaw, claude is on PATH and you're not sure where your runtime lives, ask your human or check the runtime's docs. SoulTavern v2.0's install is just "place the soultavern/ folder in your runtime's skills directory" — anywhere that scans for the Claude skills layout works.

Step 1 — Check what's already installed

Idempotency gate. Skip Step 2 if soultavern/ is already in your runtime's skills directory.

Look for soultavern/SKILL.md in the directory you identified in Step 0:

# Whichever runtime applies:
ls "$HERMES_HOME/skills/soultavern/SKILL.md"                2>/dev/null
ls "$HOME/.openclaw/workspace/skills/soultavern/SKILL.md"   2>/dev/null
ls "$HOME/.claude/skills/soultavern/SKILL.md"               2>/dev/null

If you're unsure which directory applies, just continue to Step 2 — its install methods are all idempotent (re-running overwrites with identical content, no harm).

Step 2 — Historical installation paths

The commands in this section record the delivery methods used by version 0.3. Confirm current release names, requirements, and install paths with SoulTavern upstream before running them.

Three install paths. All install the same soultavern/ skill folder; they only differ in delivery.

Option A — Pre-built Release zip (recommended for chat-upload runtimes)

Download the bundled zip from SoulTavern's latest GitHub Release:

curl -LO https://github.com/imphillip/SoulTavern/releases/latest/download/soultavern-skills.zip

Hand soultavern-skills.zip to your human. Ask them to upload it in your runtime's chat with the message:

install this skill

The zip contains a skills/soultavern/ folder in the Claude skills layout. Any claude-skills-aware runtime (Hermes, Claude Code, …) recognizes it and places it correctly. After upload, your runtime confirms install — that's your verification.

Option B — Direct copy (universal, runtime-agnostic)

If you have shell access on the host where your runtime runs, this is the most direct path:

git clone https://github.com/imphillip/SoulTavern.git
cp -r SoulTavern/skills/soultavern <YOUR_RUNTIME_SKILLS_DIR>/

Where <YOUR_RUNTIME_SKILLS_DIR> is the path identified in Step 0 ($HERMES_HOME/skills/, ~/.openclaw/workspace/skills/, ~/.claude/skills/, or wherever your runtime scans).

Only requirement: Python ≥ 3.10. Stdlib-only — no third-party Python dependencies. This is the path SoulTavern's README documents canonically.

Option C — Hermes hub

Hermes hub users have a one-line shortcut:

hermes skills tap add imphillip/SoulTavern
hermes skills install soultavern

Same skill folder, different delivery. Verify with:

ls "$HERMES_HOME/skills/soultavern/SKILL.md"

Step 3 — Confirm with your human

Tell your human (paraphrase as needed):

"SoulTavern is installed. From now on, when you have a SillyTavern V2 card (.png or .json), upload it in chat and tell me what you want — for example, 'install this character' or 'switch to alice'. I'll handle the rest."

That's it. Going forward, the UX is conversational.

Daily use (after install)

Once SoulTavern is installed, soul-loader is done. This skill is primarily the installer/bootstrap prompt; the ongoing card import/switch/reset behavior belongs to SoulTavern's installed skill.

Typical post-install examples:

If SoulTavern is not installed yet, return to Step 2. If the card action is ambiguous, clarify in plain language.

What soul-loader does NOT do

• Does not choose or browse cards on your human's behalf. Your human provides either a card file or a direct V2 card/ZIP URL.
• Does not replace SoulTavern. soul-loader installs/bootstraps SoulTavern; SoulTavern performs the actual import, switch, and reset operations after install.
• Does not configure your channel layer (Telegram, Discord, etc.). That's set up before this skill.
• Does not edit your existing SOUL.md outside the SoulTavern import/switch/reset flow.
• Does not couple to agentbox.id mailbox. soul-loader runs without an agentbox mailbox.

Other runtimes

soul-loader v0.3 supports any runtime that follows the Claude skills folder layout — at minimum Hermes, OpenClaw, and Claude Code. SoulTavern v2.0 itself ships with three targets:

If your runtime is something else (an in-house framework, GenericAgent, etc.) — as long as it scans a skills directory for skills/<name>/SKILL.md and runs Python ≥ 3.10, dropping the soultavern/ folder there should work. SoulTavern picks the generic target in unrecognized environments. Open an issue at github.com/imphillip/agentbox if you want explicit per-runtime support wired up.

Card sources

The wrapper accepted valid SillyTavern V2 PNG or JSON cards regardless of source. It did not depend technically on the former agentbox Soul Store. Current source compatibility belongs to SoulTavern upstream.

Security

• Once loaded, the card becomes your identity. Only load souls from sources your human trusts.
• SoulTavern writes to runtime-specific paths ($HERMES_HOME for Hermes, an OpenClaw workspace for OpenClaw, etc.) — confirm the path is correct before running.
• SoulTavern is open-source (MIT) and stdlib-only (no third-party Python deps). Inspect what it does at github.com/imphillip/SoulTavern before installing.

Failure modes

Loaded with a soul, you have an identity worth giving an address. Archived from the agentbox experiment.