[Enhancement]: Add support for launch instance under a unix domain socket. #2478

New Issue

2026-04-25T00:07:33+02:00

adam commented

2026-04-25 00:07:33 +02:00

Originally created by @xVermillionx on GitHub (Jan 11, 2025).

Type of Enhancement

Server Backend

Describe the Feature/Enhancement

To have the possibility of running the server over a Unix socket connection for local communication on the filesystem.

Why would this be helpful?

Unix sockets are a little bit faster and reduce the need of opening ports on a system which is especially nice to use with a reverse proxy as the firewall won't need to be configured for the service.

Future Implementation (Screenshot)

Customization of the socket_path, socket_name and mode/permissions would be great, maybe via the process.env. variables.

Audiobookshelf Server Version

v2.17.1

Current Implementation (Screenshot)

No response

Originally created by @xVermillionx on GitHub (Jan 11, 2025). ### Type of Enhancement Server Backend ### Describe the Feature/Enhancement To have the possibility of running the server over a Unix socket connection for local communication on the filesystem. ### Why would this be helpful? Unix sockets are a little bit faster and reduce the need of opening ports on a system which is especially nice to use with a reverse proxy as the firewall won't need to be configured for the service. ### Future Implementation (Screenshot) Customization of the socket_path, socket_name and mode/permissions would be great, maybe via the process.env.<VAR> variables. ### Audiobookshelf Server Version v2.17.1 ### Current Implementation (Screenshot) _No response_

adam added the enhancement label 2026-04-25 00:07:33 +02:00

adam closed this issue

2026-04-25 00:07:33 +02:00

adam commented

2026-04-25 00:07:33 +02:00

@advplyr commented on GitHub (Jan 17, 2025):

I'm not familiar with this method. Are you able to edit the source of the server and connect via your method?

@advplyr commented on GitHub (Jan 17, 2025): I'm not familiar with this method. Are you able to edit the source of the server and connect via your method?

adam commented

2026-04-25 00:07:34 +02:00

@balki commented on GitHub (Feb 3, 2025):

+1 I would like this feature as well.

I don't have dev env setup for javascript/typescript, so can't test and send a PR. But I think the change is simple.

https://github.com/advplyr/audiobookshelf/blob/master/server/Server.js#L398-L401

In the above lines, Instead of this overload which accepts host and port(1), the one which accepts path to unix socket(2) has to be used.

