# CivoCloudManager, full reference

## Who

**CivoCloudManager** is a native macOS application that runs the entire Civo Cloud control plane from the Mac menu bar and a full dashboard window. It is built and maintained by Marcel R. G. Berger, a software architect with twenty years of experience, and published by DigitalFreedom Global LLC (Sheridan, Wyoming, United States).

- Author: Marcel R. G. Berger, https://marcelrgberger.com, hello@marcelrgberger.com
- Publisher legal entity: DigitalFreedom Global LLC, 30 N Gould St, Ste N, Sheridan, WY 82801, United States
- Wyoming Secretary of State Filing ID: 2026-002048530
- App Store ID: 6760776010
- Bundle ID: de.berger-rosenstock.CivoCloudManager
- App source code: https://github.com/marcelrgberger/civo-cloud-manager
- Website: https://civo-cloud-manager.app

## How it works

CivoCloudManager connects directly to the Civo REST API v2 over HTTPS, using a Bearer token that the user stores once in the macOS Keychain. There is no backend server operated by the publisher, no telemetry, no analytics, no relay. All requests originate from the user's Mac.

- Civo REST API v2, `api.civo.com/v2`, Bearer token from macOS Keychain
- Kubernetes API, direct connection per cluster over client-certificate mTLS. The kubeconfig YAML returned by Civo is parsed in Swift, the embedded PEM client certificate and PEM private key are imported with `SecItemImport`, combined into a `SecIdentity` with `SecIdentityCreate`, and handed to a `URLSession` delegate. No kubectl, no openssl, no external process.
- Object Store / S3 API, native S3-compatible client with AWS Signature V4 signing via Apple CryptoKit (HMAC-SHA256). No AWS SDK dependency.
- IP detection, `ipify.org` with two fallbacks (`ifconfig.me`, `icanhazip.com`).

## What is delivered

### Menu-bar firewall (free tier)

- One-click Open/Close per firewall, scoped to the user's current public IPv4.
- Auto-detection of the current IP with three fallback providers.
- IP presets (e.g. Home, Office) for one-click access from saved locations.
- Auto-close timer: 15 min, 30 min, 1 h, 2 h, or unlimited; rules auto-expire on the schedule.
- Bulk Open All / Close All across every configured firewall.
- Per-firewall port configuration during onboarding.
- Touch ID gate on destructive or sensitive actions.
- Activity log with timestamps.
- Status indicator: green (all closed), yellow (some open), red (setup incomplete).
- Auto-refresh every 60 seconds.

### Dashboard (one-time Full Access)

- Quota overview with circular gauges and warning badges at 70% and 90% utilisation; in-app quota-change request submits via PUT /quota.
- Dashboard cards for every resource type, clickable to deep-link into the corresponding sidebar section.
- Quick Search (⌘K) across every resource by name.
- Export (⌘⇧E), resources as JSON, with automatic redaction of passwords, API keys, and certificates (`[REDACTED]`).

### Kubernetes

- Cluster lifecycle: create with size-picker grid (Standard / Performance / CPU-Optimised / RAM-Optimised), scale node pools, delete with name-match confirmation.
- Auto-firewall: when a cluster is selected, port 6443 is opened for the user's IP and labelled `civo-cloud-<hostname>-k8s-api`; the rule is removed on navigation away.
- Auto-connect: kubeconfig fetched and parsed lazily on cluster selection; no manual Connect step.
- Live metrics: CPU and memory percentage gauges (via metrics-server), sparkline history charts, pod count and node health indicators.
- Workloads (collapsible): Deployments (with replica scaling), DaemonSets, StatefulSets, CronJobs.
- Networking (collapsible): Services, Ingresses (with TLS status, clickable host URLs), backend info.
- Storage (collapsible): PVCs linked to Civo Volume IDs, PVs with capacity.
- ConfigMap and Secret viewer with namespace filter and base64-decoded values.
- Helm releases, detected from K8s secrets, with chart, version, status, revision.
- Pod operations: real-time log viewer with auto-scroll and auto-refresh, one-off commands run as a short-lived Job (`batch/v1`, alpine image) whose logs are returned, not a `/exec` session, restart via context menu, macOS notifications on restart-count increases.
- Node detail: capacity, conditions (Ready, MemoryPressure, DiskPressure, PIDPressure), addresses, system info (OS, architecture, container runtime, kubelet version).
- Editable node-pool labels.
- Save Kubeconfig, exports the kubeconfig as a `.yaml` file.

### Storage & object stores

