Hubfly spaceDocs
Console

hubfly realtime

hubfly realtime creates and operates Realtime servers: dedicated WebSocket servers that speak the Pusher Channels protocol (version 7) with Hubfly space extensions and built-in end-to-end encryption. It covers servers, apps and keys, binding an app's credentials to a Cell project, publishing events, live inspection, webhooks and channel history. hubfly rt is an alias.

Basics

  • <server> is a Realtime server id or name. When two managed projects use the same name, add --project <id|name>.
  • A server holds one or more apps, each with its own keys and settings. <app> is an app id or name; you can leave out --app when the server has one app.
  • Hubfly space chooses where Realtime servers run, so there is no --region flag. Sizes are nano, small, medium, large and xlarge, or a custom --cpu and --memory (at least 512 MiB).
  • Commands that print data accept --json. App secrets are printed only by keys create, keys reveal and commands run with --reveal.
  • Event data is sent as text. Run hubfly realtime help for the full usage text.

terminal

$ hubfly rt create chat --size nano --project new
$ hubfly rt bind chat --to web --client-prefix NEXT_PUBLIC_
$ hubfly rt publish chat --channel orders --event order.updated --data '{"id":42}'
$ hubfly rt tail chat

Servers

usage
hubfly realtime list [--project <id|name>] [--json]
hubfly realtime info <server> [--json]
hubfly realtime create [<name>] [--size <preset>|--cpu <n> --memory <mib>] [--storage <gib>]
                       [--project <id|name|new>] [--app <name>] [--yes] [--no-wait] [--json]
hubfly realtime delete <server> [--yes] [--wait]
CommandWhat it does
rt listRealtime servers in your managed projects with status, size, monthly price, project and id.
rt infoStatus, size, price and hostname (a *.rt.hubfly.app name) of one server.
rt createQuotes the monthly price, asks you to confirm, creates the server and waits until it is ready. --project new creates a managed project for it. --app names the first app (default production). Storage defaults to 1 GiB and holds channel history and webhook queues.
rt deleteDeletes the server after you type its name (or pass --yes). Deletion protection must be off. It removes its app bindings and revokes its keys. --wait follows the deletion until it finishes.

terminal

# Quote, confirm and wait
$ hubfly rt create chat --size small --project new
# From a script, in an existing managed project
$ hubfly rt create chat --size small --project my-managed --app web --yes

Lifecycle And Network

usage
hubfly realtime start|stop|restart <server> [--no-wait] [--json]
hubfly realtime resize <server> [--size <preset>|--cpu <n> --memory <mib>] [--storage <gib>] [--yes] [--no-wait] [--json]
hubfly realtime upgrade <server> [--yes] [--no-wait]
hubfly realtime rename <server> <new-name>
hubfly realtime protect <server> on|off
hubfly realtime network <server> [--json]
hubfly realtime network allow <server> (<cidr>|--my-ip) [--label <text>]
hubfly realtime network remove <server> <cidr>
hubfly realtime logs <server> [--tail <bytes>] [--follow]
hubfly realtime metrics <server> [--window <duration>] [--json]
hubfly realtime operations <server> [--limit <n>] [--json]
CommandWhat it does
rt restartHands connections over in place to a new server process in a few seconds. Clients reconnect at once without refused connections, and @hubfly/realtime clients keep their connection id and receive the messages they missed.
rt stop, startStopping drains the server: clients are told to reconnect and are disconnected, and history and queued webhooks are saved. A stopped server pays for storage only.
rt resizeQuotes the old and new monthly price and asks you to confirm. Resizing applies live and does not restart the server. Storage can only grow.
rt upgradeApplies an available server update after you confirm. Clients are drained and the server is unavailable for about 10–20 seconds; clients reconnect on their own.
rt rename, protectChange the display name (the hostname stays) or turn deletion protection on or off.
rt networkShows and edits the IP allowlist (up to 64 entries). The allowlist guards the server's HTTP API, which your backend uses to publish; WebSocket clients are never IP-restricted.
rt logs, metrics, operationsServer logs (--follow to keep printing), resource metrics over a window such as 1h, and recent operations with their status.

