https://github.com/devbranch-vadym/portainerssh
Native SSH-like shell client for Portainer containers, provided a powerful native terminal to manage your Docker containers
https://github.com/devbranch-vadym/portainerssh
portainer portainer-api shell ssh-client
Last synced: 2 months ago
JSON representation
Native SSH-like shell client for Portainer containers, provided a powerful native terminal to manage your Docker containers
- Host: GitHub
- URL: https://github.com/devbranch-vadym/portainerssh
- Owner: devbranch-vadym
- License: apache-2.0
- Created: 2021-07-21T19:43:51.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-12-12T23:47:15.000Z (over 1 year ago)
- Last Synced: 2025-04-08T23:32:21.906Z (12 months ago)
- Topics: portainer, portainer-api, shell, ssh-client
- Language: Go
- Homepage:
- Size: 4.38 MB
- Stars: 23
- Watchers: 1
- Forks: 6
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Authors: AUTHORS.md
Awesome Lists containing this project
README
# Portainer SSH
[](https://goreportcard.com/report/github.com/devbranch-vadym/portainerssh)
[](https://pkg.go.dev/github.com/devbranch-vadym/portainerssh)
[](https://github.com/devbranch-vadym/portainerssh/releases/latest)
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
```bash
go get github.com/devbranch-vadym/portainerssh
````
### Binary builds
Binary builds may be found at [releases](https://github.com/devbranch-vadym/portainerssh/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:
```json
{
"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:
```yml
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:
```shell
PORTAINER_API_URL=https://your.portainer.server/api
PORTAINER_USER=your_access_key
PORTAINER_PASSWORD=your_access_password
PORTAINER_API_KEY=your_access_token
```
## Usage
```bash
portainerssh []
````
`?` 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 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.