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

> Learn to configure croc with custom relay servers using the --relay, --relay-ports, and --relay-password flags for secure file transfers. Get started now.

- Repository: [Zack/croc](https://github.com/schollz/croc)
- Tags: how-to-guide
- Published: 2026-07-27

---

**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`](https://github.com/schollz/croc/blob/main/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`](https://github.com/schollz/croc/blob/main/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`](https://github.com/schollz/croc/blob/main/src/cli/cli.go) and [`src/cli/flags/flags.go`](https://github.com/schollz/croc/blob/main/src/cli/flags/flags.go) exposes flags that map directly to the configuration struct fields. Override the defaults when sending or receiving files:

```bash

# 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:

```bash
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:

```go
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`](https://github.com/schollz/croc/blob/main/src/webrelay/webrelay.go)** – Defines the `Config` struct and default values for `RelayHost`, `AllowedPorts`, and `RelayPassword`.
- **[`src/croc/croc.go`](https://github.com/schollz/croc/blob/main/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`](https://github.com/schollz/croc/blob/main/src/cli/cli.go)** – Parses command‑line input and populates the `Croc` struct fields.
- **[`src/cli/flags/flags.go`](https://github.com/schollz/croc/blob/main/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`](https://github.com/schollz/croc/blob/main/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`](https://github.com/schollz/croc/blob/main/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.