Apps And Keys

usage
hubfly realtime apps [list] <server> [--json]
hubfly realtime apps create <server> <name> [settings] [--reveal] [--json]
hubfly realtime apps update <server> <app> [--name <name>] [--enable|--disable] [settings] [--json]
hubfly realtime apps delete <server> <app> [--yes]
hubfly realtime keys list <server> [--app <app>] [--json]
hubfly realtime keys create <server> [--app <app>] [--json]
                            (prints the new secret once; with --json it is in "secret")
hubfly realtime keys rotate <server> [<key>] [--app <app>] [--grace <duration>] [--reveal] [--yes] [--json]
hubfly realtime keys revoke <server> <key> [--app <app>] [--yes] [--json]
hubfly realtime keys reveal <server> [<key>] [--app <app>] [--json]

App settings (apps create/update):
  --origins <a,b> --client-events[=false] --subscription-count[=false] --require-auth[=false]
  --encryption off|optional|required --history off|memory|durable --history-ttl <duration>
  --history-max <n> --offline-queue[=false] --max-connections <n> --max-message-bytes <n>
  --payload-preview[=false]

An app is what Pusher clients call an app: an app id, a key that clients use to connect and a secret that your backend uses to sign requests. A server can hold up to 100 apps and an app up to 10 keys.

SettingMeaning
--originsBrowser origins allowed to connect, such as https://app.example.com (up to 50). Empty allows any origin.
--client-eventsAllow clients to send client-* events on private and presence channels.
--subscription-countSend pusher:subscription_count events to subscribers.
--require-authRequire every client to sign in as a user (pusher:signin) within 30 seconds of connecting; otherwise the connection is closed.
--encryptionEnd-to-end encryption: off, optional or required.
--history, --history-ttl, --history-maxKeep recent channel messages in memory or on disk (durable) so clients can catch up: for up to 24 hours and 1,000 messages per channel.
--offline-queueQueue direct messages for a user who is offline and deliver them when they reconnect.
--max-connections, --max-message-bytesPer-app caps on concurrent connections and message size.
--payload-previewLet the live inspector (rt tail --preview) show the start of message payloads. Encrypted payloads are never readable.
CommandWhat it does
keys createAdds a key to the app and prints its secret once, with a warning on standard error (in "secret" with --json).
keys rotateCreates a new key and keeps the old one working for a grace period: 24 hours by default, or --grace up to 30 days. --grace 0 revokes the old key at once and asks you to confirm. App bindings that used the old key receive the new one.
keys revokeRevokes a key after you confirm; clients and servers that use it are refused.
keys revealShows a key's secret again. Reveals are recorded in the activity log.

terminal

$ hubfly rt apps create chat staging --origins https://staging.example.com --encryption required
$ hubfly rt apps update chat staging --client-events --history durable --history-ttl 1h
$ hubfly rt keys rotate chat --app staging --grace 24h

Bind And Environment

usage
hubfly realtime bind <server> --to <project> [--app <app>] [--preset hubfly|laravel]
                     [--client-prefix none|NEXT_PUBLIC_|VITE_|PUBLIC_] [--key <key>] [--json]
hubfly realtime bind list <server> [--json]
hubfly realtime bind remove <server> <bindingId> [--keep-variables] [--yes]
hubfly realtime env <server> [--app <app>] [--preset hubfly|laravel] [--client-prefix <prefix>]
                    [--key <key>] [--format dotenv|json] [--reveal]

rt bind writes an app's credentials into a Cell project's environment, with the secret stored as a secret variable; redeploy or restart the project's containers to load them. rt env prints the same variables for a .env file, leaving out the secret unless you pass --reveal.

