How croc Integrates with SOCKS5 and HTTP Proxies: CLI Flags and Implementation Details

croc integrates with SOCKS5 and HTTP proxies by exposing --socks5 and --connect CLI flags, which are parsed in src/comm/comm.go to create proxy.Dialer instances using golang.org/x/net/proxy and magisterquis/connectproxy, respectively, and then substituted for the default network dialer on all outbound TCP connections.

The schollz/croc repository implements proxy support directly in its command-line interface and communication layer, allowing users to tunnel secure file transfers through corporate or privacy-focused intermediary servers. This integration leverages standard Go networking libraries to parse proxy URLs and construct dialers that transparently handle connection establishment, ensuring that both metadata and payload traffic route through the specified proxy. Understanding this flow helps operators configure croc correctly in restricted network environments.

CLI Proxy Flags and Environment Variables

croc exposes two primary flags for proxy configuration, defined in src/cli/cli.go. These flags accept URL strings that specify the proxy server address and scheme.

• --socks5 <url>: Configures a SOCKS5 proxy. The URL value can also be set via the SOCKS5_PROXY environment variable.
• --connect <url>: Configures an HTTP CONNECT proxy. The URL value can also be set via the HTTP_PROXY environment variable.

According to the source code in src/cli/cli.go lines 91‑92, these flags are bound to configuration values that the CLI passes downstream to the communication layer【cli.go L91‑L92】. When present, croc ignores direct connections and instead routes all relay traffic through the parsed proxy endpoint.

Proxy Implementation in src/comm/comm.go

The core logic for establishing proxied connections resides in src/comm/comm.go. This file distinguishes between SOCKS5 and HTTP protocols using different third‑party libraries and error handling paths.

SOCKS5 Proxy Support via golang.org/x/net/proxy

When a user supplies the --socks5 flag, croc parses the URL and validates it using the golang.org/x/net/proxy package. The code calls proxy.FromURL to construct a proxy.Dialer compatible with Go’s standard net.Dial interface. If the URL scheme or host is malformed, the function returns an error wrapped as "unable to parse socks proxy url". This dialer is then substituted for the default network dialer in subsequent connection attempts.

As implemented in src/comm/comm.go lines 45‑58, the SOCKS5 path handles URL parsing and dialer instantiation before any data is transmitted【comm.go L45‑L58】.

HTTP CONNECT Proxy Support via connectproxy

For HTTP CONNECT proxies, croc utilizes the github.com/magisterquis/connectproxy library. Similar to the SOCKS5 flow, the provided URL is parsed and passed to connectproxy.New, which returns a dialer capable of tunneling TCP connections through an HTTP proxy. Errors during parsing are wrapped as "unable to parse http proxy url".

This implementation appears in src/comm/comm.go lines 65‑78, where the library constructs the HTTP‑aware dialer【comm.go L65‑L78】.

Dialer Integration and Connection Establishment

After successfully creating either a SOCKS5 or HTTP CONNECT dialer, croc stores the instance in its communication configuration. When the application initiates a TCP connection to a relay or peer, it invokes the proxy dialer’s Dial method instead of the native net.Dialer. This substitution occurs transparently, meaning the rest of the handshake—including encryption via the Noise Protocol and PAKE—proceeds unchanged, merely traveling through the proxy tunnel.

Practical Usage Examples

The following commands demonstrate how to invoke croc with proxy settings. These examples assume the proxy URLs are valid and reachable from the client host.

Use a SOCKS5 proxy for a send operation:

croc send --socks5 socks5://127.0.0.1:1080 ./document.pdf

Use an HTTP CONNECT proxy for a receive operation:

croc receive --connect http://proxy.example.com:8080

Alternatively, export the environment variables to avoid repeating the flags:

export SOCKS5_PROXY=socks5://user:pass@proxy.example.com:1080
croc send ./document.pdf

export HTTP_PROXY=http://proxy.company.net:8080
croc receive

When these variables are set, croc automatically picks them up unless overridden by explicit CLI flags.

Summary

• croc supports both SOCKS5 and HTTP CONNECT proxies through the --socks5 and --connect CLI flags, as defined in src/cli/cli.go.
• The src/comm/comm.go file handles proxy URL parsing and dialer creation, using golang.org/x/net/proxy for SOCKS5 and github.com/magisterquis/connectproxy for HTTP.
• Invalid proxy URLs produce specific error messages: "unable to parse socks proxy url" or "unable to parse http proxy url".
• Once instantiated, the proxy dialer replaces the default network dialer, ensuring all croc traffic flows through the specified intermediary.

Frequently Asked Questions

What environment variables can I use to configure proxies in croc?

You can set SOCKS5_PROXY to provide a default SOCKS5 URL and HTTP_PROXY to provide a default HTTP CONNECT URL. croc checks these variables when the corresponding CLI flags are omitted, making it convenient for scripting and shell profiles.

Which Go libraries does croc rely on for proxy functionality?

According to the source code in src/comm/comm.go, croc imports golang.org/x/net/proxy to implement SOCKS5 support and github.com/magisterquis/connectproxy to implement HTTP CONNECT support. These libraries provide the underlying Dialer interfaces that croc wraps.

How does croc handle malformed proxy URLs?

If the supplied URL cannot be parsed—whether due to an invalid scheme, missing host, or malformed port—croc returns a descriptive error message. For SOCKS5, the error reads "unable to parse socks proxy url"; for HTTP proxies, it reads "unable to parse http proxy url". These messages originate from the parsing logic in src/comm/comm.go.

Can croc route traffic through both a SOCKS5 and an HTTP proxy at the same time?

The current implementation in src/comm/comm.go creates a single dialer based on whichever flag or environment variable is present. While both --socks5 and --connect flags can be defined, the code typically selects one dialing strategy. For cascading proxy chains, users should configure an upstream proxy (such as a local proxy client) that handles the chaining externally, then point croc to that local endpoint.

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