SSH into sessions & VMs

1. Get access to the right session

A task may have multiple sessions. Identify the task, session, and VM you intend to access. Request permission to inspect or change that session, including an expiry and an accountable human owner. Viewing a task does not automatically authorize a shell on its VM.

Obtain a connection bundle containing the session-to-VM mapping, private hostname or IP, SSH port, OS username, approved public-key or certificate authentication, trusted host keys or host CA, and any VPN or bastion requirements. Keep your private key on your workstation; give the access administrator only the public key.

For a private VM, first connect through your approved VPN or use an authorized bastion. The VM must have an SSH service and an access rule for that path. SSH availability, certificate issuance, and session access are configured for your deployment.

2. Configure OpenSSH

Download this file as ssh_config. Replace the reserved .invalid hosts, usernames, and key paths with your connection bundle. Install the trusted host-key entries provided by your Platform Owner in ~/.ssh/entergenie_known_hosts. Verify their fingerprints through a trusted channel. A key collected with ssh-keyscan alone does not establish trust.

# Replace .invalid hosts, username, and file paths with your access bundle.
# This file contains no credentials. Keep private keys on your workstation.
Host entergenie-session
    HostName session-vm.internal.invalid
    User session-user
    Port 22
    IdentityFile ~/.ssh/entergenie_session
    IdentitiesOnly yes
    StrictHostKeyChecking yes
    UserKnownHostsFile ~/.ssh/entergenie_known_hosts
    ForwardAgent no
    ForwardX11 no
    ServerAliveInterval 30
    ServerAliveCountMax 3
    ConnectTimeout 15
    # For SSH certificates, add the supplied certificate path:
    # CertificateFile ~/.ssh/entergenie_session-cert.pub
    # Uncomment for access through the bastion below:
    # ProxyJump entergenie-bastion

Host entergenie-bastion
    HostName bastion.internal.invalid
    User access-user
    Port 22
    IdentityFile ~/.ssh/entergenie_bastion
    IdentitiesOnly yes
    StrictHostKeyChecking yes
    UserKnownHostsFile ~/.ssh/entergenie_known_hosts
    ForwardAgent no
    ForwardX11 no
    ConnectTimeout 15

# Inspect the resolved options locally; this does not connect.
ssh -F ./ssh_config -G entergenie-session

# Open the authorized session VM shell.
ssh -F ./ssh_config entergenie-session

If your deployment issues short-lived user certificates, enable CertificateFile and supply the matching private key. For a bastion, fill in its separate identity and trust information and enable ProxyJump. Agent forwarding stays disabled. See the OpenSSH configuration reference.

3. Inspect the session environment

# Run after logging in to the VM.
whoami
hostname
pwd
ps -u "$(id -u)" -o pid,etime,comm

# Close your SSH connection when finished.
exit

SSH opens an OS shell. It does not automatically attach to the agent’s conversation or resume the harness. Use the deployment’s supplied workspace path and runtime-specific attachment procedure to inspect agent work. Confirm whether that account enters an isolated session environment or a host administration shell.

Inspect first. Coordinate changes with the Task Owner and avoid editing files while the agent is modifying them. A shell can have access beyond policy-controlled tools; restrict its OS permissions and network access accordingly. Administrative access requires separate authorization.

Reconnect, stop, and revoke deliberately

If a connection drops, reconnect using the same configuration while the VM and access grant remain active. Exiting SSH disconnects your terminal; it does not stop the task, terminate the VM, or revoke access. Stopping agent work and ending VM access are separate operational actions.

Keep access records tied to the task and session. Configure any required command recording explicitly; an SSH login log is not a transcript. To revoke access, expire or remove credentials and terminate existing connections when required. Credential expiry alone may leave an established connection open. Coordinate retention and VM disposal with your deployment owner.

See OpenSSH connection and forwarding behavior and deployment ownership and data boundaries.

Troubleshooting

Use ssh -v -F ./ssh_config entergenie-session for diagnosis. Review debug output before sharing it because it can reveal internal hostnames and account details.