- S3 file browser with breadcrumb navigation, table view, multi-select, download to temp + open in Finder, single-file and recursive folder download with progress.
- Object Store credentials managed in-app, with Touch ID-gated reveal.
- Object Store Pause/Resume, archive an inactive store to a central `civo-cloud-manager` vault to save costs; resume to recreate the store with the original name/credentials and restore every file. The vault auto-resizes (grows before pause, shrinks after resume). Parallel transfers (4 concurrent). Verify-before-delete safety: key and size are compared before the original is removed.
- Block-storage volumes: create, attach, detach, live-resize via PUT, delete.

### Compute

- Instances: create with visual size-picker grid showing CPU, RAM, NVMe, hourly price per card; Stop, Start, Reboot from the detail view; Resize via size-picker; SSH command with copy button.
- Ed25519 SSH key generation with CryptoKit (`Curve25519.Signing`), serialised to `openssh-key-v1` format in Swift. The private key is written to a location you pick in a save panel with mode 0600, an AES-GCM-encrypted backup is kept in Application Support, and the public key is uploaded to Civo. No `ssh-keygen`, no shell-out.
- Reverse DNS editable inline.
- Auto-refresh every 5 seconds while an instance is building.

### Networking

- Networks: create, edit, delete (skips the default network).
- Firewalls: create, edit, delete. Drill-down into rule list (protocol, ports, CIDR, direction, action with color-coded badges). Add/delete rules with name-match confirmation.
- Domains: create, list. DNS records edited inline: A, AAAA, CNAME, MX, TXT, SRV, NS.
- Load balancers: list with backends, algorithm, traffic policy; delete.

### Databases

- Create MySQL / PostgreSQL with size-picker grid.
- Connection details, username visible, password gated by Touch ID or system password.
- Delete with name-match confirmation.

### Cost & API health

- Cost dashboard from the Civo charges API. Period picker: This Month (+ projected), Last Month, Last Quarter, This Year. Breakdown by resource type and individual resource. Past months cached locally.
- Rate Editor: configure custom hourly rates that override Civo's default pricing.
- API Health Monitor: tests all 16 Civo API endpoints with response time. Color coded, green <200 ms, orange <500 ms, red >500 ms.

### Quality-of-life

- Smooth animations: staggered row appear, spring transitions, sparklines.
- User-friendly errors: HTTP 500 → "Civo is experiencing issues"; cancelled requests are suppressed silently.
- Safe deletion: typing the exact resource name is required before any destructive action.
- About view with version, build, legal documents and a link to the public source repository.

## Engineering opinions

- **Zero third-party dependencies.** Apple frameworks only, SwiftUI, CryptoKit, Security, LocalAuthentication, Foundation, os. Smaller binary, no supply-chain surface, no signing certificate that someone else owns.
- **Native protocols, not wrappers.** Client-certificate mTLS straight into `URLSession` via Apple's Security framework, AWS SigV4 implemented with CryptoKit HMAC-SHA256, kubeconfig parsing in Swift. No kubectl. No AWS SDK. No shell-outs.
- **Tight App Sandbox.** Four entitlements, no more: app-sandbox, network-client, user-selected read-write files, and app-scoped bookmarks. No camera, microphone, location, contacts, calendar, health, address book or tracking identifier. Verified in `CivoCloudManager.entitlements`.
- **Keychain for the API token.** Hardware-backed encryption, never written to disk in plaintext.
- **Touch ID gate** on credential reveal and on every destructive action where the user has opted in.
- **Swift 6 strict concurrency.** All types `Sendable`, every async boundary explicit.
- **Auto-firewall ownership model.** The app only manages rules it created, labelled `civo-cloud-<hostname>-<context>`. Rules created by other tools or users are never touched.

## Stack

| Layer | Tool |
|---|---|
| Language | Swift 6 (strict concurrency) |
| UI | SwiftUI (MenuBarExtra, Window, NavigationSplitView) |
| Platform | macOS 15+ (Sequoia / Tahoe ready) |
| Civo API | URLSession, Bearer auth |
| Kubernetes API | Client-certificate mTLS via `URLSession` + `SecItemImport` + `SecIdentityCreate` |
| S3 API | AWS Signature V4 implementation built on CryptoKit (HMAC-SHA256) |
| Secrets | macOS Keychain |
| Persistence | UserDefaults |
| Purchases | StoreKit 2 (Non-Consumable, one-time, lifetime) |
| Localization | Apple String Catalog, 8 app languages (en, de, es, fr, it, nl, pl, pt) |
| Login | SMAppService |
| Logging | `os.Logger` with `privacy: .private` |
| Biometrics | LocalAuthentication |

## Markets served

The app interface is localized in 8 languages (English, German, Spanish, French, Italian, Dutch, Polish, Portuguese). The Mac App Store listing is localized in 16 locales and tracked across 15 storefronts: AU, BR, CA, DE, ES, FR, GB, IT, JP, KR, MX, NL, PL, PT, US. The marketing website ships 16 locales (EN default, DE, ES, FR, IT, NL, PL, PT, ZH-Hans, JA, KO, AR, HI, ID, TR, RU). The homepage and all five deep-dive pages exist in every locale; the legal pages are EN and DE only, since the binding templates are never machine-translated.

## Pricing posture

Freemium with a single one-time purchase for lifetime full access, priced per App Store storefront and stated only in the Mac App Store. No subscriptions. No upsells. No "Pro" tier. The free tier (menu-bar firewall) is a complete product on its own. Family Sharing is enabled, so a single purchase covers everyone in the household. Apple offer codes are supported for promotional campaigns.

## Privacy

No telemetry, no analytics SDK, no crash-reporting SDK, no advertising identifier, no attribution SDK, no social-media SDK, no A/B framework. The only outbound connections from the app are to `api.civo.com`, the user's Kubernetes API endpoints, the user's Object Store endpoints, and the three IP-detection fallbacks. The marketing website itself uses Google Analytics 4 with Consent Mode v2 (Advanced), defaults are denied, cookieless aggregated pings continue under Art. 6 (1) (f) DSGVO, full cookies fire only after explicit consent.

## Deep dive pages

The marketing site ships dedicated pages for the five Civo product surfaces CivoCloudManager exposes. Each page targets a narrower query than the homepage and goes into specifics, trade-offs, and architecture. All five exist in English (default) and German (`/de/...`).

- **Civo CLI alternative for Mac**, https://civo-cloud-manager.app/civo-cli-alternative/
  Comparison of the official Civo CLI and CivoCloudManager. Side-by-side capability table, "when GUI beats CLI" framing, and a coexistence section explaining that the CLI stays the right tool for CI/CD pipelines while the app is the right tool for inspection, firewall toggling, log reading, and cost monitoring.
- **Civo Kubernetes GUI for Mac**, https://civo-cloud-manager.app/civo-kubernetes-gui/
  Live cluster dashboard, real-time pod logs, one-off commands run as a short-lived Job, deployment scaling, ConfigMap/Secret viewer, namespace filter. Architecture section explains the client-certificate mTLS path, built on Apple's Security framework, that lets the app talk to the Kubernetes API without kubectl. Includes the auto-firewall behaviour for port 6443.
- **Civo Object Storage browser for Mac**, https://civo-cloud-manager.app/civo-object-storage-browser/
  Native S3-compatible browser implemented in Swift (no AWS SDK), with AWS Signature V4 signed via CryptoKit HMAC-SHA256. Pause/Resume section explains the central vault model: pause copies every object to a `civo-cloud-manager` vault, verifies, then deletes the source store to stop charges; resume restores byte-for-byte.
- **Civo firewall from the Mac menu bar**, https://civo-cloud-manager.app/civo-firewall-mac/
  Free-tier feature in detail: one-click open/close per firewall, auto-IP detection with three fallback providers, IP presets, auto-close timer (15 min, 2 h), bulk Open All / Close All, Touch-ID-gated destructive actions, and the `civo-cloud-<hostname>-<firewall-name>` ownership-label model that keeps the app from touching rules created by other tools.
- **Civo cost dashboard for Mac**, https://civo-cloud-manager.app/civo-cost-dashboard/
  Real numbers from the Civo charges API (not estimates). Period picker (This Month with projection, Last Month, Last Quarter, This Year), per-resource-type breakdown, rate editor for negotiated pricing, month-end linear projection, and a local cache for past months.

## Guides (all 16 locales)
- Connect your Civo API key on a Mac: https://civo-cloud-manager.app/connect-civo-api-key-mac/
- Open a Civo firewall for your current IP: https://civo-cloud-manager.app/open-civo-firewall-for-your-ip/
- Compared with Lens, OpenLens and k9s: https://civo-cloud-manager.app/civo-kubernetes-gui-vs-lens-k9s/
- Civo Object Storage over S3 on macOS (s3cmd, rclone, AWS CLI): https://civo-cloud-manager.app/civo-object-storage-s3-macos/
- Civo DNS records and domains from a Mac: https://civo-cloud-manager.app/civo-dns-manager-mac/
- Changelog: https://civo-cloud-manager.app/changelog/

## Contact

- General: hello@marcelrgberger.com
- App Store listing: https://apps.apple.com/us/app/civocloudmanager/id6760776010?mt=12
- Source: https://github.com/marcelrgberger/civo-cloud-manager
- Personal site: https://marcelrgberger.com

## Legal

- Operating company: DigitalFreedom Global LLC, 30 N Gould St, Ste N, Sheridan, WY 82801, United States.
- Wyoming Secretary of State Filing ID: 2026-002048530.
- Imprint: https://civo-cloud-manager.app/imprint
- Privacy policy: https://civo-cloud-manager.app/privacy
- Terms: https://civo-cloud-manager.app/terms