PresetVariables
hubfly (default)HUBFLY_REALTIME_URL, HUBFLY_REALTIME_APP_ID, HUBFLY_REALTIME_KEY, HUBFLY_REALTIME_SECRET. With --client-prefix, also browser copies of the URL and key, such as NEXT_PUBLIC_HUBFLY_REALTIME_URL and NEXT_PUBLIC_HUBFLY_REALTIME_KEY. The secret never gets a client copy.
laravelBROADCAST_CONNECTION=pusher, PUSHER_APP_ID, PUSHER_APP_KEY, PUSHER_APP_SECRET, PUSHER_HOST, PUSHER_PORT=443, PUSHER_SCHEME=https, PUSHER_APP_CLUSTER=mt1 and the matching VITE_PUSHER_* variables for Laravel Echo.

HUBFLY_REALTIME_E2E_KEYS is never written by Hubfly space: you set it yourself (see end-to-end keys).

terminal

$ hubfly rt bind chat --to web --client-prefix VITE_
$ hubfly rt bind chat --to shop --preset laravel
$ hubfly rt env chat --app staging --format dotenv --reveal >> .env

Publish And Send

usage
hubfly realtime publish <server> --channel <name>... --event <name> [--data <text>|--data-file <path|->]
                        [--app <app>] [--exclude <socketId>] [--message-id <id>] [--json]
hubfly realtime send <server> (--connection <id>...|--user <id>) --event <name>
                     [--data <text>|--data-file <path|->] [--app <app>] [--strip-key] [--json]
  • rt publish triggers an event on one or more channels through the server API, as your backend would. Data comes from --data, --data-file (- for standard input) or piped input. --exclude skips one connection; --message-id sets an id that makes retries safe to repeat. The short form hubfly rt publish <server> <channel> <event> [<data>] also works.
  • rt send sends a direct message to specific connections or to every connection of a user.
  • End-to-end connection ids (<socket_id>~<key>) carry a client key that must never reach Hubfly space. The CLI removes the key before any request and refuses to send plaintext to such a connection; encrypt the message on your own server with the Hubfly space server SDK, or pass --strip-key to send it unencrypted.

terminal

$ hubfly rt publish chat --channel orders --event order.updated --data '{"id":42}'
$ echo '{"id":42}' | hubfly rt publish chat orders order.updated
$ hubfly rt send chat --user u_42 --event notice --data-file ./notice.json

Inspect And Debug

usage
hubfly realtime tail <server> [--app <app>...] [--family conn,sub,member,msg,api,err,webhook]
                     [--channel-prefix <prefix>] [--preview] [--json]
hubfly realtime insights <server> [--app <app>] [--window <duration>] [--json]
hubfly realtime channels <server> [--app <app>] [--prefix <prefix>] [--limit <n>] [--json]
hubfly realtime channels inspect <server> <channel> [--app <app>] [--members <n>] [--json]
hubfly realtime history <server> --channel <name> [--app <app>] [--limit <n>] [--json]
hubfly realtime history purge <server> [--channel <name>] [--app <app>] [--yes]
hubfly realtime connections <server> [--app <app>] [--user <id>] [--channel <name>] [--limit <n>] [--json]
hubfly realtime disconnect <server> (--connection <socketId>...|--user <id>) [--app <app>] [--mode terminate|disconnect] [--yes]
hubfly realtime usage <server> [--app <app>] [--since <duration|YYYY-MM-DD>] [--json]
CommandWhat it does
rt tailOpens the live inspector and prints one line per event (--json for JSON lines): connections, subscriptions, presence members, messages, server API calls, errors and webhooks. Filter by family and channel prefix; --preview shows the start of payloads when the app allows it. Sampling and dropped events are noted on standard error. Press Ctrl-C to stop.
rt insightsPeak connections, top channels and events, failure reasons, client libraries and webhook success rate over a window such as 6h.
rt channelsOccupied channels with their subscriber counts; inspect shows one channel and its presence members.
rt historyStored messages of a channel, for apps with history on. purge deletes the history of one channel, or of every channel in the app, after you confirm.
rt connectionsOpen connections, filtered by app, user or channel.
rt disconnectCloses connections or all connections of a user after you confirm. By default the client is told not to reconnect; for single connections, --mode disconnect lets the client reconnect.
rt usageDaily peak connections, connection minutes, messages and bytes in and out, and webhook deliveries, by default for the last 30 days.

