Docs/ Operations/ Terminal Access

Terminal Access

An interactive shell inside a running app container, from the browser or from the server, and a host terminal for administrators.

Terminal of an app

The Terminal tab of an app opens a shell inside its running container, through a WebSocket bridged to docker exec with a TTY.

  1. Open the app and go to the Terminal tab.
  2. Choose the shell: sh (auto), bash, ash (Alpine) or zsh. The shell must exist in the image.
  3. Click Connect. Disconnect ends the session; closing the tab does too.
  • The shell runs as the container's user, in its working directory, with the app's environment variables, including secrets.
  • Changes to files outside a mounted volume disappear at the next deployment, as with the file manager.
  • The dashboard connects to the main container. For an app made of several services, the WebSocket /api/v1/apps/<id>/terminal accepts a service parameter.

From the CLI

sh0 ssh <app> [command] runs a command in the app's container, or /bin/sh when none is given (actual output):

Terminal (on the server)
$ sh0 ssh my-api ls /app
[*] Connecting to my-api (a17f99c5c4ac)...
server.js

$ sh0 ssh my-api        # opens /bin/sh in the container
Warning
sh0 ssh does not go through the API: it finds the container by its label and runs docker exec -it on the machine where the CLI runs. It therefore works only on the sh0 server itself, by a user allowed to use Docker, and in a real terminal (“cannot attach stdin to a TTY-enabled container because stdin is not a terminal” otherwise). It does not reach apps placed on a remote node. From your own computer, use the Terminal tab.

Host terminal

Settings, Host Access gives a terminal on the server itself, outside any container, plus a file browser of the host. The shell runs with the rights of the sh0 service, which is root on a standard installation.

Danger
The host terminal is full control of the machine: every app, every database, every secret on it. It is limited to the owner and admin roles; give those roles accordingly.

Databases

Database servers have no terminal of their own in sh0 v1.10.2. To run psql, mysql or redis-cli, open the host terminal (or SSH into the server) and use docker exec on the database container:

Terminal (on the server)
docker ps --format '{{.Names}}' | grep <database-name>
docker exec -it <container> psql -U <user> <database>

Who may open a shell

  • Terminal of an app -- developer role on the app's project.
  • Host terminal -- owner or admin role.
  • API keys -- both shells are refused to keys whose scope is not admin.
  • Revocation -- if the user's access is removed while a session is open, the session is closed.

Limitations

  • The app must be running: a stopped app has no container.
  • Images without a shell (distroless, scratch) cannot be entered.
  • The Terminal tab works for apps on a remote node through the node's connection; sh0 ssh does not.
  • Commands typed in a shell are not recorded by sh0.
Previous
Cron Jobs
Next
File Manager