WebSocket (Jetstream / Firehose)

Overview

laravel-bluesky provides two WebSocket commands for connecting to Bluesky’s real-time streams.

Jetstream — Bluesky’s own pre-filtered WebSocket endpoint. Lightweight and JSON-encoded.
Firehose — the AT Protocol’s raw event stream. Receives every piece of data in DAG-CBOR binary form.

Long-running WebSocket processes require an always-on server such as a VPS or EC2 or a Laravel Cloud custom worker. They don’t work in serverless environments such as Laravel Vapor or Vercel.

Installation

The WebSocket features require Workerman.

composer require workerman/workerman

Jetstream

Overview

Jetstream is a pre-filtered WebSocket service provided by Bluesky. Because you can filter by collection type or user DID, you can efficiently receive only the events you need.

Feature	Description
Data format	JSON
Filtering	Filter by collection or DID
Data volume	Lightweight, depending on filters
Use case	Monitoring posts, likes, follows, and so on

Starting it

# Receive every message (no filter)
php artisan bluesky:ws start

# Debug: display every message received
php artisan bluesky:ws start -v

Collection filters

Use the -C option to narrow the collections you receive. You can specify multiple values.

# Receive only posts and likes
php artisan bluesky:ws start -C app.bsky.feed.post -C app.bsky.feed.like

# Receive only follows
php artisan bluesky:ws start -C app.bsky.graph.follow

Major collections:

Collection	Contents
`app.bsky.feed.post`	Post create/delete
`app.bsky.feed.like`	Likes
`app.bsky.feed.repost`	Reposts
`app.bsky.graph.follow`	Follows
`app.bsky.graph.block`	Blocks

DID filters

Use the -D option to receive events only for specific users.

# Receive posts only from specific users
php artisan bluesky:ws start -C app.bsky.feed.post -D did:plc:xxx -D did:plc:yyy

Event handling

The Jetstream command fires Laravel events based on the type of message received.

Event class	When it fires
`JetstreamMessageReceived`	On every received message
`JetstreamCommitMessage`	On record create, update, or delete
`JetstreamIdentityMessage`	On identity events such as handle changes
`JetstreamAccountMessage`	On account activation/deactivation

Create an event listener to handle events.

php artisan make:listener JetstreamPostListener

namespace App\Listeners;

use Revolution\Bluesky\Events\Jetstream\JetstreamCommitMessage;

class JetstreamPostListener
{
    public function handle(JetstreamCommitMessage $event): void
    {
        // Check the collection type
        $collection = data_get($event->message, 'commit.collection');

        if ($collection !== 'app.bsky.feed.post') {
            return;
        }

        // Operation: create / update / delete
        $operation = $event->operation;

        // The author's DID
        $did = $event->message['did'];

        // Record contents
        $record = data_get($event->message, 'commit.record');
        $text = data_get($record, 'text', '');

        info("[$operation] $did: $text");
    }
}

Firehose

Overview

Firehose is the AT Protocol’s raw event stream. You receive every record operation on the Bluesky network in binary (DAG-CBOR) form.

Feature	Description
Data format	DAG-CBOR binary (auto-decoded by the package)
Filtering	None (receive all data)
Data volume	Very high
Use case	Data collection and archival

The package decodes DAG-CBOR automatically. In your event listener, data arrives as regular PHP arrays.

Starting it

php artisan bluesky:firehose start

# Debug: display received messages
php artisan bluesky:firehose start -v

Event handling

The Firehose command also processes messages using Laravel events.

Event class	When it fires
`FirehoseMessageReceived`	On every received message (raw data included)
`FirehoseCommitMessage`	On record create, update, or delete
`FirehoseIdentityMessage`	On identity events
`FirehoseAccountMessage`	On account events
`FirehoseSyncMessage`	On repository sync events

php artisan make:listener FirehosePostListener

namespace App\Listeners;

use Revolution\Bluesky\Events\Firehose\FirehoseCommitMessage;

class FirehosePostListener
{
    public function handle(FirehoseCommitMessage $event): void
    {
        // Check the collection type
        if ($event->collection !== 'app.bsky.feed.post') {
            return;
        }

        // Operation: create / update / delete
        $action = $event->action;

        // The author's DID
        $did = $event->did;

        // Record contents (decoded array)
        $record = $event->record;
        $text = data_get($record, 'value.text', '');

        info("[$action] $did: $text");
    }
}

Configuration

You can change the target host and logging settings in config/bluesky.php.