terminal

$ hubfly rt tail chat --family msg,conn --channel-prefix orders
$ hubfly rt tail chat --json | jq .
$ hubfly rt channels inspect chat presence-room-1 --members 20
$ hubfly rt disconnect chat --user u_42

Webhooks

usage
hubfly realtime webhooks [list] <server> [--app <app>] [--json]
hubfly realtime webhooks create <server> --url <https-url> --events <a,b> [--key <key>] [--disabled] [--app <app>] [--json]
hubfly realtime webhooks update <server> <webhook> [--url <url>] [--events <a,b>] [--key <key>] [--enable|--disable] [--app <app>] [--json]
hubfly realtime webhooks delete <server> <webhook> [--app <app>] [--yes]
hubfly realtime webhooks test <server> <webhook> [--app <app>] [--json]
hubfly realtime webhooks deliveries <server> [--webhook <webhook>] [--status <status>] [--limit <n>] [--app <app>] [--json]
hubfly realtime webhooks redeliver <server> <deliveryId> [--app <app>] [--json]
  • Webhook URLs must use https://. An app can have up to 10 webhooks.
  • Events: channel_occupied, channel_vacated, member_added, member_removed, client_event, cache_miss, subscription_count, and the Hubfly space events hubfly.connection_opened, hubfly.connection_closed, hubfly.user_online, hubfly.user_offline and hubfly.message_delivered.
  • Requests are signed with an app key: the app's newest key unless you choose one with --key. They carry the Pusher headers X-Pusher-Key and X-Pusher-Signature and a Hubfly space X-Hubfly space-Signature with a timestamp.
  • test sends a test request and prints the response status; it is not recorded as a delivery. deliveries lists recent deliveries (statuses pending, delivered, failed, dead) and redeliver queues one again.

terminal

$ hubfly rt webhooks create chat --url https://api.example.com/hooks/realtime --events member_added,member_removed
$ hubfly rt webhooks deliveries chat --status failed

End-To-End Keys

usage
hubfly realtime keygen [--kid <kid>]

rt keygen generates an end-to-end master key on your machine (32 random bytes, base64; kid:base64 with --kid) and sends it nowhere. Put it first in HUBFLY_REALTIME_E2E_KEYS on your own servers: a comma-separated list of kid:base64 entries in which the first entry encrypts and the others still decrypt, so you can rotate without breaking older messages. Hubfly space never stores or sees these keys.

terminal

$ hubfly rt keygen --kid k2

Scripting And Secrets

  • JSON output. With --json, standard output carries only JSON; prompts and progress go to standard error.
  • Confirmations. Creating, resizing, deleting, revoking, purging and disconnecting ask first. Without a terminal they stop with confirmation required; re-run with --yes; pass --yes once you have reviewed the change.
  • Secrets. App secrets appear only in keys create, keys reveal (audited) and with --reveal on apps create, keys rotate and env. --debug never prints secrets or tokens.
  • Waiting. Long operations show progress and wait; --no-wait returns as soon as Hubfly space has accepted the request. Follow it later with hubfly rt operations.
  • Exit codes. Non-zero on failure, with distinct codes for usage errors, authentication, conflicts and timeouts. See exit codes.

Pusher clients need only the host and key

Existing pusher-js, Laravel Echo and Pusher server SDK code connects after you change the host to your server's hostname (port 443, TLS) and use the app id, key and secret from rt env. See the Realtime protocol reference for what is compatible.
Something unclear or out of date? Emailsupport@hubfly.spaceBack to top