portainerssh

README

Portainer SSH

Native shell client for Portainer containers, provided a powerful native terminal to manage your Docker containers.

• It's dead simple. like the ssh cli, you do portainerssh container_name to SSH into any containers
• It's flexible. portainerssh reads configurations from ENV, from yml or json file
• It's powerful. portainerssh searches the whole Portainer deployment, open shell into any containers from your workstation, regardless which host it belongs to
• It's smart. portainerssh uses fuzzy container name matching. Forget the container name? it doesn't matter, use "*" or "%" instead

Is it really an SSH client?

No. It's called so for historical purposes. It acts like SSH in terms of providing you shell access to your containers. Also SSH is what people are likely googling for.

Installation

Via Golang

go get github.com/devbranch-vadym/portainerssh

Binary builds

Binary builds may be found at releases page. We currently provide amd64 and arm64 builds for GNU/Linux and Mac and amd64 for Windows.

Configuration

The configuration could be provided by either config.json or config.yml in ./, /etc/portainerssh/ or ~/.portainerssh/ folders.

If you want to use JSON format, create a config.json in the folders with content:

{
  "api_url": "https://portainerssh.server/api",
  "user": "your_access_key",
  "password": "your_access_password",
  "endpoint": "10",
  "api_key": "your_api_key"
}

If you want to use YAML format, create a config.yml with content:

api_url: https://your.portainer.server/api
user: your_access_key
password: your_access_password
endpoint: 10 # Optional Portainer endpoint ID, defaults to 1.
api_key: your_api_key # Optional Portainer API key, defaults to empty. Replaces username and password.

We accept environment variables as well:

PORTAINER_API_URL=https://your.portainer.server/api
PORTAINER_USER=your_access_key
PORTAINER_PASSWORD=your_access_password

Usage

portainerssh [<flags>] <container>

? in container name matches any single character. "%" matches zero or more characters.

Examples

portainerssh my-container-name
portainerssh my-container-%
portainerssh %-container-%
portainerssh my-container-????
portainerssh -c /bin/sh my-container-name

Flags

  -h, --help            Show context-sensitive help (also try --help-long and --help-man).
      --version         Show application version.
      --api_url=""      Portainer server API URL, https://your.portainer.server/api .
      --endpoint=1      Portainer endpoint ID. Default is 1.
      --user=""         Portainer API user/accesskey.
      --password=""     Portainer API password/secret.
      --api_key=""      Portainer API key.
  -c, --command="bash"  Command to execute inside container.
  -u, --run_as_user=""  User to execute container command as.
  -w, --workdir=""      Working directory to execute command in.

Arguments

<container>  Container name, wildcards allowed

Limitations

Currently, only Docker endpoints are supported.

History

portainerssh is based on wonderful rancherssh utility by Fang Li. In fact, portainerssh is a fork and partial rewrite of rancherssh, just for Portainer.