assh

assh is an agentic SSH toolkit for stateful, token-efficient remote execution.

assh provides a typed Python package and CLI for:

• repo and global target resolution
• stateful remote execution with output shaping
• environment-set injection
• reusable workflow scripts
• Docker and Kubernetes helpers
• SSH-driven remote worker deployment and task lifecycle management

Status

v0.1.0 is the first MVP release.

The current release includes:

• async-first SSH transport with persisted remote working directory state
• JSON, XML, and Rich output from a shared canonical result model
• repo-local and global SQLite-backed target and env-set state
• push and fetch helpers for remote file transfer
• deployable remote worker support for long-running task lifecycle control
• automated scenario coverage derived from Astra and Nexus workflows
• a guarded real-VM validation suite exercised against root@192.237.244.107

Install

Local development

uv sync --group dev
uv run assh --help

Install as a tool

uv tool install --from . assh

Quick start

uv run assh init
uv run assh target add vm root@192.237.244.107
uv run assh run "uname -a && whoami && pwd" --target vm

Persist a remote workspace across commands:

uv run assh chain \
  --target vm \
  --step "mkdir -p /tmp/assh-demo" \
  --step "cd /tmp/assh-demo" \
  --step "printf 'hello from assh\n' > note.txt"

uv run assh run "pwd && cat note.txt" --target vm

Use env sets with automatic redaction:

uv run assh env set deploy APP_ENV production
uv run assh env set deploy API_TOKEN super-secret-token
uv run assh env enable deploy
uv run assh run "printf 'APP_ENV=%s\nTOKEN=%s\n' \"\$APP_ENV\" \"\$API_TOKEN\"" --target vm

Use the remote worker for long-running tasks:

uv run assh worker deploy --target vm
uv run assh task start "printf 'start\n'; sleep 10; printf 'done\n'" --target vm
uv run assh task list --target vm
uv run assh task logs <task-id> --target vm

Validation

Core local checks:

uv run ruff check .
uv run mypy src
uv run pytest
uv build

Guarded real-VM validation:

ASSH_E2E_ENABLE=1 \
ASSH_E2E_TARGET=root@192.237.244.107 \
ASSH_E2E_WORKDIR=/tmp/assh-scenarios \
ASSH_E2E_STRICT_HOSTKEY=accept-new \
uv run pytest -m e2e tests/e2e/test_vm_manual.py -vv

Documentation

• AGENTS.md is the tracked repo entrypoint.
• docs/ contains the public Mintlify docs.
• docs/examples.mdx contains copy-paste usage examples.

Release workflow

• .github/workflows/ci.yml runs lint, typecheck, tests, and package builds on pushes and pull requests.
• .github/workflows/release.yml verifies the tagged revision before publishing to PyPI.