assh

An SSH workflow helper that gives LLM agents persistent tmux sessions and pageable, context-friendly output.

Stars
★ 22
Last updated
11d ago
License
MIT
Primary language
Go

At a glance

How it runs
CLIAgent plugin / skill
Works with
Universal · cross-platformCodex · Claude CodeChatGPT (Unsupported)
Cost
Free, no paid service needed
Setup effort
Low · running in minutes
You'll need
Node.js/npm (for global install)Go binary from GitHub Releases (installed via npm wrapper)system OpenSSH clienttmux on remote hostrsync (only for transfer sync)GNU find/stat on remote host (only for transfer list/stat)Shell / CLINetwork accessLocal filesystem
Typical use
A terminal coding agent (Claude Code, Codex, OpenCode) needs to inspect logs or restart a service on a remote box without dumping thousands of journal lines into its context window.
Not a fit if
  • Users who just want a one-off interactive SSH login, not persistent sessions
  • Workflows needing interactive password prompts or Windows remote hosts
  • Security teams requiring independently signed release provenance
Maintenance
Commits in the last 30 dayslast commit 2026-11-09latest release v1.4.0 (2026-11-09)
Source review
65/100 · Some gaps

What does this agent do, and when should you use it?

assh is a Go CLI distributed through npm that packages the SSH workflow an LLM agent actually needs. A single assh connect creates or reuses an SSH key, optionally deploys the public key using a password passed by environment variable, verifies key login, checks remote capabilities, installs tmux non-interactively, garbage-collects old trusted sessions, and opens a persistent tmux session — returning a session id plus ready-to-run next_commands. Subsequent remote work goes through assh session exec, which returns compact JSON metadata (ok, rc, seq, line counts), and assh session read, which pages output by line window so the agent only pulls what it needs. Beyond sessions it ships one-shot exec/read, transfer file operations and rsync sync, forward port forwarding, fleet exec for parallel multi-host runs, scan host inventory, audit with a savings counter, and capabilities probing. Safety features include a destructive-command classifier, best-effort secret redaction, and readonly/ops/admin profiles. The repo also packages the skill as plugins for Claude Code, Codex, Copilot CLI, Pi and rule files for Cursor, Cline and OpenCode.

assh connect picks the key from --identity (default ~/.ssh/id_agent_ed25519, generated if missing), tries key login first, and only falls back to a password from the env var named by -E when key auth fails; it then appends the public key, re-verifies key login, checks server capabilities, installs tmux unless --no-install-tmux, cleans old trusted assh sessions unless --no-gc, and opens a tmux session named assh_<sid>, recording local registry metadata. Commands return JSON metadata first — assh session exec -s SID -- "cmd" yields {ok, rc, seq, stdout_lines, stderr_lines}, and assh session read --seq N --limit M [--offset] [--stream stderr] [--raw] returns a page of content with total_lines and has_more. Long work moves to session exec-async with job-status/job-cancel. transfer put|get|read|list|stat|mkdir|rm|mv|sync covers file operations and returns an output_id for paged reads; forward start|status|stop manages tunnels; fleet exec runs one command across hosts and reports per-host results plus a failed count with 8 KiB per-stream caps; scan emits a JSON OS/CPU/memory/disk/uptime inventory; audit --last|--host|--failed|--savings reads local logs and sums lines withheld by pagination. Remote command text is checked by a pattern-based destructive-command classifier, output is redacted by default (--no-redact disables), and --profile readonly|ops|admin restricts commands inside a session using ~/.config/assh/profiles.json.

  1. A terminal coding agent (Claude Code, Codex, OpenCode) needs to inspect logs or restart a service on a remote box without dumping thousands of journal lines into its context window.
  2. An operator receives a provider server-info block and wants one command to do first password login, install the key, and end up in a reusable session.
  3. Debugging that requires a persistent shell where the working directory and environment survive between steps.
  4. Piping a build or setup script to the remote host via stdin, or moving large files with transfer put/get/sync instead of shell redirects.
  5. Running the same diagnostic across several hosts at once with fleet exec and spotting failures from the aggregated result.
  6. Giving Claude Code, Codex, Cursor, Cline, Copilot CLI, OpenCode or Pi native SSH know-how through the bundled skill/plugin installers.

Key setup facts

Pulled from the install and usage notes below. The project README has the current values.

Install / run
  • npm i -g agent-assh
Environment variables
JOB_ID
Config files
~/.ssh/id_ed25519

How do you install or deploy this agent?

