@tehw0lf/n8n-nodes-unix-socket-bridge

n8n-nodes-unix-socket-bridge

An n8n community node that enables generic Unix domain socket communication with configurable servers for system automation and command execution.

n8n is a fair-code licensed workflow automation platform.

⚠️ Node Verification Status

This n8n node appears as "unverified" in the n8n interface due to its use of Node.js APIs that are outside n8n's standard allowlist:

• net module: Required for Unix domain socket communication
• setTimeout/clearTimeout: Used for connection timeout handling

This occurs because the node requires system-level APIs for socket communication. The functionality is stable and the code is open source for review.

What this means for users:

• ✅ The node works normally in all n8n versions
• ✅ Code is open source and available for security review
• ⚠️ You'll see an "unverified" badge in the n8n interface
• ⚠️ n8n may show a warning when you first add the node

Installation

Method 1: Install via n8n interface (Easiest)

• Open n8n in your browser
• Go to Settings → Community Nodes
• Click Install a community node
• Enter: @tehw0lf/n8n-nodes-unix-socket-bridge
• Click Install
• Restart n8n when prompted

Method 2: Install from npm

npm install -g @tehw0lf/n8n-nodes-unix-socket-bridge

Method 3: Install from source

cd n8n-node
npm install
npm run build
npm pack
npm install -g ./n8n-nodes-unix-socket-bridge-1.0.7.tgz

⚠️ Important if installing with npm or from source: Configure n8n to recognize the custom node

After installing from other sources than within n8n directly, you must set these environment variables for n8n to recognize the custom node:

# Find your installation path
npm list -g @tehw0lf/n8n-nodes-unix-socket-bridge

# Set required environment variables
# Path to your custom node installation
export N8N_CUSTOM_EXTENSIONS=/home/user/.nvm/versions/node/v20.0.0/lib/node_modules/@tehw0lf/n8n-nodes-unix-socket-bridge

# Ensure n8n reinstalls missing packages (recommended for custom nodes)
export N8N_REINSTALL_MISSING_PACKAGES=true

# For multiple custom nodes, separate with colons
# export N8N_CUSTOM_EXTENSIONS=/path/to/node1:/path/to/node2

Add these environment variables to your shell profile (.bashrc, .zshrc, etc.) or your n8n startup script to make them persistent.

Operations

The Unix Socket Bridge node provides seamless communication with Unix domain socket servers:

• Auto-Discovery: Automatically discovers available commands from servers at runtime
• Raw Communication: Send raw messages to Unix sockets
• JSON Commands: Send structured JSON commands with parameter validation
• Flexible Response Handling: Auto-detect JSON responses or handle as plain text

Node Reference

Socket Path

Path to the Unix domain socket file (e.g., /tmp/socket.sock)

Auto-Discover Commands

When enabled, the node automatically discovers available commands from the server using introspection. This provides a user-friendly dropdown of available operations.

Operation Modes

Auto-Discovery Mode (Recommended)

• Automatically loads available commands from the server
• Provides dropdown selection of commands
• Validates parameters based on server configuration
• Handles parameter types and formatting automatically

Manual Modes

• Send JSON Command: Manually specify command name and parameters
• Send Raw Message: Send arbitrary text messages to the socket

Parameters

When using JSON commands, parameters can be provided as key-value pairs. The node handles:

• String parameters: Text values
• Number parameters: Numeric values
• Boolean parameters: True/false flags
• Parameter validation: Based on server-defined patterns and types

Response Handling

• Auto-Detect (default): Automatically detects JSON responses, falls back to text
• JSON: Forces JSON parsing of responses
• Text: Returns raw text responses

Configuration Example

Server Setup

First, set up a Unix socket server using the provided server component:

{
  "name": "System Control",
  "description": "Basic system monitoring commands",
  "socket_path": "/tmp/system.sock",
  "commands": {
    "uptime": {
      "description": "Get system uptime",
      "executable": ["uptime"],
      "timeout": 5
    },
    "disk-usage": {
      "description": "Check disk usage",
      "executable": ["df", "-h"],
      "timeout": 10,
      "parameters": {
        "path": {
          "description": "Specific path to check",
          "type": "string",
          "required": false,
          "style": "argument"
        }
      }
    }
  }
}

n8n Workflow Usage

• Add the Unix Socket Bridge node to your workflow
• Configure the socket path: /tmp/system.sock
• Enable auto-discovery (recommended)
• Select a command from the dropdown (e.g., "uptime")
• Add parameters if needed
• Execute the workflow

Use Cases

• System Monitoring: Check disk usage, memory, CPU, uptime
• Media Control: Control music/video players via playerctl
• Docker Management: Start/stop containers, health checks
• Custom Applications: Integrate any command-line tool with n8n
• System Administration: Automate routine system tasks
• Development Tools: Integrate build tools, test runners, deployment scripts

Server Component

This n8n node works with the Unix Socket Bridge server, which provides:

• Configurable Commands: Define any system command via JSON configuration
• Parameter Validation: Built-in type checking and pattern validation
• Security: Sandboxed execution with restricted environments
• Introspection: Auto-discovery of available commands

For complete server setup and configuration examples, see the main repository.

Security

• Commands are allowlisted in server configuration
• Input validation prevents command injection
• Configurable timeouts prevent hanging processes
• Restricted execution environment
• Socket file permissions control access

Compatibility

• Node.js: >=16.0.0
• n8n: 1.0.0+ (tested with 1.102.4+)
• Operating Systems: Linux, macOS (Unix systems with socket support)

Resources

• n8n community nodes documentation
• GitHub Repository
• Configuration Examples

Troubleshooting

Node Not Appearing in n8n

• Check environment variables are set:

echo "N8N_CUSTOM_EXTENSIONS: $N8N_CUSTOM_EXTENSIONS"
echo "N8N_REINSTALL_MISSING_PACKAGES: $N8N_REINSTALL_MISSING_PACKAGES"

• Verify the node is installed:

npm list -g @tehw0lf/n8n-nodes-unix-socket-bridge

• Check n8n logs for errors:

# For systemd installations
sudo journalctl -u n8n -f

# For Docker installations
docker logs n8n-container-name

• Restart n8n after installation.

Socket Connection Issues

• Verify the socket server is running
• Check socket file permissions
• Ensure the socket path is correct in both server config and n8n node

License

MIT

Support

• Issues: GitHub Issues
• Documentation: Repository README