drumsergio/cashpilot-worker repository overview

⁠What is CashPilot?

CashPilot is a self-hosted platform that lets you deploy, manage, and monitor passive income services from a single web interface. Instead of manually setting up dozens of Docker containers, configuring credentials, and checking multiple dashboards, CashPilot handles everything from one place.

It supports both Docker-based services (deployed and managed automatically) and browser extension / desktop-only services (tracked via the web UI with signup links, earning estimates, and balance monitoring). Whether a service runs in a container or in your browser, CashPilot aggregates all your earnings into a unified dashboard with historical tracking.

The key differentiator: a browser-based setup wizard guides you through account creation and service deployment, orchestrates containers through Docker workers, and collects earnings from 40+ services across bandwidth sharing, DePIN, storage, and GPU compute categories.

⁠Features

• Web-based setup wizard with guided account creation for each service
• One-click container deployment for 16+ passive income services
• Real-time earnings dashboard with historical charts and trend analysis
• Container health monitoring -- CPU, memory, network, and uptime at a glance
• Multi-category support -- bandwidth sharing, DePIN, storage sharing, GPU compute
• Automatic earnings collection from service APIs and dashboards
• Mobile-responsive dark UI -- manage your fleet from any device
• Simple two-container setup -- UI + Worker, no dependencies to install
• Runs on x86-64 and ARM -- Raspberry Pi, Apple Silicon and ARM cloud boxes; see Running on ARM⁠
• Service catalog with earning estimates, requirements, and platform details

⁠Quick Start

With Docker Compose (recommended):

docker compose up -d
# Open http://localhost:8080

This starts two containers:

• cashpilot-ui -- Web dashboard, earnings collection, service catalog (port 8080)
• cashpilot-worker -- Docker agent that deploys and monitors service containers (port 8081, requires Docker socket)

Then open http://localhost:8080⁠ and follow the setup wizard. On first start, CashPilot prints a one-time setup token to the cashpilot-ui container logs (docker compose logs cashpilot-ui) — enter it on the registration form to create the first (owner) account. See Getting Started⁠ for details.

⁠Supported Services

⁠Docker-Deployable Services

Services CashPilot can deploy and manage automatically via Docker.

⁠Browser Extension / Desktop Only

These services have no Docker image. CashPilot lists them in the catalog with signup links and earning estimates, but cannot deploy or monitor them.

⁠GPU Compute

GPU-intensive computing services. Requires compatible hardware.

⁠How It Works

1. Deploy CashPilot -- a single docker compose up -d gets you running
2. Open the web UI -- browse the full service catalog at http://localhost:8080
3. Browse services -- filter by category, see earning estimates and requirements
4. Sign up -- each service card has a signup link; create accounts as needed
5. Enter your credentials -- the setup wizard collects only what each service needs
6. CashPilot deploys and monitors -- the worker launches containers, health-checks them, and the UI tracks earnings automatically

⁠Architecture

CashPilot uses a split UI + Worker architecture:

• UI container (drumsergio/cashpilot) -- FastAPI web application with dashboard, earnings collection, service catalog, and credential storage. No Docker socket needed.
• Worker container (drumsergio/cashpilot-worker) -- Agent with Docker socket access that deploys, monitors, and manages service containers. Reports status to the UI via API.
• Database: SQLite -- zero configuration, backed up via the mounted volume
• Service definitions: YAML files in services/ are the single source of truth for all service metadata, Docker configuration, and earning estimates
• Frontend: Server-rendered templates with a responsive dark UI

cashpilot/
  app/            # FastAPI application (UI + worker API)
  services/       # YAML service definitions (source of truth)
    bandwidth/    # Bandwidth sharing services
    depin/        # DePIN services
    storage/      # Storage sharing services
    compute/      # GPU compute services
  docs/           # Documentation and guides

⁠Configuration

⁠UI Environment Variables

The UI's web port inside the container is fixed at 8080 (set via the container's CMD); CASHPILOT_BIND_ADDR controls only which host interface it is published on.

⁠Worker Environment Variables

⁠Why the worker looks up its public IP

Bandwidth providers cap earnings per IP address, not per machine. Two workers behind one home connection are two rows on your dashboard and one customer to the provider, so the second one usually earns nothing. To warn you before that happens, each worker asks a public IP-echo service what address it comes from — one request per hour.

That is the only outbound call CashPilot makes purely to learn about your setup. Turn it off with CASHPILOT_EGRESS_DETECT=off, point it at your own endpoint with CASHPILOT_EGRESS_IP_URL, or skip the lookup entirely by stating the address with CASHPILOT_EGRESS_IP. With detection off, the fleet simply reports that worker's exit as undetermined and raises no conflict warnings for it.

Known limitation: grouping matches on the exact address, so on a native-IPv6 connection each machine has its own global address and no conflict is detected. The check is therefore best-effort — it can miss a conflict, but it will not invent one.

⁠Multi-Node Fleet Management

For power users running services across multiple servers, deploy a single CashPilot UI and connect workers from each server. The UI aggregates everything into a unified fleet view; workers report via HTTP API.