Install the npm wrapper; it downloads the matching Go binary from GitHub Releases. You need Node.js/npm locally, and the remote host needs OpenSSH and an installable tmux on a Unix-like system.

npm i -g agent-assh

Archives can also be fetched by hand from GitHub Releases. The installer verifies the archive SHA-256 against checksums.txt, but that checksum comes from the same release, so it protects against corrupt downloads rather than a replaced release; build from source if you need provenance.

https://github.com/izzzzzi/agent-assh/releases

How do you use this agent?

First connect by key, or by password on first login when you only have credentials (password travels only through an environment variable).

assh connect -H 203.0.113.10 -u root -i ~/.ssh/id_ed25519 -n deploy

export TARGET_PASS="..."
assh connect -H 203.0.113.10 -u root -E TARGET_PASS -n deploy
unset TARGET_PASS

Use the returned sid with the session API; the connect response includes next_commands.

assh session exec -s f7a2b3c4 -- "pwd"
assh session read -s f7a2b3c4 --seq 1 --limit 50
assh session read -s f7a2b3c4 --seq 1 --limit 50 --raw
assh session close -s f7a2b3c4

Background jobs, stdin scripts, port forwarding and file transfer:

assh session exec-async -s f7a2b3c4 -- "make build"
assh session job-status -s f7a2b3c4 --job-id JOB_ID

cat script.sh | assh session exec -s f7a2b3c4 --stdin -- "bash -s"

assh forward start -H HOST -u USER -i KEY
assh transfer put -H HOST -u USER -i KEY ./local /remote/path

Install the agent skill, e.g. for Claude Code and Codex:

/plugin marketplace add izzzzzi/agent-assh
/plugin install assh@assh
codex plugin marketplace add izzzzzi/agent-assh
codex plugin add assh@assh

What are this agent's strengths and limitations?

Pros
  • One connect call handles key creation, optional password-based first login, tmux install, session GC and session creation, and hands back runnable next_commands.
  • The metadata-then-page output model (seq, --limit, --offset) keeps large output out of the agent context, with audit --savings reporting withheld line counts.
  • Explicit secret hygiene: passwords only via env var names, no password flag, hashed command text in audit logs, and default redaction of AWS keys, JWTs, PEM keys and provider tokens.
  • ControlMaster pooling reuses the SSH socket, and exec-async/job-status/job-cancel cover work that outlives the default 300-second session exec timeout.
  • One CLI spans sessions, transfers, port forwarding, multi-host fan-out, host scanning, and documented plugin/skill installs for several terminal agents.
Limitations
  • The safety classifier and profiles are pattern-based guardrails only; the README states they ignore scripts passed via --stdin, interpreters, and cases like docker rm or DROP DATABASE.
  • Requires the system OpenSSH client; transfer sync additionally needs rsync and transfer list/stat need GNU find/stat, otherwise returning unsupported_remote.
  • tmux sessions target Unix-like remote hosts, v1 has no interactive password prompts, and --force-pty merges stderr into stdout with heuristic banner stripping.
  • No independent release signing (Sigstore/cosign): the checksum comes from the same release, so provenance-sensitive users must build from source.
  • One session exec at a time per session is advised because commands share a single shell, and profile restrictions do not apply to exec, transfer or fleet.

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

Agent Source review Form / cost Stars Updated Language Full support on
assh This agent 65 · Some gaps CLIFree ★ 22 11d ago Go Codex · Claude Code
Agent Payment Node (APN) 80 · Good CLIFree ★ 73 2d ago TypeScript —
Agency Orchestrator: One Sentence to Orchestrate an AI Expert Team 71 · Some gaps CLIFree + model costs ★ 2.5k 10d ago TypeScript Codex · Claude Code · OpenAI API · Claude API
OpenOSINT: AI-Powered OSINT Investigation Agent 68 · Some gaps CLIFree + model costs ★ 2k 5d ago Python Claude Code · Claude.ai · OpenAI API

How does FollowAgents rate this agent?

FollowAgents source review · FARS-2.1
Some gaps
65/ 100 5-point scale 3.3 / 5
Trust 16/29
Reliability 9/14
Adaptability 14/18
Convention 12/18
Effectiveness 10/13
Verifiability 4/8
Why each dimension lost points
Trust16 / 29 · 2.8/5

