ouranos/docs/kernos.md

Kernos Service Documentation

HTTP-enabled MCP shell server using FastMCP. Wraps the existing mcp-shell-server execution logic with FastMCP's HTTP transport for remote AI agent access.

Features

• HTTP Transport: Accessible via URL instead of stdio
• Health Endpoints: /live, /ready, /health for Kubernetes-style probes
• Prometheus Metrics: /metrics endpoint for monitoring
• JSON Structured Logging: Production-ready log format with correlation IDs
• Full Security: Command whitelisting inherited from mcp-shell-server

Endpoints

Endpoint	Method	Description
/mcp/	POST	MCP protocol endpoint (FastMCP handles this)
/live	GET	Liveness probe - always returns 200
/ready	GET	Readiness probe - checks executor and config
/health	GET	Combined health check
/metrics	GET	Prometheus metrics (text/plain) or JSON

Ansible Playbooks

Stage Playbook

ansible-playbook kernos/stage.yml

Fetches the Kernos repository from clio and creates a release tarball at ~/rel/kernos_{{kernos_rel}}.tar.

Deploy Playbook

ansible-playbook kernos/deploy.yml

Deploys Kernos to caliban.incus:

1. Creates kernos user/group
2. Creates /srv/kernos directory
3. Transfers and extracts the staged tarball
4. Creates Python virtual environment
5. Installs package dependencies
6. Templates .env configuration
7. Templates systemd service file
8. Enables and starts the service
9. Validates health endpoints

Configuration Variables

Host Variables (ansible/inventory/host_vars/caliban.incus.yml)

Variable	Description
kernos_user	System user for the service
kernos_group	System group for the service
kernos_directory	Installation directory
kernos_port	HTTP server port
kernos_host	Server bind address
kernos_log_level	Python log level
kernos_log_format	Log format (json or text)
kernos_environment	Environment name for logging
kernos_allow_commands	Comma-separated command whitelist

Global Variables (ansible/inventory/group_vars/all/vars.yml)

Variable	Default	Description
kernos_rel	master	Git branch/tag for staging

Allowed Commands

The following commands are whitelisted for execution:

ls, cat, head, tail, grep, find, wc, file, stat, mkdir, touch, cp, mv, rm, 
chmod, pwd, tree, du, df, sed, awk, sort, uniq, cut, tr, tee, curl, wget, 
ping, nc, dig, host, ps, pgrep, kill, pkill, nohup, timeout, python3, pip, 
node, npm, npx, pnpm, git, make, tar, gzip, gunzip, zip, unzip, whoami, id, 
uname, hostname, date, uptime, free, which, env, printenv, run-captured, jq

Security

All security features are inherited from mcp-shell-server:

• Command Whitelisting: Only commands in ALLOW_COMMANDS can be executed
• Shell Operator Validation: Commands after ;, &&, ||, | are validated
• Directory Validation: Working directory must be absolute and accessible
• No Shell Injection: Commands executed directly without shell interpretation

The systemd service includes additional hardening:

• NoNewPrivileges=true
• PrivateTmp=true
• ProtectSystem=strict
• ProtectHome=true
• ReadWritePaths=/tmp

Usage

Testing Health Endpoints

/health /ready /live /metrics

MCP Client Connection

Connect using any MCP client that supports HTTP transport:

from fastmcp import Client

client = Client("http://caliban.incus:22021/mcp")

async with client:
    result = await client.call_tool("shell_execute", {
        "command": ["ls", "-la"],
        "directory": "/tmp"
    })
    print(result)

Tool: shell_execute

Execute a shell command in a specified directory.

Parameters

Parameter	Type	Required	Default	Description
command	list[str]	Yes	-	Command and arguments as array
directory	str	No	/tmp	Absolute path to working directory
stdin	str	No	None	Input to pass to command
timeout	int	No	None	Timeout in seconds

Response

{
    "stdout": "command output",
    "stderr": "",
    "status": 0,
    "execution_time": 0.123
}

Monitoring

Prometheus Metrics

The /metrics endpoint exposes Prometheus-compatible metrics. Add to your Prometheus configuration:

- job_name: 'kernos'
  static_configs:
    - targets: ['caliban.incus:22021']

Service Status

# Check service status
sudo systemctl status kernos

# View logs
sudo journalctl -u kernos -f

Troubleshooting

Service Won't Start

1. Check logs: journalctl -u kernos -n 50
2. Verify .env file exists and has correct permissions
3. Ensure Python venv was created successfully
4. Check that ALLOW_COMMANDS is set

Health Check Failures

1. Verify the service is running: systemctl status kernos
2. Check if port is accessible
3. Review logs for startup errors

Command Execution Denied

1. Verify the command is in ALLOW_COMMANDS whitelist
2. Check that the working directory is absolute and accessible
3. Review logs for security validation errors