IvoryValley

Status: Under Heavy Development - This project is in early development. APIs and features may change without notice.

A transparent deduplication proxy for Mastodon and the Fediverse.

The Problem

Following users across multiple Fediverse accounts often results in seeing the same posts repeatedly due to boosts/reposts. Your timeline can show the same content 10+ times.

The Solution

IvoryValley sits between your Mastodon client and the upstream server, filtering out duplicate posts before they reach you. It tracks seen post URIs and removes duplicates from timeline responses.

┌─────────────┐     ┌─────────────────┐     ┌──────────────┐
│   Client    │────▶│   IvoryValley   │────▶│   Mastodon   │
│  (Tusky,    │◀────│                 │◀────│   Instance   │
│   etc.)     │     │  - Filter dupes │     │              │
└─────────────┘     │  - Store URIs   │     └──────────────┘
                    │  - Pass auth    │
                    └─────────────────┘

Features

• Transparent proxying - Works with any Mastodon-compatible client
• Deduplication - Filters duplicate posts and boosts from timelines
• WebSocket streaming - Real-time filtering for streaming connections
• OAuth passthrough - No credential handling, tokens are forwarded directly
• SQLite storage - Lightweight local database for tracking seen URIs
• Configurable - CLI args, environment variables, or config file

Installation

From Source

git clone https://github.com/your-username/ivoryvalley.git
cd ivoryvalley
cargo build --release

The binary will be at target/release/ivoryvalley.

Usage

# Basic usage
ivoryvalley --upstream https://mastodon.social

# With custom port
ivoryvalley --upstream https://mastodon.social --port 8080

# With environment variables
IVORYVALLEY_UPSTREAM=https://mastodon.social ivoryvalley

Then configure your Mastodon client to use http://localhost:8080 (or your chosen port) as the server URL instead of your actual instance.

Configuration

IvoryValley supports configuration via:

1. CLI arguments (highest priority)
2. Environment variables (prefixed with IVORYVALLEY_)
3. Config file (ivoryvalley.toml)

Options

How It Works

1. Client sends request to IvoryValley
2. IvoryValley forwards request to upstream Mastodon instance
3. For timeline endpoints, IvoryValley:
   • Extracts post URIs (globally unique across federation)
   • Checks each URI against the seen-URI database
   • Filters out duplicates
   • Records new URIs as seen
4. Returns filtered response to client

Development

This project uses just as a command runner. Install with cargo install just.

# List all available commands
just

# Run the proxy in development mode
just dev

# Run all tests
just test

# Run all quality checks before committing
just check

Testing with Mastodon Clients

Most Mastodon clients require HTTPS for OAuth. Use the built-in HTTPS proxy:

# Start proxy with HTTPS (available at https://localhost:8443)
just dev-https

This uses a Python HTTPS reverse proxy with a self-signed certificate. You'll need to accept the certificate warning in your client.

Then configure your Mastodon client to use https://localhost:8443 as the server.

Compatible clients:

Manual Commands

# Run with logging
RUST_LOG=ivoryvalley=debug cargo run -- --upstream-url https://mastodon.social

# Check code quality
cargo clippy --all-features -- -D warnings

# Format code
cargo fmt

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT