Documentation
From an empty account to first findings, then billing and licensing.
Getting started
- Create an account. This also creates your organization on the Community plan.
- Open onboarding and create a connector. Copy its credential: it is shown once.
- Install the connector on a Proxmox node or a Linux host that can reach the Proxmox API.
- Read the findings. They appear as soon as the first report is stored.
Connector
The connector reads your cluster with a read-only Proxmox API token and reports every five minutes. It sends only GET requests to Proxmox, opens no port, pins the Proxmox certificate by its fingerprint and reports no credentials, guest contents or guest IP addresses. What the token may not read is left out and shown as unknown, never as a problem.
pveum user add goeck@pve --comment "GoEck Core connector" pveum acl modify / --users goeck@pve --roles PVEAuditor pveum user token add goeck@pve connector --privsep 1 pveum acl modify / --tokens 'goeck@pve!connector' --roles PVEAuditor
cd /tmp curl -fsSLO https://core.goeck-it.com/downloads/goeck-connector-linux-amd64 -O https://core.goeck-it.com/downloads/SHA256SUMS -O https://core.goeck-it.com/downloads/SHA256SUMS.sig -O https://core.goeck-it.com/downloads/goeck-release.pub openssl pkeyutl -verify -pubin -inkey goeck-release.pub -rawin -in SHA256SUMS -sigfile SHA256SUMS.sig sha256sum --ignore-missing -c SHA256SUMS install -m 755 goeck-connector-linux-amd64 /usr/local/bin/goeck-connector install -d -m 700 /etc/goeck-connector $EDITOR /etc/goeck-connector/connector.env # settings below, permissions 600 goeck-connector -config /etc/goeck-connector/connector.env -dry-run systemctl enable --now goeck-connector
Releases are signed (Ed25519). openssl pkeyutl -verify needs OpenSSL 3 (Proxmox VE 8 and later) and prints “Signature Verified Successfully”. The release key's fingerprint is 7f1fb9df70cedfe378bd9900ae4cb38401f7122bd9014418dab9efd32f0737e2; check it with openssl pkey -pubin -in goeck-release.pub -outform DER | sha256sum against the fingerprint you received from us outside this website.
GOECK_API_URL=https://connect.core.goeck-it.com GOECK_CONNECTOR_TOKEN=npc_... # shown once when you create the connector PVE_URL=https://127.0.0.1:8006 PVE_TOKEN_ID=goeck@pve!connector PVE_TOKEN_SECRET=... PVE_TLS_FINGERPRINT=AB:CD:... # openssl x509 -in /etc/pve/local/pveproxy-ssl.pem -noout -fingerprint -sha256 # GOECK_INTERVAL=5m
The systemd unit runs the connector as an unprivileged, throw-away user with a read-only view of the system. Use -once to report a single time and -dry-run -print to see exactly what would be sent.
What is analysed
- Availability: offline nodes, lost quorum, guests set to start at boot that are stopped, HA resources in error, mixed Proxmox VE versions.
- Capacity: storage at 80 and 90 percent, inactive storage, node memory and root file system, projected storage exhaustion from the growth of the last weeks.
- Backups: guests without a backup or without one in the last seven days, failed last backups, guests no enabled job covers, jobs writing to local storage, disabled jobs.
- Security: cluster firewall off, Proxmox users without a second factor, pending (security) updates, expiring web certificates.
The health score combines availability, capacity, backups and security. A part without data is shown as unknown and left out of the score; nothing is estimated. Which findings and how much history a plan includes is listed on the plan comparison.
Connector API
The connector uses three endpoints, authenticated with the connector credential as a bearer token: POST /api/connector/v1/hello, /heartbeat and /inventory. A report is a full snapshot per cluster: assets missing from it are marked as deleted. Unknown fields are rejected.
API
Business and MSP plans include a read-only API. Owners and admins create keys under API in the app; a key is shown once and belongs to one organization. Send it as a bearer token. Each key may make 1,200 requests per hour; a key stops working when it is revoked, expires, or the plan no longer includes the API.
curl -H "Authorization: Bearer $GOECK_API_KEY" \ https://core.goeck-it.com/api/public/v1/overview
GET /public/v1/overview: health score and its parts, open findings by severity, asset counts, clusters with their last report.GET /public/v1/findings: findings with rule, category, severity, title, recommendation and asset. Filters:severity(critical, warning, info),status(open, acknowledged, all; default open).GET /public/v1/assets: nodes, VMs, containers and storage with current CPU, memory and disk usage in percent. Filter:kind(node, vm, lxc, storage).GET /public/v1/assets/{id}: one asset with its findings and, for guests, its last backups.
The API returns exactly what the plan shows in the dashboard. Version 1 only ever adds fields. Errors use the shape {"error": {"code", "message"}} with the HTTP status: 401 for a missing or invalid key, 403 when the plan does not include the API, 429 when the hourly limit is reached (see Retry-After).
How workloads are counted
- Virtual machines and LXC containers count. Nodes and storage do not.
- Templates do not count.
- Deleted assets (no longer reported) and assets you archived do not count.
- The same workload reported by two clusters, recognised by its fingerprint, counts once.
- Over the limit, the oldest workloads stay managed. The rest stay visible and are marked as not managed.
Billing
- Paid plans are bought through Stripe Checkout. Your plan becomes active once Stripe confirms it, not when the browser returns.
- The trial requires a payment method. Checkout states the date and amount of the first charge.
- Cancelling takes effect at the end of the paid period, or at the end of the trial without a charge. You can reactivate until then.
- If a renewal payment fails, access continues for a grace period, then the organization is limited to the Community plan. Data is kept.
- Payment methods, billing details and invoices are managed in the Stripe customer portal, opened from Billing.
Self-hosted licensing
For plans that include self-hosted deployment. The self-hosted control plane itself is not yet released for production use.
- An owner or admin creates a deployment and receives a one-time activation code.
- The installation generates an Ed25519 key pair and activates with the code and a proof of possession. It receives a signed license bound to that key.
- It validates online periodically with a signed request and a fresh nonce. Entitlement changes arrive as a renewed license.
- Offline, the license keeps working for the grace period written into it, and never beyond its expiry.
Public verification keys are served at GET /api/licensing/keys. Private keys never leave the licensing service.