// Jetstream
'jetstream' => [
    'host' => env('BLUESKY_JETSTREAM_HOST', 'jetstream1.us-west.bsky.network'),
    'max' => env('BLUESKY_JETSTREAM_MAX', 0), // maxMessageSizeBytes (0 = unlimited)
    'logging' => [
        'driver' => env('BLUESKY_JETSTREAM_LOG_DRIVER', 'daily'),
        'days' => 7,
        'path' => env('BLUESKY_JETSTREAM_LOG_PATH', storage_path('logs/jetstream.log')),
    ],
],

// Firehose
'firehose' => [
    'host' => env('BLUESKY_FIREHOSE_HOST', 'bsky.network'),
    'logging' => [
        'driver' => env('BLUESKY_FIREHOSE_LOG_DRIVER', 'daily'),
        'days' => 7,
        'path' => env('BLUESKY_FIREHOSE_LOG_PATH', storage_path('logs/firehose.log')),
    ],
],

Example .env values:

BLUESKY_JETSTREAM_HOST=jetstream2.us-east.bsky.network
BLUESKY_JETSTREAM_MAX=1000000

Combining with Labeler

You can start Jetstream or Firehose alongside a Labeler server. This lets the Labeler use Jetstream or Firehose data when processing labeling requests.

# Labeler + Jetstream (monitor follow events)
php artisan bluesky:labeler:server start --jetstream -C app.bsky.graph.follow

# Labeler + Firehose (receive all data)
php artisan bluesky:labeler:server start --firehose

For Labeler details, see the Labeler page.

Running long-running processes

WebSocket commands are long-running processes. In production, use a process manager like Supervisor.

Example Supervisor configuration

/etc/supervisor/conf.d/bluesky-jetstream.conf:

[program:bluesky-jetstream]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/html/artisan bluesky:ws start -C app.bsky.feed.post
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/html/storage/logs/jetstream-worker.log
stopwaitsecs=3600

# Reload Supervisor and start
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start bluesky-jetstream:*

Laravel Forge daemon configuration

If you use Laravel Forge, add a daemon under the Daemons section.

Command: php artisan bluesky:ws start -C app.bsky.feed.post
Directory: /var/www/html
User: forge

Background processes on Laravel Cloud

Because WebSocket commands connect to Bluesky’s stream as a WebSocket client, they also work on Laravel Cloud. Configure them as a Laravel Cloud background process (custom worker). Add a Custom Worker in your Laravel Cloud background process settings. For Jetstream:

php artisan bluesky:ws start

For Firehose:

php artisan bluesky:firehose start

Process stop and restart on deploy is handled automatically by Laravel Cloud. No extra configuration beyond the background process setup is required.

Notes

If a process exits unexpectedly, autorestart=true restarts it automatically.
To avoid memory leaks, consider periodic restarts.
For Firehose, which receives a large volume of messages, offload listener work to an async Queue Job.

// Example of dispatching to a Queue Job from a listener

namespace App\Listeners;

use App\Jobs\ProcessFirehosePost;
use Revolution\Bluesky\Events\Firehose\FirehoseCommitMessage;

class FirehosePostListener
{
    public function handle(FirehoseCommitMessage $event): void
    {
        if ($event->collection !== 'app.bsky.feed.post') {
            return;
        }

        // Delegate heavy work to a Queue Job
        ProcessFirehosePost::dispatch($event->did, $event->record, $event->action);
    }
}

Source: src/Console/WebSocket

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds and RSS

Middleware

Overview

Installation

Jetstream

Overview

Starting it

Collection filters

DID filters

Event handling

Firehose

Overview

Starting it

Event handling

Configuration

Combining with Labeler

Running long-running processes

Example Supervisor configuration

Laravel Forge daemon configuration

Background processes on Laravel Cloud

Notes

​Overview

​Installation

​Jetstream

​Overview

​Starting it

​Collection filters

​DID filters

​Event handling

​Firehose

​Overview

​Starting it

​Event handling

​Configuration

​Combining with Labeler

​Running long-running processes

​Example Supervisor configuration

​Laravel Forge daemon configuration

​Background processes on Laravel Cloud

​Notes

Overview

Installation

Jetstream

Overview

Starting it

Collection filters

DID filters

Event handling

Firehose

Overview

Starting it

Event handling

Configuration

Combining with Labeler

Running long-running processes

Example Supervisor configuration

Laravel Forge daemon configuration

Background processes on Laravel Cloud

Notes