koios/docs/tools/kernos.md

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

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.