How to Throttle Upload Speed in Croc Transfers

Croc provides the --throttleUpload flag to cap outgoing bandwidth using human-readable units like 500k, 2M, or 1G, leveraging the golang.org/x/time/rate package to enforce limits during each file transfer.

Croc is a secure, peer-to-peer file transfer tool written in Go that prioritizes simplicity and cross-platform compatibility. When sharing large files over limited bandwidth connections, you can throttle upload speed in croc transfers to prevent network saturation and maintain usable internet access for other applications. This functionality parses suffixed values and applies a token-bucket rate limiter to the outgoing data stream.

Using the --throttleUpload Flag

To limit upload bandwidth, append --throttleUpload followed by a numeric value and an optional unit suffix. If you omit the suffix, croc interprets the value as bytes per second.

Supported Size Units

Croc recognizes standard binary suffixes to scale the throttle value appropriately:

• k or K: Kilobytes (1024 bytes per second)
• M: Megabytes (1024² bytes per second)
• G: Gigabytes (1024³ bytes per second)

Practical Command Examples

# Limit upload to ~500 KB/s

croc send --throttleUpload 500k large-file.iso

# Limit to 2 MiB/s when sending folders

croc send --throttleUpload 2M big-folder/

# Limit to 1 GiB/s (useful for testing on fast LANs)

croc send --throttleUpload 1G huge-dataset.tar

# Specify raw bytes for precise control (100 KB/s = 102400 bytes)

croc send --throttleUpload 102400 document.pdf

How Rate Limiting Works in the Source Code

According to the croc source code, the throttling mechanism spans the command-line interface layer and the core client logic, utilizing Go’s standard rate limiting library to govern packet transmission.

CLI Flag Definition

In src/cli/cli.go at lines 156-158, the --throttleUpload flag is defined to accept a string value representing the desired bandwidth cap. This value is passed into the client configuration during initialization.

Parsing and Limiter Creation

In src/croc/croc.go between lines 258-288, croc parses the throttle string and applies the appropriate byte multiplier based on the detected suffix. The code instantiates a rate.NewLimiter from the golang.org/x/time/rate package (declared in go.mod) and attaches it to the Client struct field c.limiter.

Runtime Enforcement

During file transmission, croc consults c.limiter before dispatching data chunks. The limiter’s ReserveN method calculates the necessary delay to maintain the specified rate, pausing execution until the bandwidth budget allows the next chunk to proceed. This token-bucket algorithm ensures the upload rate never exceeds the configured threshold while smoothing out burst traffic.

Summary

• Use --throttleUpload with values like 500k, 2M, or 1G to throttle upload speed in croc transfers.
• The flag is defined in src/cli/cli.go (lines 156-158) and processed in src/croc/croc.go (lines 258-288).
• Croc utilizes golang.org/x/time/rate to create a token-bucket rate limiter stored in c.limiter that enforces caps via ReserveN.
• Omitting unit suffixes interprets the value as raw bytes per second.

Frequently Asked Questions

What units does --throttleUpload support?

The --throttleUpload flag supports k or K for kilobytes, M for megabytes, and G for gigabytes per second. Without a suffix, the value is treated as bytes per second. For example, --throttleUpload 500k limits the transfer to approximately 500 kilobytes per second, while 102400 equals 100 KB/s.

How does croc implement the upload throttle internally?

The implementation resides in src/croc/croc.go where the flag value is parsed between lines 258-288. The code creates a rate.NewLimiter from the golang.org/x/time/rate package and attaches it to c.limiter. During transfers, the ReserveN method pauses execution to enforce the specified bandwidth cap.

Can I throttle download speed separately from upload speed?

While the source analysis focuses on --throttleUpload, croc typically provides separate flags for download throttling. Check the latest src/cli/cli.go for --throttleDownload or similar options, as the architecture supports distinct rate limiters for each transfer direction.

What happens if I specify a raw number without units?

If you omit the unit suffix, croc interprets the value as bytes per second. For example, --throttleUpload 102400 sets the limit to exactly 102,400 bytes per second (100 KB/s), providing precise control when human-readable suffixes are not required.

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