SSH and web shell

Use SSH or the dashboard shell to inspect a running service instance. Commands execute in the live workload and can read its environment, secrets, and data. Use logs first when a shell is unnecessary.

Requirements​

Shell access is available for eligible paid web services, private services, and background workers. The service must be unsuspended, running a live image, and have a Ready instance. Static sites, cron jobs, free services, and managed datastores do not use this running-service shell workflow.

The installation needs its SSH/web-shell gateway configured. Your account needs sensitive-resource access, normally developer/admin, plus any applicable policy checks. Permission to restart a service is insufficient. Uploading an SSH key also does not grant access to a workspace you cannot otherwise use.

The application image must contain the shell or executable you want to run. A minimal image without a shell will not become a full Linux toolbox merely because the gateway is reachable.

Register a public key​

Use your dashboard account's SSH key settings to add an existing public key, or generate a dedicated pair locally if needed:

ssh-keygen -t ed25519 -f ~/.ssh/bex_service -C bex-service-access

Choose a new filename rather than overwriting an existing key. Upload only the .pub file; keep the private key on your machine.

The API provides GET /v1/ssh-keys, POST /v1/ssh-keys with name and publicKey, and DELETE /v1/ssh-keys/{id}. Key enrollment is restricted to eligible direct human callers. A machine API key or third-party OAuth agent cannot enroll another durable credential for itself. See API authentication.

Connect to the service​

After CLI login, choose your workspace and use a returned service ID:

bex workspace set YOUR_WORKSPACE_ID
bex ssh YOUR_SERVICE_ID

For a direct OpenSSH connection, use the service's returned serviceDetails.sshAddress, not a hostname inferred from its display name or public web URL. Supply your private key with ssh -i if it is not already selected by your SSH configuration or agent. Verify an unfamiliar gateway's host key through the platform operator; do not disable host-key checking to bypass a connection error.

A bare service target can select any Ready replica. Inspect GET /v1/services/{id}/instances and use the returned instance identifier when you need a particular replica. Instances can disappear during deployments or scaling, so refresh the list if a target is no longer available.

Use the dashboard shell​

Open the service's Shell view and select an instance when offered. The dashboard obtains a short-lived connection ticket and the gateway checks access again when opening the session. No private SSH key needs to be pasted into the browser.

If a ticket expires before connection, reopen the shell to obtain a fresh one. Do not reuse a captured ticket as a permanent automation credential or share it in a support report.

Session limits and troubleshooting​

Shell changes to the container filesystem are ephemeral unless written to a mounted persistent disk or an external datastore. Such persistent writes affect real application data. Make durable code/configuration changes in the repository or platform settings and deploy them normally.

Running-service SSH is not a generic bastion: App targets do not provide SFTP subsystems or a general forwarding service. Do not infer support for ephemeral instances or hosted one-off jobs from imported CLI options. Agent-session sandboxes are a separate product with different capabilities.

For database access, use Postgres connections or Key Value connections. For a command that should gate each release, use a pre-deploy command.