CashPilot UI (dashboard + earnings + catalog)
        ^                ^                ^
        | HTTP           | HTTP           | HTTP
  Worker (server-a)  Worker (server-b)  Worker (server-n)
  + Docker socket    + Docker socket    + Docker socket

⁠Setting up the fleet

Use docker-compose.fleet.yml on your main server to run both the UI and a local worker:

docker compose -f docker-compose.fleet.yml up -d

⁠Adding remote workers

On each additional server, deploy only a worker pointing to the UI:

services:
  cashpilot-worker:
    image: drumsergio/cashpilot-worker:1.19
    pull_policy: always
    container_name: cashpilot-worker
    ports:
      # The worker's API is backed by the Docker socket -- deploy, stop or
      # remove ANY container -- so publishing it is publishing full control of
      # this host. It binds LOOPBACK by default for that reason.
      #
      # A remote UI does need to reach it, so set CASHPILOT_WORKER_BIND_ADDR to
      # this server's PRIVATE or VPN address (a Tailscale IP, say). Never a
      # public one, and never 0.0.0.0.
      - "${CASHPILOT_WORKER_BIND_ADDR:-127.0.0.1}:8081:8081"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - cashpilot_worker_data:/data
    environment:
      - TZ=Europe/Madrid
      - CASHPILOT_UI_URL=http://main-server:8080
      - CASHPILOT_API_KEY=your-shared-api-key
      - CASHPILOT_WORKER_NAME=server-b
      - CASHPILOT_WORKER_URL=http://server-b:8081
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true

volumes:
  cashpilot_worker_data:

Communication goes both ways: workers connect outbound to the UI via HTTP for heartbeats, and the UI connects outbound to each worker's :8081 API to push commands (deploy, stop, restart). This means the worker must be reachable from the UI (LAN, Tailscale, or port forwarding) -- set CASHPILOT_WORKER_URL to the address the UI should use, since auto-detection falls back to the container's own network interface, which is often unreachable from another host. The UI's fleet dashboard shows all connected workers, their containers, and live status.

⁠FAQ

Is bandwidth sharing safe?

Bandwidth sharing services generally route legitimate traffic (market research, ad verification, price comparison, content delivery) through your connection. That said, you are sharing your IP address, so review each service's terms of service and privacy policy carefully before signing up. Running these on a VPS rather than residential IP is an option for some services. This is not legal advice -- consult with the particular services you intend to use and, if needed, seek independent legal counsel regarding your jurisdiction.

How much can I earn?

Earnings vary widely based on location, ISP, number of devices, and which services you run. The dashboard tracks your actual earnings over time so you can optimize your setup.

Can I run on a VPS or cloud server?

Some services require a residential IP and will not pay (or will ban) VPS/datacenter IPs. These are marked as "Residential Only" in the service catalog. Services that work on VPS are a good way to scale up without additional home hardware.

How are credentials stored?

All service credentials are encrypted at rest in the SQLite database using a Fernet key stored at /data/.fernet_key, which is generated automatically on first run. The database file lives in the mounted Docker volume (cashpilot_data:/data). No credentials are ever sent anywhere except to the service containers themselves.

Note that this is a different key from CASHPILOT_SECRET_KEY, which only signs login sessions.

⁠Backing up the encryption key

Your credentials are only as recoverable as /data/.fernet_key. If you lose that file you will have to re-enter every credential, because there is no way to decrypt the stored values without it.

# Back it up
docker exec cashpilot-ui cat /data/.fernet_key

# Restore onto a fresh volume: pass the saved value when starting CashPilot.
# It must reach the container, so put it on the same command line (or export it,
# or set it in your .env) - a bare shell assignment on its own line does nothing.
CASHPILOT_ENCRYPTION_KEY=<the value you saved> docker compose up -d

The file always takes precedence over the environment variable, so setting CASHPILOT_ENCRYPTION_KEY on an instance that already has a key changes nothing and is safe. It is adopted only when no key file exists, which is exactly the restore case.

If the key cannot be written to disk at all — an unwritable or unmounted /data — CashPilot refuses to start rather than encrypting your credentials under a key that disappears on the next restart. Set CASHPILOT_ALLOW_EPHEMERAL_KEY=true if that is genuinely what you want.

What about security?

Every service CashPilot deploys runs inside its own isolated Docker container. Containers cannot access your host filesystem, other containers, or your local network unless explicitly configured to do so. CashPilot further hardens deployments with --security-opt no-new-privileges, preventing privilege escalation inside containers. Service credentials are encrypted at rest using Fernet symmetric encryption. Only the worker container requires Docker socket access; the UI container has no privileged access.

That said, no setup is bulletproof. You are still running third-party software that routes external traffic through your network. Docker isolation significantly reduces the attack surface compared to running these services directly on your host, but it does not eliminate all risk. We recommend running CashPilot on a dedicated machine or VLAN, keeping Docker and your host OS up to date, and reviewing the open-source code of any service before deploying it.

What happens if a service container crashes?

CashPilot monitors container health continuously. If a service container exits unexpectedly, it is automatically restarted. The dashboard shows uptime and health status for every running service.

⁠Disclosure

⁠Ecosystem

⁠Contributing

Contributions are welcome. To add a new service:

1. Create a YAML file in the appropriate services/ subdirectory following `services/_schema