Least privilege: offers readonly/ops/admin profiles and a safety classifier, but explicitly states these are guardrails not security boundaries, and exec/transfer/fleet bypass profiles, so 2. User confirmation: destructive commands require --confirm-danger, exec/exec-async/fleet deliberately lack the flag and multi-host destructive execution is impossible, but the classifier is pattern-based and bypassable via scripts, so 2. Data flow transparency: README explains passwords via env/file, audit stores only command hashes, output redacted by default, but local transcript keeps command text, a transparency gap, so 2. Sensitive data handling: no --password flag, passwords excluded from audit, default redaction, but redaction is best-effort and --no-redact disables it, so 2. Dependency security: go.mod only cobra/pflag/mousetrap, small surface, but no go.sum or vuln-scan evidence shown and npm postinstall downloads binaries verified only against same-release checksums.txt with no independent signature, so 1. External effects: default -T, accept-new host keys, cleanup limited to trusted metadata, controlled, so 2. Rollback: session close/gc and job-cancel exist, but no recovery for already-executed destructive actions, so 1. Source attribution: plugin/package metadata points to izzzzzi, but publisher is unverified by FollowAgents and identity unknown, so 1.

Reliability9 / 14 · 3.2/5

Self-consistency: README, AGENTS.md and SKILL.md agree on commands and error codes, and AGENTS.md is generated from the skill with CI checking copy sync, so 2. Dependency availability: relies on system OpenSSH, tmux, rsync, GNU find/stat; cross-platform limited and external dependency detection not declared in package, so 1. Failure messages: error-code table (dangerous_command_requires_confirmation, command_not_allowed, timeout, etc.) gives clear remediation, so 3.

Adaptability14 / 18 · 3.9/5

Audience and scenarios: targets LLM agents doing SSH work, covering connect, sessions, transfer, jobs, fleet; scenarios clear, so 2. Capability boundaries: explicitly lists classifier/redaction as non-boundaries, no interactive password, tmux Unix-only, 4 MiB stdin cap; boundaries well documented, so 3. Trigger precision: SKILL.md description names SSH/remote commands/logs/transfer/deploy scenarios, fairly precise, but 'use assh for any SSH work' is broad, so 2. Environment fit: supports multiple agent install paths and --force-pty, --ssh-config, jump hosts, but depends on Unix remotes and system tools, so 2.

Convention12 / 18 · 3.3/5

Information architecture: README well-sectioned with architecture diagram and command list; AGENTS.md and SKILL.md consistent, so 2. Install notes: npm global install, per-agent install methods and manual download, but postinstall binary-download mechanism is thinly explained, so 2. Naming stability: package agent-assh, command assh, plugin assh consistent; version 1.4.0 consistent across files, so 2. Examples and FAQ: many command examples and error-handling table, but no dedicated FAQ, so 2. Known limitations: detailed Limitations section on platform, dependencies, concurrency, stdin, so 3. License: MIT, LICENSE file matches metadata, so 3. Versioning/changelog: version numbers and release workflow present, but no CHANGELOG file, so 1. Maintenance responsibility: SECURITY.md gives reporting channel and supported versions, but publisher unverified and no explicit maintainer commitment, so 1.

Effectiveness10 / 13 · 3.8/5

Output usability: compact JSON, next_commands, paginated reads and --raw, agent-parseable, so 3. Marginal value: adds persistent sessions, output pagination, redaction and safety classifier over raw ssh, clear value though composable from existing tools, so 2. Cost benefit: requires Go binary install and remote tmux; benefit is context savings and guardrails, reasonable tradeoff but adds dependencies, so 2.

Verifiability4 / 8 · 2.5/5

Claim traceability: README claims CI badge and workflow files corroborate, but most security/behavior claims lack corresponding source in the packet, so 1. Cross-source corroboration: README, AGENTS.md, SKILL.md, SECURITY.md and CI config mutually corroborate commands and security policy, so 2. Fact/inference separation: docs distinguish 'guardrails not boundaries' and 'best-effort redaction' without overclaiming, so 2.

Risks and how to mitigate them
  • The safety classifier and profiles are pattern-matching guardrails only; they can be bypassed via --stdin scripts, interpreters, or unclassified commands (docker rm, DROP DATABASE, git reset --hard) and are not a security boundary.
  • npm postinstall downloads binaries from GitHub Releases verified only against same-release checksums.txt with no independent signature, risking a replaced release; build from source for sensitive environments.
  • The local session transcript keeps command text, so never inline secrets in commands; redaction is best-effort and can be disabled with --no-redact.
  • Publisher identity is unverified by FollowAgents; verify provenance and release integrity before installing.
  • Depends on system OpenSSH, tmux, rsync and GNU tools; functionality is limited on non-Unix remotes or when tools are missing.
