How to Use croc with Custom Relay Servers: Complete Configuration Guide

You can configure croc to use a custom relay server by setting the --relay, --relay-ports, and --relay-password flags, which populate the RelayHost, AllowedPorts, and RelayPassword fields in the internal webrelay.Config struct.

The schollz/croc repository provides a secure file transfer tool that defaults to public relay infrastructure, but enterprise and self‑hosted deployments require redirecting traffic to private infrastructure. This guide demonstrates how to use croc with custom relay servers by modifying the underlying configuration parameters that control connection endpoints, port ranges, and authentication.

Understanding the Relay Configuration Architecture

The relay behavior is governed by the Config struct defined in src/webrelay/webrelay.go. This structure contains three critical fields that determine how the client connects to relay infrastructure:

• RelayHost – Specifies the hostname of the relay server (without URL scheme). The default value is croc.schollz.com (lines 52‑55).
• AllowedPorts – Defines the slice of TCP ports available for relay connections. The default list includes ports 9009 through 9017 (lines 69‑75).
• RelayPassword – Sets an optional authentication password required by the relay server. The default password is "pass123" (lines 55‑58).

When the client initiates a transfer, the startClient() method in src/croc/croc.go (lines 60‑68) constructs a webrelay.Handler using these configuration values. This handler establishes the WebSocket‑to‑TCP bridge that tunnels file data through your specified relay host and port.

Configuration Methods

Command-Line Flags

The CLI layer in src/cli/cli.go and src/cli/flags/flags.go exposes flags that map directly to the configuration struct fields. Override the defaults when sending or receiving files:

# Send via a custom relay on specific ports with authentication

croc send --relay private.example.com --relay-ports 9009,9010 --relay-password mysecret file.txt

# Receive using the same relay configuration

croc receive --relay private.example.com --relay-ports 9009,9010 --relay-password mysecret

Environment Variables

For automated scripts and CI pipelines, croc accepts environment variables that supersede flag values:

export CROC_RELAY=private.example.com
export CROC_RELAY_PORTS=9009,9010,9011
export CROC_RELAY_PASSWORD=mysecret

croc send file.txt

Programmatic Configuration

When embedding croc as a library, instantiate the Croc struct with custom relay parameters before invoking the client:

c := &Croc{
    RelayHost:     "private.example.com",
    AllowedPorts:  []string{"9009", "9010"},
    RelayPassword: "mysecret",
}
// The startClient() method will use these values when creating the webrelay.Handler

Key Source Files and Implementation Details

The following files contain the implementation details for custom relay configuration:

• src/webrelay/webrelay.go – Defines the Config struct and default values for RelayHost, AllowedPorts, and RelayPassword.
• src/croc/croc.go (lines 60‑68) – Creates the webrelay.Handler using the configured relay parameters, bridging WebSocket connections to the TCP relay.
• src/cli/cli.go – Parses command‑line input and populates the Croc struct fields.
• src/cli/flags/flags.go – Declares the flag definitions including --relay, --relay-ports, and --relay-password.

Summary

• Croc connects to relay servers defined by the webrelay.Config struct with three key fields: RelayHost, AllowedPorts, and RelayPassword.
• Default configuration points to croc.schollz.com with ports 9009‑9017 and password pass123.
• Override defaults using --relay, --relay-ports, and --relay-password CLI flags or the corresponding CROC_RELAY, CROC_RELAY_PORTS, and CROC_RELAY_PASSWORD environment variables.
• The client implementation in src/croc/croc.go instantiates the web relay handler using these parameters to establish secure connections through your custom infrastructure.

Frequently Asked Questions

What is the default relay server for croc?

By default, croc connects to croc.schollz.com using TCP ports 9009 through 9017 with the password pass123, as defined in src/webrelay/webrelay.go lines 52‑58 and 69‑74.

Can I run my own relay server for croc?

Yes, you can deploy a self‑hosted relay and configure croc clients to use it by setting the --relay flag to your server's hostname and ensuring the --relay-password matches your relay's authentication configuration.

Why does croc require multiple ports for the relay?

The AllowedPorts configuration specifies a range of TCP ports (default 9009‑9017) that croc rotates through for connection resilience and load balancing, allowing the client to attempt alternative ports if specific ones are blocked or occupied.

Is the relay password required for custom servers?

While the default password pass123 works with public infrastructure, custom relay servers should specify a unique password using the --relay-password flag or CROC_RELAY_PASSWORD environment variable to prevent unauthorized access to your relay endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}