DepotTools API

Docker-based public broker for the DepotTools desktop client. It keeps the DepotBox API key server-side and exposes only the endpoints DepotTools uses.

Protection model

• Anonymous client limit: 30 requests per IP per minute.
• Anonymous daily limit: 60 requests per IP per day for routes that use the daily quota.
• Global upstream budget: 50 DepotBox requests per minute by default.
• Redis-backed counters shared by all API replicas.
• Per-instance in-memory JSON caching and request coalescing prevent duplicate upstream calls within an API instance; cache entries are not shared through Redis or between instances.
• Eight concurrent upstream requests maximum per API instance.
• If an API instance has no available upstream concurrency slot, the request fails immediately with 503. If the shared upstream per-minute budget is exhausted, it fails with 429; the broker does not queue requests for either condition.
• Downloads are streamed and bounded by the same global concurrency/rate controls.
• No client ever receives the DepotBox API key.

The default upstream budget is intentionally below a 60-request upstream limit. Confirm the actual DepotBox terms and limits before deployment.

Local Docker run

cp .env.example .env
# Edit .env and set DEPOTBOX_API_KEY.
docker compose -f compose.yml up --build

The base compose file uses a project-local Docker network and binds the API only to 127.0.0.1; it does not require a pre-created Dokploy network. Redis data is stored in a named volume.

Health checks:

http://localhost:8080/health/live
http://localhost:8080/health/ready

Stop without deleting persistent data:

docker compose -f compose.yml down

Remove local Redis data only when intentionally resetting the test environment:

docker compose -f compose.yml down -v

App integration

The desktop app should point its DepotBox base URL at the deployed broker, for example:

https://api.example.com

The broker accepts the same /api/... paths used by DepotTools. In broker mode, DepotTools must not require or send a user DepotBox key; the broker owns the upstream credential and applies its own anonymous quota. Keep direct DepotBox mode available for development until the hosted broker is deployed and tested.

Required configuration

Set these values in .env or inject them through a secret manager. Do not commit .env or put secrets in the image or compose files.

Variable	Required	Purpose
DEPOTBOX_API_KEY	Yes	Server-side credential for DepotBox; never sent to clients.
UPSTREAM_REQUESTS_PER_MINUTE	No	Global DepotBox request budget; defaults to 50 and must remain below the contractual upstream limit.

CLOUDFLARED_TUNNEL_TOKEN is additionally required only for the Cloudflare compose overlay. The overlay enables trusted-proxy handling with TRUSTED_PROXY_ENABLED=true, reads the client address from FORWARDED_HEADER_NAME=CF-Connecting-IP, and trusts the Docker network range TRUSTED_PROXY_CIDRS=172.16.0.0/12 by default. Set TRUSTED_PROXY_CIDRS to the actual private network CIDR if the Docker network uses a different range.

Production ingress

• Put the API behind TLS and a trusted reverse proxy.

• Do not publish the API container directly to the public internet. The base file's host binding is local-only; a production reverse proxy should be the public TLS ingress and forward to the API over the private Docker network.

• The application uses the socket peer address for anonymous quotas by default; it does not process X-Forwarded-For. If Cloudflare is the sole ingress, start with the overlay, which enables its CF-Connecting-IP handling:

  docker compose -f compose.yml -f compose.cloudflare.yml up -d --build

  Configure the tunnel's public hostname/ingress rule to target http://api:8080. The overlay removes the host port and trusts only the configured Docker network peer range; never expose the API on an untrusted direct path, because clients could spoof the Cloudflare header and evade per-IP accounting.

• Use a secret manager for DEPOTBOX_API_KEY.

• Set UPSTREAM_REQUESTS_PER_MINUTE below the contractual DepotBox limit.

• Add abuse monitoring, IP reputation controls, and an operational kill switch before public launch.

• Do not use this service to bypass DepotBox authorization, terms, or copyright restrictions.

Anonymous-access constraints

This broker intentionally has no client authentication. Any caller who can reach the ingress can use the exposed /api/... routes. The 30-requests-per-IP per-minute limit and the default 50-request global upstream budget are abuse controls, not authorization, and can be affected by proxy/IP configuration. Keep the ingress private or add appropriate WAF, authentication, and abuse controls before exposing it publicly. The /health/live and /health/ready endpoints bypass the anonymous request limiter; restrict them at the ingress if their availability or readiness information must not be public.