GUI Walkthrough
This guide walks through every screen of the Discord Ferry web interface. Ferry runs a small local web server when you launch it — no data ever leaves your machine.
Launching the GUI
On Windows, double-click the downloaded Ferry-windows-x86_64.exe. On macOS, open Ferry.app (see Installation if macOS blocks it the first time). On Linux, run ferry-gui in a terminal.
The downloaded Windows and macOS apps draw their own window and do not launch a browser. A pipx install has no window toolkit bundled, so ferry-gui opens your browser instead.
Either way, http://localhost:8765 reaches the same interface while Ferry is running.
If the window cannot be drawn on your machine, Ferry says so in the window and opens your browser instead. Set FERRY_NO_NATIVE=1 to skip the window from the start. See Troubleshooting.
Setup Screen
The first screen collects the information Ferry needs before it can begin. Ferry has two modes — 1-Click Migration (default) and Offline mode.
1-Click Migration (default)
In this mode, Ferry downloads and runs DiscordChatExporter for you automatically.
Discord token — paste your Discord user token (masked input). Click "How to find these?" for step-by-step instructions.
Discord server ID — paste the server ID (right-click the server name in Discord > Copy Server ID).
ToS disclaimer — check the checkbox to acknowledge that using a user token may violate Discord's Terms of Service.
Stoat API URL — select Official (https://api.stoat.chat) or enter your self-hosted domain.
Stoat user token — paste the token you copied from your browser's developer tools (masked input). See how to find it. No bot or app creation needed — this is a key your browser already has.
Offline Mode ("I already have exports")
Toggle "I already have exports" to switch to offline mode. The Discord token and server ID fields are replaced with:
Export folder — paste or browse to your DiscordChatExporter export folder. The folder should contain one or more .json files and a media/ subfolder.
Media folder required
If you exported without the --media flag, attachments will not migrate. Re-export with --media before continuing.
Advanced Options
Click Advanced Options to expand the following settings. Defaults are safe for most migrations.
| Option | Default | Description |
|---|---|---|
| Rate limit (seconds) | 1.0 | Delay between messages. Range 0.5–3.0. Lower is faster but risks hitting Stoat's speed limit on how fast data can be sent. |
| Skip messages | Off | Import server structure only (channels, roles, categories). No messages will be sent. |
| Skip emoji | Off | Do not upload custom emoji. |
| Skip reactions | Off | Do not add message reactions. |
| Skip threads | Off | Do not migrate threads or forum posts. Useful when approaching the 200-channel limit. |
| Thread strategy | Flatten | How to handle threads and forum posts. Flatten (default) creates a dedicated channel for each thread. Merge appends thread messages into the parent channel. Archive exports the thread as a markdown attachment in the parent channel. |
| Dry run | Off | Run all migration phases without actually contacting the Stoat server. Useful for validating your export before committing to a full migration. |
| Existing server ID | (empty) | Paste a Stoat server ID to migrate into a server you have already created, rather than creating a new one. |
| Server name | (empty) | Name for the new Stoat server. Defaults to the Discord server's name. |
Below these, three labelled groups hold the tuning settings (since v2.7.0):
Speed
| Option | Default | Description |
|---|---|---|
| Concurrent channels | 3 | Channels migrated in parallel. Raise only on self-hosted instances — the GUI warns if you raise it while targeting the official service. |
| Concurrent API requests | 5 | Total concurrent API calls across all channel workers. Same self-hosted caveat. |
Content
| Option | Default | Description |
|---|---|---|
| Reaction mode | Text | Text appends a reaction summary to each message (fast). Native adds per-emoji reactions via the API (slow, Stoat caps 20 per message). Skip drops reactions. |
| Min thread messages | 0 | Exclude threads with fewer messages than this (0 = include all). Useful for servers with hundreds of low-activity threads. |
| Skip avatar pre-flight | Off | Skip the avatar batch-upload phase; avatars still upload on demand during messages. |
Safety
| Option | Default | Description |
|---|---|---|
| Checkpoint interval | 50 | How often migration state is saved (every N messages). Lower = safer but more disk I/O. |
| Validate after migration | Off | After migration, fetch the server and compare channel/role counts against expectations. |
Running into 'Too Many Requests' errors?
That error (code 429) means Stoat is asking Ferry to slow down. Increase the rate limit slider to 2.0 or 3.0 seconds. This slows the migration but eliminates the errors.
Continue Button
Click Continue when all required fields are filled. In 1-Click mode, Ferry moves to the Export screen. In offline mode, Ferry parses your export locally and moves to the Validate screen.
Validate Screen
Ferry has parsed your export and is showing you a summary before anything is sent to Stoat.
Source Server Info
The server name and export date from the DCE export appear at the top of the screen.
Counts Table
| Item | What it counts |
|---|---|
| Channels | Text, voice, and announcement channels |
| Categories | Channel categories (groupings) |
| Roles | Server roles |
| Messages | Total messages across all channels |
| Attachments | Files and images attached to messages |
| Custom emoji | Server-specific emoji |
| Threads | Forum posts and threaded conversations |
Warnings List
Any issues found during parsing are listed. Amber entries are informational. A red entry needs your acknowledgement before the migration can start. Common warnings:
- Mentions written as plain text (red). One entry per channel, carrying a count: those messages have mentions written as plain text instead of raw IDs, so they will arrive as text, with no link back to the user. See Mentions written as plain text for what to do about it.
- Attachment files missing — one or more attachment files were not found locally. Those files will be skipped.
- Channel limit may be exceeded — the combined channel and thread count exceeds 200.
- Emoji limit will be reached — the server has more than 100 custom emoji. Only the first 100 will be migrated.
Warnings and acknowledgement
Amber warnings need no action, and the migration proceeds with them. When the mentions warning is present, its full explanation appears above the buttons alongside a checkbox, I understand, migrate anyway. Ticking that box is the only thing that enables Start Migration. The tick does not persist: press Back and return to this screen, and the box is clear again.
A hard failure such as "No valid DCE JSON files found" stops the screen before the status is drawn, so it never appears as a colour here.
ETA Estimate
Based on your message count and the rate limit you chose, Ferry shows an estimated duration. Long migrations should be left to run overnight.
Overall Status
- Green, "Export looks good". No warnings were found.
- Amber, "Warnings present, review before migrating". Read the warnings above, then proceed.
- Red, "Acknowledgement needed before migrating". Tick I understand, migrate anyway to enable Start Migration. Red on this screen means acknowledgement is needed and nothing else.
Use the Back button to return to the Setup screen and adjust settings, or click Start Migration to begin.
Export Screen (1-Click Mode Only)
This screen appears only when you use 1-Click Migration. Ferry downloads and runs DiscordChatExporter automatically.
What Happens
Ferry runs through three steps automatically:
- Token validation — confirms your Discord token works via the Discord API.
- DCE download — if DiscordChatExporter is not cached locally, Ferry downloads the correct version for your operating system.
- Channel export — DCE exports all channels, threads, and media from your Discord server. Progress is shown per-channel.
Cached Exports
If Ferry detects cached export files from a previous run, it shows a summary (file count and total size) and offers two choices:
- Use Cached — skip re-exporting and go straight to validation.
- Re-export — discard cached files and export fresh.
This is useful when resuming after a crash or when you want to re-run the migration without re-downloading everything.
.NET Runtime
DCE requires the .NET 8 runtime on macOS and Linux. If Ferry detects it is missing, it shows an error with a download link. Windows users are not affected — the Windows DCE build is self-contained.
When the export completes, Ferry automatically moves to the Validate screen.
Review Dialog
Before creating anything on Stoat, Ferry shows a confirmation dialog summarising what will be created.
What It Shows
The dialog displays a summary table:
| Item | Description |
|---|---|
| Roles | Number of roles to create (excluding @everyone) |
| Categories | Number of channel categories |
| Channels | Number of text and voice channels |
| Custom emoji | Number of emoji to upload |
| Messages | Total messages to migrate |
| Threads | Number of threads/forum posts |
Warnings
If potential issues are detected, they appear below the summary:
- No Discord token provided — permissions and NSFW flags will not be migrated (these require the Discord API)
- Channel limit may be exceeded — combined channel and thread count is close to or over 200
- Emoji limit may be exceeded — more than 100 custom emoji detected
Actions
- Proceed — start creating the server on Stoat
- Cancel — return to the Validate screen without creating anything
Why review before creating?
Server creation on Stoat is not easily undone. The review step lets you verify the scope of the migration before Ferry contacts the Stoat server. This is especially useful for large servers where mistakes are costly.
Migrate Screen
The main migration screen. Ferry works through 12 sequential phases.
Phase Indicator
The 12 phases are shown in order, with a checkmark as each completes:
- Export — run DiscordChatExporter (skipped in offline mode)
- Validate — confirm export is readable
- Connect — verify Stoat credentials
- Server — create or connect to the target server
- Roles — create all server roles, then apply Discord permissions (translated to Stoat equivalents)
- Categories — create channel categories
- Channels — create all channels with NSFW flags, then apply per-channel permission overrides
- Emoji — upload custom emoji
- Messages — send all messages
- Reactions — add message reactions
- Pins — pin messages
- Report — write summary report with post-migration checklist
Progress Bar
During the Messages phase, a per-channel progress bar shows how many messages have been sent in the current channel and how many remain. In v2.0.0+, up to 3 channels are processed concurrently by default — the progress bar reflects the active channel workers simultaneously.
Running Totals
A live counter in the top-right area shows:
- Messages sent — total messages delivered to Stoat
- Attachments uploaded — files successfully uploaded to Stoat's file storage
- Errors — messages or items that could not be migrated
- Warnings — non-fatal issues logged
Live Log Stream
The lower half of the screen shows a scrolling log of activity. The log auto-scrolls to the latest entry. You can scroll up to review earlier entries.
ETA Countdown
A live estimate of time remaining updates as messages are sent.
Pause / Resume
Click Pause to temporarily stop the migration after the current message finishes. Click Resume to continue. Pausing is useful if you need to reduce load on your machine temporarily.
Cancel
Click Cancel to stop the migration entirely. Ferry saves its state to disk before stopping. To continue later, re-launch Ferry with the same export folder. On the Migrate screen, Ferry will detect the previous migration state and offer a Resume or Start Fresh choice (or use --resume on the CLI).
Do not close the browser tab during migration
Closing the tab while migration is running does not stop Ferry — it continues in the background. However, you will lose visibility into progress. Leave the tab open, or use the CLI if you need a more robust background process.
Completion Screen
When all phases finish, the Completion screen shows a card with the error count and — when a Discord token was used — a native-fidelity line showing how many slowmode settings, voice user limits, and role icons were applied.
For the full statistics (message counts, attachments, and the fidelity score — a 0–100 measure of migration quality), click Open Report. Two report files are saved to the ferry-output/ folder:
migration_report.md— a human-readable summary you can share with your communitymigration_report.json— a machine-readable report with full error details and ID mappings
Rollback this migration
If you want to undo the migration, click Rollback this migration. Ferry shows a confirmation dialog with the counts of channels, roles, custom emoji, and Ferry-owned categories it will delete from the Stoat target server. Any untracked Ferry-suspect channels — channels present on the Stoat server but missing from Ferry's state file, likely orphans from a previous crashed migration — are listed separately so you can opt in to each one individually before proceeding.
Rollback is idempotent — if it's interrupted, just click the button again and it picks up where it left off. The migration's state.json and entity maps are preserved as a forensic audit trail; deletions are tracked in a separate rollback_progress.rolled_back_ids field.
What rollback does not delete
Uploaded attachments, avatars, and emoji images remain on Stoat's Autumn file store — Autumn has no public DELETE endpoint. The rollback summary reports the orphan count. The Stoat server itself is never deleted; rollback only removes what Ferry created inside it.
The same operation is available on the CLI as ferry rollback --output-dir <path> — see the CLI reference for full options.