The four parts
Everything BasePit does is split between one controller and three kinds of small program that run near your machines.
| Part | Where it runs | What it does | What it never does |
|---|---|---|---|
| Controller | Hosted by BasePit, at app.basepit.com | Holds your inventory, history and settings, serves the console, and makes every decision: what runs where, when a monitor is down, who is paged. | Reach into your network. It only answers connections that your machines open. |
Agent basepit-agent | On each of your hosts: a static binary run by systemd on Linux, or as a system service on macOS | Runs the apps you registered, reports facts and measurements, streams logs when asked, and checks monitors that point at private addresses. | Run anything you did not register, unless the machine's owner switched on an extra at install (see Security). |
Worker basepit-worker | On machines BasePit runs, in several places | Checks your public websites, ports, ping and DNS from outside your network. | Run or deploy anything. The code that runs commands is not in its binary at all, and it refuses private and loopback addresses. |
Cluster agent basepit-kube | Inside a Kubernetes or OpenShift cluster, installed from a Helm chart or plain YAML | Reports the cluster's objects, events, logs and usage, and carries out the actions you take in the Kubernetes area. | Do work meant for a host. The controller refuses to address it as one. |
Proxmox VE nodes and RHEL-family servers are not separate kinds: they run the same agent, which notices the platform and announces what it can do there.
One connection, opened by the machine
A node (an agent, a worker or a cluster agent) dials app.basepit.com over ordinary HTTPS and upgrades the request to a WebSocket. It keeps that one connection open and carries all of its traffic on it, one message per frame. Nothing ever connects in to the machine, so no managed host needs an inbound firewall rule, a VPN or a public address. The connection works through proxies and load balancers that end TLS, and nothing on the node expires.
From the machine
A hello with its capabilities and location, heartbeats, host measurements, app measurements, command results, log lines while someone is reading them, and check results.
From the controller
The machine's configuration, commands, requests to start or stop a log stream, the monitors it should check, and requests to run a check now.
Out of band: files you upload (a JAR, a saved image) travel separately over authenticated HTTPS, so a large download never holds up heartbeats.
How a machine proves who it is
A machine's identity is issued by BasePit, never guessed from the machine. Its hostname, IP and MAC addresses are shown as facts, but what makes it that host is an id and a secret the controller gave it.
- Enrolment. The console gives you an install line with a token that works once, expires in an hour, and is shown once. The installer hands the token to the agent as a private file (mode 0600), never as a command-line argument, and the token never appears in the installer's output.
- The node secret. The controller makes 32 random bytes for the machine, keeps them encrypted on the machine's record, and gives the machine the only plaintext copy, which it stores in a file readable only by its own user.
- Every connection. The controller sends a fresh 32-byte challenge, and the machine answers with an HMAC-SHA256 of it under its secret. The secret crosses the wire once, at enrolment; a recorded answer is useless the next time.
There are no certificates on the machine and nothing that expires. To replace a secret you suspect, use New secret on the host: it keeps the host's id, apps, monitors and history. A revoked host is sent nothing: no commands and no settings.
What leaves your machine
This is everything an agent sends, when it sends it, and whether the controller keeps it.
| What | When | Kept by BasePit |
|---|---|---|
| Facts: hostname, addresses, operating system and kernel, capabilities, location label | On connect, and when they change | Yes, on the host's record |
| Host measurements: CPU, memory, load, uptime, network in and out, disk use per mount, GPU use, memory, temperature and power | Every 15 seconds | Yes, as history. How long depends on your account, and Billing says it. |
| App state and measurements: state, exit code, start time, CPU, memory | Every 15 seconds | Yes, as history |
| Command results: whether it worked, and the last 8 KiB of its output | After each start, stop, restart or deploy | Yes. Secret values are never on a command line, so they are never in this output. |
| App logs | Only while someone has them open or searches them | No. The controller has no log store; the agent keeps a short buffer of recent lines in memory. |
| Container events: stopped, out of memory, restarted, health changed | As they happen, at most 10 per app per minute | Yes, as Activity entries. Never the container's output. |
| Monitor check results | After each check | Yes, as history |
| Host insight: servers listening, processes, services, host logs | Only when someone opens it, on a host whose owner allowed it | No. Read when asked, never stored or logged, and command lines are cleared of anything shaped like a secret on the machine before they are sent. |
| Kubernetes, Proxmox and RHEL pictures: objects, guests, units, ports, denials, updates | On connect, and on change | A live picture in the controller's memory; for Kubernetes, also CPU and memory history. Kubernetes Secret values and Helm values are never sent. |
| Terminal and screen sessions | While open | Opening and closing are recorded. Not a byte of what is typed or shown is logged. |
How secrets reach a process
A password, token or key you give BasePit is sealed under a key that belongs to your organisation alone, and it is never shown again.
- The controller decrypts a secret only when it sends the command that needs it. It travels inside the machine's connection, and the agent puts it into the process's environment in memory, at the moment it starts the process.
- A container gets it as a bare
-e NAME, so the value is never on a command line, in the command's output, in the console or on the machine's disk. It is never written to the audit log or to measurements either. - A script names the secrets it needs in its header; BasePit passes them through the environment, never through
/bin/sh, so a value with a quote or a$cannot break a command. - You can keep secrets in HashiCorp Vault (KV v2, token or AppRole) or AWS Secrets Manager instead. BasePit reads one when an app starts, holds it in memory for 60 seconds, and stores it nowhere.
- Registry credentials are used in the pull itself: nothing is written to the machine's
~/.docker/config.json.
To rotate a secret, set it again under the same name; every app that uses it keeps working. Restart the app so the process gets the new value.
Where decisions are made
The agent is simple on purpose. It holds no desired state, runs no reconcile loop, judges no thresholds and remembers nothing between ticks. It reports what it sees and carries out commands it is given. Every judgement, such as whether a monitor is down, whether to page anyone, or which machines a release goes to, is made by the controller, where it can be seen and changed.
The one exception is AI coding agent sessions. On a host whose owner allowed them, a small session server keeps each session's terminal between your visits, so it survives the agent restarting.
Nothing restarts a stopped app by itself.
That is a deliberate choice. Containers keep Docker's own restart policy across reboots, and BasePit's readiness view shows any app that lacks one. When something stops, BasePit tells you; it does not quietly start it again.
How outside checks run
Each machine and worker has a location label, and the controller assigns monitors by it. Nobody picks a machine by hand.
- A public target is checked by BasePit's workers in up to three places, chosen from the monitor's id so the choice stays the same across restarts.
- A private target, such as an address inside your network, is checked by your own agents at the location
local. - Each place confirms a failure on its own, as a run of failed checks. Then the places vote, so one network with a problem does not page anybody.
- A check that a node could not run at all, such as one whose resolver is down, counts as an error about that node. It never moves the monitor towards Down.
A heartbeat is the one monitor nothing dials: your job calls https://app.basepit.com/h/<token> when it finishes, and BasePit notices when the call does not come.
When the connection drops
- Your apps keep running. BasePit is not in their path: requests to your apps never pass through it.
- The agent keeps up to 15 minutes of measurements and sends them when it reconnects. They fill in the history, and they never change an alert.
- An agent that stops cleanly says goodbye first, so the console can tell a shutdown from a lost connection.
- The agent reconnects by itself. Nothing on the machine expires while it is away.
Agent upgrades start from the console. The agent fetches the new binary from BasePit, checks its size and SHA-256, keeps the old one, and swaps. If the new one has not connected after three starts or two minutes, a guard puts the old one back.
What the install line does
curl -fsSL https://app.basepit.com/install.sh | sudo sh -s -- --token <TOKEN>- Checks first, writes nothing. Root, the tools it needs, the platform, that systemd is really running, and that BasePit answers. If any check fails it says Nothing was installed, and that is true.
- Downloads the agent built for this exact platform and verifies it against two checksums before installing it.
- Enrols, configures and starts the agent as a service, then waits until the machine has actually connected before it says so.
The script is safe to pipe into sh: it is written so that a download cut halfway does nothing. Running it again upgrades the agent and changes nothing else. --dry-run prints every step and writes nothing. The uninstall script it leaves behind needs no network, because a lost connection is when you most need it. Step by step: Get started.
What BasePit does not do
- Open a port on your machines, or connect in to them.
- Run a command you did not register, unless the machine's owner switched on one of the extras listed on Security, each of which has fixed limits.
- See or touch services and processes it does not manage, unless the host's owner allowed host insight.
- Restart a stopped app on its own.
- Keep a copy of your app logs.
- Show a secret again after you set it.