kernctl

What it is

kernctl [--url URL] [--token TOKEN] [--json] [--yes] <command>

It talks to the management API, /kern/v1/admin/*. That surface can read everything about the instance and none of anybody's work: it counts records, measures spaces and lists who belongs to what, but never returns the contents of a task, note or whiteboard.

The installer puts it at /usr/local/bin/kernctl. kernctl help prints the same list as this page.

Where it gets its token

On the server's own machine, nothing needs setting up: the server writes a management token on first start and kernctl reads it. Sources are consulted in this order, first match winning:

--url / --token              on the command line
KERN_URL / KERN_ADMIN_TOKEN  in the environment
~/.config/kernctl/config     written by `kernctl use`
/etc/kernctl/config          system-wide, written by the installer
the token file               ADMIN_TOKEN_FILE, or /var/lib/kern/admin-token
http://127.0.0.1:8787        the default

That ordering is why a root shell on the server just works, while a laptop needs to be told once — and why a CI job can set two environment variables and nothing else.

From your own machine

The management API is loopback-only by default, so reach it through an SSH tunnel and remember the choice:

ssh -L 8787:127.0.0.1:8787 you@server
kernctl use http://127.0.0.1:8787 --token kern_…

kernctl use writes ~/.config/kernctl/config with mode 600. Get a token for it with kernctl token new on the server.

If a command is refused with admin_local_only, the address gate stopped you, not your token — the tunnel isn't up, or you are talking to the public address rather than the forwarded one.

Looking at it

status first, when you don't know what is wrong; doctor when you can't reach the server at all, because it tests the path rather than the server.

kernctl status
kernctl health
kernctl health --fix            # repair everything safe
kernctl health --fix=sessions   # repair one check
kernctl logs -f --level warn

Health repairs are safe by construction: each deletes something that has already expired or lost its parent. Nothing repairable touches live data. See keeping it healthy for what is checked.

People

kernctl users list --unverified
kernctl users verify alice@example.com
kernctl users hold bob@example.com "left the company"
kernctl allow add carol@example.com "contractor"

Hold rather than delete when somebody leaves: a hold stops new sessions and leaves everything they contributed to shared workspaces where it is. Deleting is for when they ask you to.

Destructive commands name what they will destroy — deleting an account takes the email as confirmation — so a mistyped id can't take out the wrong one.

Spaces, invites, streams

streams disable is the blunt instrument for a stream being abused from outside: it stops accepting submissions without deleting it or touching its settings, so the owner can fix the rules and you can turn it back on.

Deleted spaces sit in a grace period, which is why spaces list --deleted exists and why kernctl health reports spaces deleted more than 30 days ago as something to clean up.

The instance

kernctl settings
kernctl set registration closed
kernctl set registration default
kernctl notice "Upgrading at 20:00; sync will pause briefly" --warn

Live settings take effect immediately, with no restart and nobody disconnected, because the sign-up checks and /instance read the live value rather than the environment. Which settings are live is on the configuration page.

A notice reaches open apps over the realtime socket, so it is the thing to send before an upgrade, not after.

Tokens and pairing

A token reads kern_<id>_<secret>, and only the hash of the secret half is stored — a stolen database yields no working tokens. Scopes are full and read; give a monitoring check a read token and it can look at everything and change nothing.

kernctl token new "monitoring" --read --days 90
kernctl token list
kernctl token revoke a1b2c3d4e5f60718
kernctl audit 50

Everything that changes something is recorded in the audit trail with the token that did it, so token new per purpose — rather than one shared token — is what makes the audit trail worth reading.

kernctl pair prints a line beginning kern-platform:. Paste it into Kern Platform and it decodes the address and token, vets the address and stores the token in your operating system's credential store. Over a tunnel, forward the port first — the address in the line is the one the server knows itself by.

kernctl pair --json gives the same values as JSON, for a script.

Running it

kernctl service status
kernctl service upgrade
kernctl backup /srv/backups/kern-$(date +%F).sql.gz

service and backup act on the machine they run on, so they need a shell on the server — unlike everything else here, a tunnel is not enough. restore replaces the database: see backups for what clients do afterwards.

Scripting and exit codes

Formatted tables use python3 when it is there. --json always works and needs neither, which is what you want in a script.

1 and 3 are worth separating in a script: refused means the server is up and said no, unreachable means it isn't answering at all.

Monitoring

The whole check is one line, and needs no parsing:

kernctl health --json >/dev/null || echo "kern unhealthy"   # exit 4 when failing

Nightly backup with two weeks kept, from cron:

0 3 * * * /usr/local/bin/kernctl backup /srv/backups/kern-$(date +\%F).sql.gz && \
          find /srv/backups -name 'kern-*.sql.gz' -mtime +14 -delete

Give the monitoring check its own --read token, so a compromised monitoring box can't change anything, and so the audit trail shows which token did what.

For a load balancer, use the public endpoint instead: GET /kern/v1/health needs no token, checks the database and reports realtime figures.

Kern Platform

Kern Platform is the same management API in a desktop app: health, people, spaces, streams, settings, logs, the audit trail and a read-only SQL console. Anything one client can do, the other can — that is deliberate, and it is why a server with no graphical session is not limited.

To connect it, on the server:

kernctl pair "Kern Platform"

Paste the kern-platform: line into the app. If the server is remote, forward the port over SSH first and keep the tunnel open while you use it.