assh
An SSH workflow helper that gives LLM agents persistent tmux sessions and pageable, context-friendly output.
- Source repo
- izzzzzi/agent-assh
- Stars
- ★ 22
- Last updated
- 11d ago
- License
- MIT
- Primary language
- Go
- FA score
- 65/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude CodeChatGPT (Unsupported)
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- 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.
- 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.
- 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.
- Debugging that requires a persistent shell where the working directory and environment survive between steps.
- Piping a build or setup script to the remote host via stdin, or moving large files with
transfer put/get/syncinstead of shell redirects. - Running the same diagnostic across several hosts at once with
fleet execand spotting failures from the aggregated result. - 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-asshArchives 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/releasesHow 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_PASSUse 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 f7a2b3c4Background 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/pathInstall the agent skill, e.g. for Claude Code and Codex:
/plugin marketplace add izzzzzi/agent-assh
/plugin install assh@asshcodex plugin marketplace add izzzzzi/agent-assh
codex plugin add assh@asshWhat are this agent's strengths and limitations?
- One
connectcall handles key creation, optional password-based first login, tmux install, session GC and session creation, and hands back runnablenext_commands. - The metadata-then-page output model (
seq,--limit,--offset) keeps large output out of the agent context, withaudit --savingsreporting 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-cancelcover work that outlives the default 300-secondsession exectimeout. - One CLI spans sessions, transfers, port forwarding, multi-host fan-out, host scanning, and documented plugin/skill installs for several terminal agents.
- The safety classifier and profiles are pattern-based guardrails only; the README states they ignore scripts passed via
--stdin, interpreters, and cases likedocker rmorDROP DATABASE. - Requires the system OpenSSH client;
transfer syncadditionally needs rsync andtransfer list/statneed GNU find/stat, otherwise returningunsupported_remote. - tmux sessions target Unix-like remote hosts, v1 has no interactive password prompts, and
--force-ptymerges 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 execat a time per session is advised because commands share a single shell, and profile restrictions do not apply toexec,transferorfleet.
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?
Why each dimension lost points
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.
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.
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.
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.
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.
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.
- 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.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
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 pluginView on GitHub ↗ -
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 ↗ -
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 outputView on GitHub ↗
FAQ
Does assh call an LLM itself?
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?
--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?
--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?
Is assh open source?
Is assh safe to use?
Is assh still maintained?
Who makes assh?
Thanks — we use this to improve the page.