# Kernos

> Terminal interface to hosts — shell execution and file operations.

- **MCP server name:** `korax` (the host that runs the MCP server; e.g., `korax.helu.ca` in prod)
- **Prompt snippet:** [prompts/tools/kernos.md](../../prompts/tools/kernos.md)

## What It Is

Kernos is the workbench. It's how agents run shell commands, inspect files, and operate on hosts. Most engineering work routes through here — Scotty uses it for production operations, Harper uses it for builds and experiments.

The Kernos MCP server itself runs on a host (the codename for the Andromeda-class host is "Kernos"; the actual hostname is environment-dependent — `korax.helu.ca` in production, something else in sandbox/dev). The hostname can matter when an agent needs to talk to it directly, not just through MCP.

## What It's Good For

- Running whitelisted shell commands on a target host
- File inspection (`file_info` for existence, size, permissions before touching)
- Reading config files, log fragments, command output
- Running scripts and one-liners during build and ops work
- Shelling into hosts that aren't the host running the MCP server (when configured)

## What It's Not Good For

- Anything not on the whitelist — `get_shell_config` shows what's allowed
- Long-running interactive sessions — Kernos is request/response, not a persistent shell
- Operations that should be in IaC (Terraform, Ansible) — use those for repeatable provisioning, not Kernos for one-off prod changes
- Anything Argos can do for free (don't use Kernos to `curl` a web page when Argos exists)

## Known Gotchas

- **The `success` boolean matters.** Every Kernos response includes an explicit `success` field. If it's `false`, the command did not run as intended — treat that as the truth, not the surrounding text. This is the root mitigation for the MCP-failure-confabulation pattern noted in agent docs.
- **Whitelist surprises.** A command that "should work" may not be on the whitelist. Run `get_shell_config` first when in doubt.
- **`file_info` before file operations.** Cheaper than failing on a missing path or a permissions issue mid-operation.
- **Hostname targeting.** Kernos can operate on multiple hosts; specifying the wrong target host will silently do the right command on the wrong machine. Verify the target.