Writing Plugins

External modules are standalone executables that communicate with glidesh via newline-delimited JSON on stdin/stdout. They can be written in any language — scripted or compiled. Plugins never receive SSH credentials — they request operations through glidesh, which proxies them over the existing SSH session. They do not receive the secrets vault either: a plugin sees only the secrets the plan passes it as arguments.

Protocol Overview

The protocol has three phases:

1. Describe — glidesh probes the plugin during discovery to learn its name and version. This happens once at startup in a short-lived process. The describe handshake is only used during discovery — runtime check/apply processes do not receive a describe request.
2. Check/Apply — glidesh spawns a new plugin process and sends a task; the plugin may issue SSH requests and returns a result
3. Shutdown — glidesh tells the plugin to exit

All messages are single-line JSON, terminated by a newline.

1. Describe Handshake

glidesh sends:

{"method":"describe"}

Plugin responds:

{"name":"acme/nginx-vhost","version":"1.0.0","protocol_version":1}

Field	Type	Description
name	string	Canonical module name. May contain / for owner/name format
version	string	Module version (informational)
protocol_version	integer	Must be 1

The name in the describe response is authoritative — it becomes the name used in plans with external "acme/nginx-vhost".

2. Check and Apply

After the handshake, glidesh sends check or apply requests:

{
    "method": "check",
    "resource_name": "mysite",
    "args": {
        "server_name": {"string": "example.com"},
        "listen": {"integer": 443}
    },
    "os_info": {
        "id": "ubuntu",
        "version": "22.04",
        "family": "debian",
        "pkg_manager": "apt",
        "init_system": "systemd",
        "container_runtime": "docker" // may be null if no runtime detected
    },
    "vars": {"@host.name": "web-1", "@host.address": "10.0.0.1"},
    "dry_run": false
}

vars never carries the vault

Any variable whose value holds a decrypted secret is stripped from vars before the request is sent — including values that merely embed one, such as a connection string built from a password. Arguments are interpolated first, so a secret the plan passes explicitly (external "acme/widget" "app" token="${api-token}") still arrives in args. If your plugin needs a secret, document that the plan must pass it as an argument. See Secrets.

Check Response

Return one of three statuses:

{"status":"satisfied"}

{"status":"pending","plan":"will create /etc/nginx/sites-enabled/mysite"}

{"status":"unknown","reason":"cannot determine nginx state"}

Apply Response

{
    "changed": true,
    "output": "created vhost mysite",
    "stderr": "",
    "exit_code": 0
}

Error Response

If something goes wrong, return an error at any point:

{"error":"nginx config syntax check failed"}

3. SSH Operations

Plugins don’t have direct SSH access. Instead, they send SSH operation requests and glidesh responds with results. This proxy loop can repeat as many times as needed during a single check or apply call.

exec — Run a command

Request:

{"ssh":"exec","command":"nginx -t"}

Response:

{"ssh_result":"exec","exit_code":0,"stdout":"syntax ok\n","stderr":""}

upload — Write a file

Request:

{"ssh":"upload","path":"/etc/nginx/sites-enabled/mysite","content_base64":"c2VydmVyIHsgLi4uIH0="}

Response:

{"ssh_result":"upload","ok":true}

On failure, an error field is included:

{"ssh_result":"upload","ok":false,"error":"Permission denied"}

download — Read a file

Request:

{"ssh":"download","path":"/etc/nginx/sites-enabled/mysite"}

Response:

{"ssh_result":"download","content_base64":"c2VydmVyIHsgLi4uIH0=","exists":true}

When the file doesn’t exist or an error occurs, exists is false and an optional error field explains why:

{"ssh_result":"download","content_base64":"","exists":false,"error":"No such file"}

checksum — SHA256 of a remote file

Request:

{"ssh":"checksum","path":"/etc/nginx/sites-enabled/mysite"}

Response:

{"ssh_result":"checksum","hash":"a1b2c3...","exists":true}

When the file doesn’t exist: {"ssh_result":"checksum","hash":"","exists":false}. On other failures, an error field is included.

set_attrs — Set file ownership and permissions

Request:

{"ssh":"set_attrs","path":"/etc/nginx/sites-enabled/mysite","owner":"root","group":"root","mode":"0644"}

Response:

{"ssh_result":"set_attrs","ok":true}

On failure: {"ssh_result":"set_attrs","ok":false,"error":"Permission denied"}.

All fields in set_attrs except path are optional — only provided fields are changed.

Error field

All SSH proxy responses except exec may include an optional error string field on failure. Plugins should check ok/exists first, then inspect error for diagnostics.

4. Shutdown

glidesh sends a shutdown request when it no longer needs the plugin:

{"method":"shutdown"}

The plugin should exit cleanly.

Complete Example: example/motd Plugin

All four implementations below do the same thing — set /etc/motd on the target host. The plugin:

1. describe — reports itself as example/motd with protocol version 1
2. check — downloads /etc/motd via SSH proxy and compares to the desired content
3. apply — uploads the new content via SSH proxy
4. shutdown — exits cleanly

Save the file as glidesh-module-example-motd (compiled languages produce a binary with this name), place it in one of the discovery paths, and use it in a plan:

step "Set MOTD" {
    external "example/motd" "Managed by glidesh."
}

Bash

#!/usr/bin/env bash
set -euo pipefail

MOTD_PATH="/etc/motd"

while IFS= read -r line; do
    method=$(echo "$line" | jq -r '.method // empty')

    case "$method" in
        describe)
            echo '{"name":"example/motd","version":"1.0.0","protocol_version":1}'
            ;;
        check)
            resource=$(echo "$line" | jq -r '.resource_name')
            desired="$resource"$'\n'

            echo "{\"ssh\":\"download\",\"path\":\"$MOTD_PATH\"}"
            IFS= read -r result

            exists=$(echo "$result" | jq -r '.exists')
            if [ "$exists" = "false" ]; then
                echo "{\"status\":\"pending\",\"plan\":\"will create $MOTD_PATH\"}"
            else
                current=$(echo "$result" | jq -r '.content_base64' | base64 -d)
                if [ "$current" = "$desired" ]; then
                    echo '{"status":"satisfied"}'
                else
                    echo "{\"status\":\"pending\",\"plan\":\"will update $MOTD_PATH\"}"
                fi
            fi
            ;;
        apply)
            resource=$(echo "$line" | jq -r '.resource_name')
            content=$(printf '%s\n' "$resource" | base64 -w0)

            echo "{\"ssh\":\"upload\",\"path\":\"$MOTD_PATH\",\"content_base64\":\"$content\"}"
            IFS= read -r _result

            echo "{\"changed\":true,\"output\":\"set $MOTD_PATH\",\"stderr\":\"\",\"exit_code\":0}"
            ;;
        shutdown)
            exit 0
            ;;
    esac
done

Requires jq and base64 on the machine running glidesh.

Python

#!/usr/bin/env python3
import json
import sys
import base64

MOTD_PATH = "/etc/motd"

def read_msg():
    line = sys.stdin.readline()
    if not line:
        sys.exit(0)
    return json.loads(line)

def send_msg(msg):
    print(json.dumps(msg), flush=True)

def ssh_download(path):
    send_msg({"ssh": "download", "path": path})
    return read_msg()

def ssh_upload(path, content):
    encoded = base64.b64encode(content.encode()).decode()
    send_msg({"ssh": "upload", "path": path, "content_base64": encoded})
    return read_msg()

while True:
    msg = read_msg()
    method = msg.get("method")

    if method == "describe":
        send_msg({
            "name": "example/motd",
            "version": "1.0.0",
            "protocol_version": 1,
        })

    elif method == "check":
        desired = msg["resource_name"] + "\n"
        result = ssh_download(MOTD_PATH)

        if not result.get("exists"):
            send_msg({"status": "pending", "plan": f"will create {MOTD_PATH}"})
        else:
            current = base64.b64decode(result["content_base64"]).decode()
            if current == desired:
                send_msg({"status": "satisfied"})
            else:
                send_msg({"status": "pending", "plan": f"will update {MOTD_PATH}"})

    elif method == "apply":
        desired = msg["resource_name"] + "\n"
        ssh_upload(MOTD_PATH, desired)
        send_msg({
            "changed": True,
            "output": f"set {MOTD_PATH}",
            "stderr": "",
            "exit_code": 0,
        })

    elif method == "shutdown":
        sys.exit(0)

Requires Python 3 on the machine running glidesh.

Go

package main

import (
  "bufio"
  "encoding/base64"
  "encoding/json"
  "fmt"
  "os"
)

const motdPath = "/etc/motd"

var (
  scanner = bufio.NewScanner(os.Stdin)
)

func readMsg(out any) {
  scanner.Scan()
  json.Unmarshal(scanner.Bytes(), out)
}

func sendMsg(msg any) {
  data, _ := json.Marshal(msg)
  fmt.Println(string(data))
}

func sshDownload(path string) map[string]any {
  sendMsg(map[string]any{"ssh": "download", "path": path})
  var result map[string]any
  readMsg(&result)
  return result
}

func sshUpload(path, content string) {
  encoded := base64.StdEncoding.EncodeToString([]byte(content))
  sendMsg(map[string]any{
    "ssh":            "upload",
    "path":           path,
    "content_base64": encoded,
  })
  var result map[string]any
  readMsg(&result)
}

func main() {
  for scanner.Scan() {
    var msg map[string]any
    json.Unmarshal(scanner.Bytes(), &msg)

    switch msg["method"] {
    case "describe":
      sendMsg(map[string]any{
        "name":             "example/motd",
        "version":          "1.0.0",
        "protocol_version": 1,
      })

    case "check":
      resource := msg["resource_name"].(string)
      desired := resource + "\n"
      result := sshDownload(motdPath)

      if exists, _ := result["exists"].(bool); !exists {
        sendMsg(map[string]string{
          "status": "pending",
          "plan":   fmt.Sprintf("will create %s", motdPath),
        })
      } else {
        encoded := result["content_base64"].(string)
        current, _ := base64.StdEncoding.DecodeString(encoded)
        if string(current) == desired {
          sendMsg(map[string]string{"status": "satisfied"})
        } else {
          sendMsg(map[string]string{
            "status": "pending",
            "plan":   fmt.Sprintf("will update %s", motdPath),
          })
        }
      }

    case "apply":
      resource := msg["resource_name"].(string)
      sshUpload(motdPath, resource+"\n")
      sendMsg(map[string]any{
        "changed":   true,
        "output":    fmt.Sprintf("set %s", motdPath),
        "stderr":    "",
        "exit_code": 0,
      })

    case "shutdown":
      os.Exit(0)
    }
  }
}

Build with go build -o glidesh-module-example-motd.

Rust

use base64::{engine::general_purpose::STANDARD as B64, Engine};
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use std::io::{self, BufRead, Write};

const MOTD_PATH: &str = "/etc/motd";

fn read_msg() -> Value {
    let mut line = String::new();
    io::stdin().lock().read_line(&mut line).unwrap();
    serde_json::from_str(&line).unwrap()
}

fn send_msg(msg: &Value) {
    let mut stdout = io::stdout().lock();
    serde_json::to_writer(&mut stdout, msg).unwrap();
    writeln!(stdout).unwrap();
    stdout.flush().unwrap();
}

fn ssh_download(path: &str) -> Value {
    send_msg(&json!({"ssh": "download", "path": path}));
    read_msg()
}

