feat(cli): add traffic limiting with configurable time periods

[AminAlam]

Adds support for limiting total traffic usage over a specified time period, allowing Conduit node operators to manage bandwidth costs and stay within data caps.

Features

• Traffic Limit Flag (--traffic-limit, -t): Set total traffic limit in GB
• Traffic Period Flag (--traffic-period, -p): Set time period in days
• Automatic Pause/Resume: Service pauses when limit is reached and automatically resumes after period expires
• Persistent State: Traffic usage tracked in traffic_state.json and persists across container restarts
• Real-time Monitoring: Continuous traffic monitoring with limit enforcement

Usage

# Allow 500 GB of total traffic over 10 days:
conduit start --psiphon-config ./psiphon_config.json --traffic-limit 500 --traffic-period 10

This example allows 500 GB of total traffic over 10 days. When the limit is reached, the service waits for the period to end before resuming.

Updated docker-compose.yml to use local image with traffic limit flags and updated README.md with comprehensive documentation.

How It Works

Service tracks total traffic (upload + download) during the configured period. When the limit is reached, the service pauses and waits for the period to end. After the period expires, traffic counters reset and service resumes automatically. Traffic state is persisted to disk for reliability across restarts

[tmgrask]

Hi, we are actually in the middle of implementing a runtime schedule feature to achieve this. since #157 is a feature request we have discussed internally as well. This will enable all Conduit station operators (CLI and mobile) to set a runtime usage schedule, so that they can choose when their conduit gets used more or less. I will be preparing a PR soon

[AminAlam]

Nice! these two features will work very nicely together. I'll be happy to adjust this PR once you merge your PR.

[tmgrask]

Hi, we've been working on the idea of a built-in "reduced usage" window that can be used to tune usage limits down during some daily window. I was able to get the mobile side pretty close yesterday in #179 .

This reduced usage window feature is probably more important for the mobile app where bandwidth and battery are more constrained. The goal is to enable users to run a highly active mobile conduit station overnight while their phone is plugged in and on WIFI, and a less active conduit station during the daytime when they need their battery and bandwidth to last. Still, I think it could be a useful thing for CLI operators running on bandwidth constrained hosts. Hooking this up to the CLI is just a matter of exposing the new InproxyReduced... config values.

I see this PR addresses bandwidth limits in a different way, by stopping the Psiphon controller when a certain bandwidth limit is hit. I am somewhat hesitant about this approach because this means disconnecting everyone connected to the station, which we would obviously like to minimize. Of course I can also understand that bandwidth is a limited resource in the cloud. I would feel better about this feature if we set large enough minimums so that we'd expect a conduit to remain active for some number of days before shutting down. Shutting down too frequently would also have a negative impact on Conduit reputation.

If we had it setup so that you can't set --traffic-limit + --traffic-period to less than 500GB/month or something like that, I'd feel good about it!

(Sorry about the many merge conflicts, I recently refactored the way the CLI parses the Notices that psiphon tunnel core emits.)

[AminAlam]

Hi, thanks for the feedback and the explanation. I've reworked the traffic limiting approach based on your feedback. Here's the new logic:

Instead of stopping the service when hitting a traffic limit, it now throttles down gracefully:

• You set a quota (e.g., 500GB/30days) and a threshold (default 80%)
• You also configure the throttled capacity with --min-connections and --min-bandwidth
• At threshold( for example 80% usage=400GB), it automatically switches to your throttled settings (e.g., 50→10 clients, 40→10 Mbps)
• Existing connections finish naturally, new connections respect the lower limits
• It stays online the whole period, just at reduced capacity
• When the period ends, it resets to full capacity

This way no user disconnections and there is no reputation damage (stays online 24/7) while having the bandwidth management working. It also enforces minimums (100GB/7days) to prevent frequent restarts By default, if you don't set --traffic-limit, everything runs unlimited with zero overhead.

Does this approach align better with what you had in mind? Happy to adjust the thresholds, minimums, or behavior based on your feedback.

[tmgrask]

Hey, thanks for updating this. Unfortunately, restarting the controller like this does disconnect everyone who is connected. We don't have support for dynamically changing MaxClients right now.

I think I am OK with the idea of stopping the process with the minimums you put in (100GB / 7 days w/ 60% min threshold = minimum of 60GB/week). However, I still feel uneasy about having this throttling machinery/behaviour around the main controller.Run invocation. Most CLI runners probably don't want to have any throttling.

What do you think about implementing this "up a level"? Like some new script that manages the existing cli process when it sees the limits hit via the /metrics endpoint. The only downside with that idea is that /metrics then stops reporting anything during the "throttled" time period, but maybe that's OK since that is the desired state.

[tmgrask]

I'm imagining something like:

cli/
├── docker-compose.yml                    # default, no throttling
├── docker-compose.limited-bandwidth.yml  # for quota-limited VPS
└── scripts/
    └── bandwidth-limiter.sh              # entrypoint wrapper, could be a go program instead of shell script

[AminAlam]

Hey, Thanks for the feedback on the previous approach. I've reworked this to implement the supervisor pattern you suggested. Instead of adding throttling logic inside the controller, there's now a separate conduit-monitor tool in cli/scripts/monitor/ that:

1. Runs conduit as a child process and passes through all arguments
2. Scrapes the /metrics endpoint every 10 seconds to track conduit_bytes_uploaded + conduit_bytes_downloaded
3. When threshold is reached (e.g., 80% of 500GB), it gracefully stops conduit and restarts it with reduced --max-clients and --bandwidth values
4. When the period resets, it restarts conduit with normal capacity

The minimums are enforced: 100GB minimum quota, 7-day minimum period, threshold between 60-90%. This ensures at least 60GB/week before any throttling kicks in.

There's a separate docker-compose.limited-bandwidth.yml so users with unlimited bandwidth can keep using the standard compose file unchanged. The main conduit codebase is untouched.

One trade-off: as you noted, restarting does disconnect users. But with these minimums, restarts should be infrequent (at most once per week for heavy usage), and the throttled mode keeps the node running rather than going completely offline.

However, I still believe having dynamically changing MaxClients support implemented in the upstream could make this 10x better as there would be no need to disconnect clients. Maybe that's something you guys can think about for next releases.

[tmgrask]

Great, thanks for being flexible on this. This looks like a good solution for your use case for now.

dynamically changing MaxClients support implemented in the upstream could make this 10x better

Agreed, we like the idea of making this dynamically configurable. This is on our list, when it's ready I'll either make an issue about how it could be used on mobile and CLI or maybe just do it myself.

If you have time to fix those lint errors and to add the new binary to the release workflow, that would speed things up. I should be able to get to this in the next day or two if you don't.

Thanks for the contribution!

[tmgrask]

@AminAlam could you please sign the CLA as described in CONTRIBUTING.md, then I will merge and release.

[tmgrask]

https://github.com/Psiphon-Inc/conduit/releases/tag/release-cli-1.5.0 The new binary is in the docker image