maki-ssh

A Maki plugin that turns an SSH server into the agent's active workspace. Connection settings come from environment variables, and the agent automatically uses remote equivalents of its shell, read, write, edit, list, glob, grep, and index tools.

Install

Install globally for the current user with one command:

curl -fsSL https://raw.githubusercontent.com/arxdeus/maki-ssh/main/install.sh | bash

The plugin is installed in ${XDG_CONFIG_HOME:-$HOME/.config}/maki.

Requirements:

• Maki with Lua plugin support
• ssh
• sshpass
• A POSIX-compatible remote shell

On Debian or Ubuntu, install the SSH dependencies with:

sudo apt install openssh-client sshpass

The installer refuses to overwrite existing global Maki plugin files. Use --force to back them up and replace them, or merge .maki/init.lua and .maki/plugin.toml manually:

curl -fsSL https://raw.githubusercontent.com/arxdeus/maki-ssh/main/install.sh | bash -s -- --force

Connect

Pass the SSH connection to Maki through environment variables:

MAKI_SSH_HOST=server.example.com \
MAKI_SSH_USER=deploy \
MAKI_SSH_PORT=22 \
MAKI_SSH_PASSWORD='your-password' \
MAKI_SSH_ROOT=/srv/app \
maki

Or export the variables first:

export MAKI_SSH_HOST=server.example.com
export MAKI_SSH_USER=deploy
export MAKI_SSH_PORT=22
export MAKI_SSH_PASSWORD='your-password'
export MAKI_SSH_ROOT=/srv/app
maki

Environment variables

Variable	Required	Default	Description
MAKI_SSH_HOST	yes	—	SSH hostname or IP address.
MAKI_SSH_USER	yes	—	SSH username.
MAKI_SSH_PORT	no	22	SSH port.
MAKI_SSH_PASSWORD	yes	—	SSH password passed to sshpass through SSHPASS, never as a command argument.
MAKI_SSH_ROOT	no	.	Remote project root. All tool paths are relative to it.
MAKI_SSH_HOST_KEY_CHECK	no	accept-new	accept-new or yes. Use yes for strict pre-verified host keys.

Environment variables are read when Maki starts. Restart Maki after changing them.

How it works

When configured, the plugin tells the agent that the remote server is its active project workspace. It should use these tools instead of local tools:

Remote tool	Purpose
ssh_bash	Commands, builds, tests, Git, and other shell operations.
ssh_read	Paged, line-numbered text reads.
ssh_write	Atomic complete-file writes.
ssh_edit	Exact or fuzzy string replacement.
ssh_multiedit	Multiple ordered replacements in one file.
ssh_list	One-level directory listing.
ssh_glob	File lookup by glob pattern.
ssh_grep	Recursive regular-expression search.
ssh_index	Compact source-file or directory structure.

The tool inputs do not include host, user, port, or password. The agent cannot select a different server; every remote tool uses the environment-defined connection.

Examples

Ask Maki normally after launching it with the environment variables:

Inspect this project and explain its architecture.

Find the authentication handler, fix the token validation bug, and run tests.

Read package.json and update all outdated lint scripts.

Maki will use the ssh_* tools for those operations.

Security

Password authentication has unavoidable risks. SSH keys or an SSH agent are safer, but this version intentionally supports the requested host/user/port/password workflow.

• The password is provided to sshpass through the child process environment as SSHPASS; it is not placed in command-line arguments or tool output.
• Privileged local users may still inspect another process's environment.
• Avoid placing plaintext passwords in shell history. Prefer a secret manager or a silent prompt:

read -rsp 'SSH password: ' MAKI_SSH_PASSWORD; echo
export MAKI_SSH_PASSWORD
MAKI_SSH_HOST=server.example.com MAKI_SSH_USER=deploy MAKI_SSH_PORT=22 MAKI_SSH_ROOT=/srv/app maki
unset MAKI_SSH_PASSWORD

• MAKI_SSH_HOST_KEY_CHECK=accept-new accepts a host key only on first connection and rejects changed keys. Set it to yes after verifying the host key for stricter protection.
• Paths are restricted to MAKI_SSH_ROOT; absolute paths, .. traversal, and symlink file targets are rejected.
• Writes use a temporary file followed by an atomic rename.
• File sizes and returned output are bounded.
• ssh_bash can execute arbitrary commands as the configured SSH user. Use a dedicated least-privileged account.
• A detached remote process may survive when a timed-out local SSH process is terminated.

Optional Maki limits

The plugin supports these Maki plugin options in addition to the environment variables:

maki.setup({
  plugins = {
    maki_ssh = {
      connect_timeout_secs = 10,
      command_timeout_secs = 60,
      max_read_bytes = 50000,
      max_write_bytes = 65536,
      max_output_lines = 2000,
      max_output_bytes = 50000,
    },
  },
})

Environment variables define the connection; options only control limits and timeouts.

Verify

With the environment variables set:

maki prompt --tools --names | grep '^ssh_'

Expected tools:

ssh_bash
ssh_read
ssh_write
ssh_edit
ssh_multiedit
ssh_list
ssh_glob
ssh_grep
ssh_index

Project-only installation

From a clone:

git clone https://github.com/arxdeus/maki-ssh.git
cd maki-ssh
./install.sh --project /path/to/project

Without cloning:

curl -fsSL https://raw.githubusercontent.com/arxdeus/maki-ssh/main/install.sh | bash -s -- --project /path/to/project

Uninstall

If these files contain only maki-ssh, remove the global installation:

rm "${XDG_CONFIG_HOME:-$HOME/.config}/maki/init.lua" \
   "${XDG_CONFIG_HOME:-$HOME/.config}/maki/plugin.toml"

If they contain other Maki configuration, remove only the merged maki-ssh sections.