Evidence confidence: Low Reviewed Nov 15, 2026 Reviewed revision 6ddefe1aba2d
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/agent-assh.svg)](https://followagents.com/en/agents/agent-assh)
<a href="https://followagents.com/en/agents/agent-assh"><img src="https://followagents.com/badge/agent-assh.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. v1.4.0
    Release notes excerpt
    Changelog * 745024878c9149d8eb66a1eaf15018dc2ce5a866 Merge: pause dependabot updates * f0b44fbf4e426e22182e6f58d9bbc0e820563195 Merge: release 1.4.0 * 3d9fc3be3edbdebf65480109c437bc7a0cce6961 chore: pause dependabot updates (remove config temporarily) * a43bd0fa955431c3c4f6652748ba3838e9dbb53b fix: close quote-desync and process-substitution bypasses, honour --batch * c63230e285264ab3089b7f7ff81b34ba82d41d6d release: 1.4.0 — safer sessions, one-source skill, installable plugin
    View on GitHub ↗
  2. v1.3.3
    Release notes excerpt
    Changelog * 769b6147c00f42c9ea8b4af71220925faa4f56d1 Bump version to 1.3.3 * fd94f091772bc100fdc0695524fe0518bf341e3e Merge branch 'docs/assh-skill-usage-fixes' * 488e87bcb6d4a449c6d479f4fbc70150fea9e9ba Merge: bump version to 1.3.3 * 8bd7d7a972e5eca4fec028895ba095d621b9b8dd Merge: ci rerun * bfd75aec956e8a4b68d48edec10f256ae8bb71ee Merge: docs accuracy pass * 1055de660c80b921488ac2cfb1f2bbae7bca128d Merge: fix golangci v2 config * bb4f677a5847cb8f42f3e5bb09c8ca62bd08c6f1 Merge: remove docker/db-query wrappers …
    View on GitHub ↗
  3. v1.3.2
    Release notes excerpt
    Changelog * 08bc624af9346c646e9a4426fbdb19eb5c3348da chore: bump version to 1.3.2 * 7db8e9d85b7fe64dceca4cb0f29a6b553bd5cf34 chore: ignore agent scratch files * a4114bcf96af4d8e91bdf8a6f2d0a0e8df8c7dc0 feat: label session list liveness as ttl-only * 721627db2cbf652e6b69ed93a2a5eb3f15ab2f90 feat: report stale remote tmux sessions * f635591d54858f9ee0b82113821b5f64d7bd04e1 feat: report unreachable registered sessions * 34d119d188cf86bf8fcec23097e06a0cdf746789 fix: add recovery hints for missing session output
    View on GitHub ↗

FAQ

Does assh call an LLM itself?
No. It contains no model or API calls; it is an SSH and session tool used by an external agent such as Claude Code or Codex, or by a human operator.
How is the password passed, and does it land in logs?
connect and key-deploy accept only an environment variable name via -E (there is no --password flag), and connect-info reads a provider block from a file or stdin. Audit logs keep command hashes rather than command text and never the password values, but the local session transcript does retain command text, so don't inline secrets in commands.
Does paged reading lose output?
No. Output stays in the remote tmux session and you page it with --seq, --offset, --limit and --stream stderr. Pages are measured in lines, not bytes, so a very long single line is returned in full — trim it on the server, e.g. with | cut -c1-500.
What happens when a command times out?
session exec waits 300 seconds by default (-t adjusts it); after a timeout the command keeps running in the session, so read its seq later instead of re-running it blindly. Use exec-async plus job-status/job-cancel for long or unbounded work.
Can I limit what an agent is allowed to do?
Yes, partially: --profile readonly or ops gates commands inside a session and ~/.config/assh/safety.rules (mode 0600) adds deny rules. The repo is explicit that these are guardrails against accidents, not a security boundary — the real boundary is the remote account's permissions, so pair it with a least-privilege account and --host-key-policy strict where it matters.
Is assh free?
Yes. assh is free to use and does not need a paid service.
Is assh open source?
Yes. The source code is on GitHub (izzzzzi/agent-assh) under the MIT licence.
Is assh safe to use?
FollowAgents' FARS review (Nov 15, 2026) scored assh 16/29 on trust and safety. None of the eight safety controls the review checks for was missing outright.
Is assh still maintained?
Yes. The latest commit on GitHub is from 2026-11-09, within the last 30 days. The latest release is v1.4.0 (2026-11-09).
Who makes assh?
assh is published on GitHub by the account izzzzzi. FollowAgents has not verified which person or company is behind that account.
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts