# SSH into an app

> A shell or a one-off command in a running instance, authenticated with a short-lived certificate

URL: https://pier.run/docs/ssh

```bash
pier ssh api
```

Opens a shell in one running instance of `api`'s primary target. A command after `--` runs
and returns its exit status:

```bash
pier ssh api -- env | grep -E '^(LOG_LEVEL|API_KEY)='
```

```text title="output"
API_KEY=sk_live_9f2e4c…
LOG_LEVEL=info

```

```bash
pier ssh api/canary                     # another target
pier ssh api/primary/2                  # a specific instance (the third ref segment)
pier ssh api -- ./migrate up            # a one-off with the app's own environment
```

## How access works

* `pier ssh` signs your SSH public key (`~/.ssh/id_ed25519.pub` by default, `--key` to
  change) with the platform's certificate authority and connects through `ssh.pier.run`.
  The certificate is valid for **15 minutes** and is re-issued on every invocation;
  `pier ssh-key` mints one by hand for a plain `ssh` client.
* The certificate names the workspaces where your role is **developer or above**; the
  gateway re-checks your membership on every connection, so a downgrade or removal cuts
  access at the next connection, not at certificate expiry. Viewers cannot open a shell.
* Every certificate issued is recorded as an event (`ssh.cert_sign`).
* The shell runs as the container's user in the container's filesystem; what the image
  ships is what is there. Changes do not survive a roll.

## See also

[`pier ssh`](/docs/cli/reference/ssh) · [`pier ssh-key`](/docs/cli/reference/ssh-key) ·
[Run database migrations](/docs/guides/run-database-migrations) · [Security](/docs/security)