CLI: `fedify relay` command

[dahlia]

Background

The @fedify/relay package (introduced in Fedify 2.0.0) provides ActivityPub relay implementations supporting both Mastodon and LitePub protocols. However, to test or experiment with a relay server, developers currently need to write boilerplate code to set up the server, configure tunneling for external access, and handle storage.

The existing fedify inbox command demonstrates how a CLI tool can simplify federation testing by providing an ephemeral server with automatic tunneling. A similar fedify relay command would lower the barrier for developers who want to:

• Test how their ActivityPub server interacts with relays
• Experiment with relay protocols before implementing their own relay
• Debug federation issues involving relay servers
• Quickly spin up a relay for local development environments

Proposed feature

Add a new fedify relay command that starts an ActivityPub relay server with sensible defaults for development and testing.

Usage

Start a Mastodon-compatible relay with in-memory storage and automatic tunneling:

fedify relay --protocol mastodon

Start a LitePub-compatible relay with persistent SQLite storage (followers survive restarts):

fedify relay --protocol litepub --persistent ./relay.db

Start a relay that accepts subscriptions from a specific domain:

fedify relay --protocol mastodon --accept-follow '*@mastodon.social'

Start a relay that auto-approves all subscription requests:

fedify relay --protocol mastodon --accept-follow '*'

Full example with all options:

fedify relay \
  --protocol mastodon \
  --port 8000 \
  --name "My Test Relay" \
  --persistent ./relay.db \
  --accept-follow '*@mastodon.social' \
  --accept-follow '*@fosstodon.org'

Options

Option	Short	Description	Default
--protocol <TYPE>	-p	Relay protocol: mastodon or litepub	(required)
--persistent <PATH>		SQLite database path for persistent storage	(in-memory)
--port <PORT>	-P	Local server port	8000
--name <NAME>	-n	Display name of the relay actor	"Fedify Relay"
--accept-follow <PATTERN>	-a	Auto-accept subscription requests matching pattern (can be specified multiple times; see fedify inbox)	(reject all)
--no-tunnel	-T	Disable tunneling (local access only)	false
--debug	-d	Enable debug logging	false

Implementation notes

• Tunneling via @hongminhee/localtunnel (consistent with fedify inbox)
• MemoryKvStore by default; SqliteKvStore when --persistent is specified
• Domain derived from tunnel URL automatically
• Consider adding a web UI to monitor connected followers and relayed activities
• Follow the --accept-follow pattern from fedify inbox for subscription approval

Related

• @fedify/relay package
• fedify inbox command (similar UX pattern)

[sij411]

Could you assign me on this?

[dahlia]

@sij411 Assigned, thanks!

[sij411]

I have got a question on --open option for relay, if it doesn't auto-approve the Follow request, how users pass the subscription approval logic via command line? I don't thinkOptique can take arrow function as user inputs.

[dahlia]

Good question! I think I didn't think through the --open option properly when I created this issue.

We should follow the same pattern as the fedify inbox command, which provides --follow and --accept-follow options.

For fedify relay, we could apply a similar approach:

Proposed options

1. --accept-follow <PATTERN> (can be specified multiple times):

   • Accept subscription requests from specific actors: --accept-follow @user@domain.com
   • Accept from all users on a domain: --accept-follow '*@domain.com' or --accept-follow '@*@domain.com'
   • Accept all requests: --accept-follow '*'
   • Default behavior (no option): reject all subscription requests

2. Remove --open (or make it an alias for --accept-follow '*')

Example usage

# Accept subscriptions from specific domain
fedify relay --protocol mastodon --accept-follow '*@mastodon.social'

# Accept subscriptions from multiple domains
fedify relay --protocol mastodon \
  --accept-follow '*@mastodon.social' \
  --accept-follow '*@fosstodon.org'

# Accept all subscriptions (open relay)
fedify relay --protocol mastodon --accept-follow '*'

# Accept no subscriptions (default, for testing)
fedify relay --protocol mastodon

This approach:

• Follows the established UX pattern from fedify inbox
• Doesn't require users to input functions via CLI
• Provides fine-grained control over which subscriptions to accept
• Keeps the simple “accept everything” use case with --accept-follow '*'

What do you think? Should I update the issue description accordingly?

[sij411]

Sounds good. It's clearer. I'd appreciate it if you do.

[dahlia]

I've updated the issue description to replace --open with --accept-follow <PATTERN> following the fedify inbox pattern. Thanks for the feedback!

[sij411]

As a block list, I think adding --reject-follow <PATTERN> is not a bad idea?