fn ssh_upload(path: &str, content: &str) {
    let encoded = B64.encode(content.as_bytes());
    send_msg(&json!({
        "ssh": "upload",
        "path": path,
        "content_base64": encoded,
    }));
    let _ = read_msg();
}

fn main() {
    let stdin = io::stdin().lock();
    for line in stdin.lines() {
        let line = line.unwrap();
        let msg: Value = serde_json::from_str(&line).unwrap();

        match msg["method"].as_str() {
            Some("describe") => {
                send_msg(&json!({
                    "name": "example/motd",
                    "version": "1.0.0",
                    "protocol_version": 1,
                }));
            }
            Some("check") => {
                let resource = msg["resource_name"].as_str().unwrap();
                let desired = format!("{resource}\n");
                let result = ssh_download(MOTD_PATH);

                if result["exists"].as_bool() != Some(true) {
                    send_msg(&json!({
                        "status": "pending",
                        "plan": format!("will create {MOTD_PATH}"),
                    }));
                } else {
                    let encoded = result["content_base64"].as_str().unwrap();
                    let current = B64.decode(encoded).unwrap();
                    if current == desired.as_bytes() {
                        send_msg(&json!({"status": "satisfied"}));
                    } else {
                        send_msg(&json!({
                            "status": "pending",
                            "plan": format!("will update {MOTD_PATH}"),
                        }));
                    }
                }
            }
            Some("apply") => {
                let resource = msg["resource_name"].as_str().unwrap();
                ssh_upload(MOTD_PATH, &format!("{resource}\n"));
                send_msg(&json!({
                    "changed": true,
                    "output": format!("set {MOTD_PATH}"),
                    "stderr": "",
                    "exit_code": 0,
                }));
            }
            Some("shutdown") => std::process::exit(0),
            _ => {}
        }
    }
}

Add serde, serde_json, and base64 to your Cargo.toml. Build with cargo build --release and rename the binary to glidesh-module-example-motd.

Packaging Conventions

Convention	Details
Executable prefix	glidesh-module- (required for discovery)
Name format	owner/name recommended for distribution
Protocol version	Must be 1
Describe response	Must return non-empty name
Distribution	Place in ./modules/ (relative to inventory) or ~/.glidesh/modules/

Security: Process Sandbox

glidesh runs every plugin process inside a sandbox:

Measure	Platform	Effect
Env scrub	All	Only PATH, HOME/USERPROFILE, LANG, temp dir vars are passed. Secrets are stripped.
Vault isolation	All	Secret-carrying values are stripped from the request’s vars; a plugin sees only what the plan passes it explicitly.
stderr redaction	All	Plugin stderr is scrubbed of decrypted secrets before it reaches the debug log.
Temp workdir	All	Plugin CWD is the system temp directory, not the project directory.
Session isolation	Unix	setsid() — plugin cannot signal glidesh’s process group.
Filesystem restriction	Linux 5.13+	landlock limits access to /tmp, /usr, /lib, /lib64. Home dirs, project files, and SSH keys are blocked.

Runtime (check/apply) processes also receive GLIDESH_PROTOCOL_VERSION and GLIDESH_MODULE_NAME environment variables.

macOS and Windows

Landlock filesystem restriction is only available on Linux 5.13+. On macOS and Windows, plugins still get environment scrubbing, temp workdir, and session isolation (Unix), but they can read any file accessible to the glidesh user. Always review third-party plugins before installing them — especially on platforms without landlock.

Tips

• Use dry_run in the check/apply request to avoid side effects during --dry-run runs
• The os_info field tells you the target OS, package manager, and init system — use it to adapt behavior
• Template variables from the plan are available in vars — the plugin receives them already interpolated, minus any value carrying a secret (pass those explicitly as arguments)
• Keep plugins stateless between check and apply — glidesh may call them in any order
• Return descriptive plan messages in Pending responses — they appear in dry-run output