this.server.listen(this.Port, this.Host, () => {

           listen(port?: number, hostname?: string, backlog?: number, listeningListener?: () => void): this;
(1) -->    listen(port?: number, hostname?: string, listeningListener?: () => void): this;                  
           listen(port?: number, backlog?: number, listeningListener?: () => void): this;                   
           listen(port?: number, listeningListener?: () => void): this;                                     
           listen(path: string, backlog?: number, listeningListener?: () => void): this;                    
(2) -->    listen(path: string, listeningListener?: () => void): this;

The path is a regular filesystem path e.g. /tmp/abs.sock that the user running audiobookshelf has permission to create.

There an be a new config/env variable UNIX_SOCKET_PATH, when non-empty, listens on unix socket instead of host:port. Or reuse HOST and PORT. e.g. if HOST==unix, then treat port as unix socket path. I think new config option is cleaner.

@balki commented on GitHub (Feb 3, 2025): +1 I would like this feature as well. I don't have dev env setup for javascript/typescript, so can't test and send a PR. But I think the change is simple. https://github.com/advplyr/audiobookshelf/blob/master/server/Server.js#L398-L401 In the above lines, Instead of this overload which accepts host and port(1), the one which accepts path to unix socket(2) has to be used. ```javascript this.server.listen(this.Port, this.Host, () => { ``` ```typescript listen(port?: number, hostname?: string, backlog?: number, listeningListener?: () => void): this; (1) --> listen(port?: number, hostname?: string, listeningListener?: () => void): this; listen(port?: number, backlog?: number, listeningListener?: () => void): this; listen(port?: number, listeningListener?: () => void): this; listen(path: string, backlog?: number, listeningListener?: () => void): this; (2) --> listen(path: string, listeningListener?: () => void): this; ``` The path is a regular filesystem path e.g. `/tmp/abs.sock` that the user running audiobookshelf has permission to create. There an be a new config/env variable `UNIX_SOCKET_PATH`, when non-empty, listens on unix socket instead of host:port. Or reuse `HOST` and `PORT`. e.g. if `HOST==unix`, then treat port as unix socket path. I think new config option is cleaner.

adam commented

2026-04-25 00:07:34 +02:00

@balki commented on GitHub (Feb 12, 2025):

@advplyr I got this working with below change.

❯ git diff master           
diff --git a/server/Server.js b/server/Server.js
index c3e73ae..115d170 100644
--- a/server/Server.js
+++ b/server/Server.js
@@ -395,10 +395,18 @@ class Server {
     })
     router.get('/healthcheck', (req, res) => res.sendStatus(200))
 
-    this.server.listen(this.Port, this.Host, () => {
-      if (this.Host) Logger.info(`Listening on http://${this.Host}:${this.Port}`)
-      else Logger.info(`Listening on port :${this.Port}`)
-    })
+    if(fs.pathExistsSync("/run/audiobookshelf")) {
+        const sockPath = "/run/audiobookshelf/web.sock"
+        this.server.listen(sockPath, () => {
+            fs.chmodSync(sockPath, 0o666);
+            Logger.info(`Listening on unix socket :${sockPath}`)
+        })
+    } else {
+        this.server.listen(this.Port, this.Host, () => {
+            if (this.Host) Logger.info(`Listening on http://${this.Host}:${this.Port}`)
+            else Logger.info(`Listening on port :${this.Port}`)
+        })
+    }
 
     // Start listening for socket connections
     SocketAuthority.initialize(this)

/run/audiobookshelf directory can be created by setting RuntimeDirectory=audiobookshelf in systemd service config. This should ideally be configurable.

Caddy reverse proxy config

reverse_proxy unix//run/audiobookshelf/web.sock

The main usecase for unix socket is to isolate the service in a different network namespace but still be able to receive requests from reverse proxy. E.g. PrivateNetwork=yes in systemd service or docker ... --network=none.

@balki commented on GitHub (Feb 12, 2025): @advplyr I got this working with below change. ```diff ❯ git diff master diff --git a/server/Server.js b/server/Server.js index c3e73ae..115d170 100644 --- a/server/Server.js +++ b/server/Server.js @@ -395,10 +395,18 @@ class Server { }) router.get('/healthcheck', (req, res) => res.sendStatus(200)) - this.server.listen(this.Port, this.Host, () => { - if (this.Host) Logger.info(`Listening on http://${this.Host}:${this.Port}`) - else Logger.info(`Listening on port :${this.Port}`) - }) + if(fs.pathExistsSync("/run/audiobookshelf")) { + const sockPath = "/run/audiobookshelf/web.sock" + this.server.listen(sockPath, () => { + fs.chmodSync(sockPath, 0o666); + Logger.info(`Listening on unix socket :${sockPath}`) + }) + } else { + this.server.listen(this.Port, this.Host, () => { + if (this.Host) Logger.info(`Listening on http://${this.Host}:${this.Port}`) + else Logger.info(`Listening on port :${this.Port}`) + }) + } // Start listening for socket connections SocketAuthority.initialize(this) ``` `/run/audiobookshelf` directory can be created by setting `RuntimeDirectory=audiobookshelf` in systemd service config. This should ideally be configurable. Caddy reverse proxy config ``` reverse_proxy unix//run/audiobookshelf/web.sock ``` --- The main usecase for unix socket is to isolate the service in a different network namespace but still be able to receive requests from reverse proxy. E.g. `PrivateNetwork=yes` in systemd service or `docker ... --network=none`.

adam commented

2026-04-25 00:07:34 +02:00

@github-actions[bot] commented on GitHub (May 17, 2025):

Fixed in v2.23.0.

@github-actions[bot] commented on GitHub (May 17, 2025): Fixed in [v2.23.0](https://github.com/advplyr/audiobookshelf/releases/tag/v2.23.0).

Sign in to join this conversation.

Branches Tags

master

book_tags_genres_dedupe

episode_download_fallback

Issue-4540-SortBy-StartedDate-and-FinishedDate

episode_meta_tagging

fix_authorize_race_condition

redirect_transcode_requests

progress_updated_sort

fix_ereader_socket_event

fix_change_empty_root_password

fix_podcast_session_track_index

fix_set_token

session_modal_user

localize_durations

fix_oidc_create_user

jwt_auth_refactor

fix_scanner_deleting_single_file_books

fix_mediaprogress_updatedat_2

experimental_next_client

podcast_episode_duration

episode-timestamps-clickable

book_author_secondary_sort_title

podcast_useragents

pathexists_user_access

fix_pathexists_join

book_author_secondary_sort

clean_duplicate_mediaprogress

sanitize_html_description

trix_prevent_attachments

check_path_api_fix

fix_mediaprogress_updatedat

increase_express_json_limit

fix_dockerfile_nunicode

search_episodes

audiobook_tools_update

episode_secondary_sorts

hls_stream_url_update

new_session_track_endpoint

audiobook_tools_enhancements

watcher_rescans_update

player_track_tooltip

fix_exclude_prefixes_crash

socket_item_events

fix_podcast_episode_scanner_promise

new_stats_controller

count_cache_for_userpermissions

parsing-opf-v3

validate_migration_files

fix-quick-match-all-crash

fix-chapter-end-sleep-timer

stringify_sequelize_query

remove-col-ambiguity

fix_next_prev_edit_description

details_trim_whitespace

fix_content_url_basepath

fix_logger_fatal

progress_bar_visibility

batch-edit-populate-map-details

feed_generator_updates

bookmark-modal-updates

migrate-library-item-in-scanner

migrate-new-library-items

migrate-podcasts-new-library-item-2

migrate-podcasts-new-library-item

fix-remove-episode-from-playlist

playback-session-use-new-library-item

refactor-library-item

fix-heatmap-caption

feed-episodes-upsert

share-media-player-media-session-api

remove-old-playlist

remove_old_collection_object

plugin-implementation-demo

feed_migration

refactor-feeds-from-item

fix_remove_authors_no_books

v2.17.3-fk-constraints-migration

migrations-first-upgrade

sqlite_2

feature/nuxt-target-server

waveform

sqlite

playlists

video

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/audiobookshelf#2478