Enable SSH on a Machine Runner

In some cases, you may wish to run your runner with SSH for debugging purposes. 

This is possible via your launch-agent-config.yml


Step 1 - Considerations before enabling SSH debugging

Task-agent runs an embedded SSH server and agent on a dedicated port when the “Rerun job with SSH” option is activated. This feature will not affect any other SSH servers or agents on the system that the self-hosted runner is installed on.

  • The host port used by the SSH server is currently fixed to 54782. Ensure this port is unblocked and available for SSH connections. A port conflict can occur if multiple machine runners are installed on the same host.

  • The SSH server will inherit the same user privileges and associated access authorizations as the task-agent, defined by the runner.command_prefix parameter.

  • The SSH server is configured for public key authentication. Anyone with permission to initiate a job can rerun it with SSH. However, only the user who initiated the rerun will have their SSH public keys added to the server for the duration of the SSH session.

  • Rerunning a job with SSH will hold the job open for two hours if a connection is made to the SSH server, or ten minutes if no connection is made, unless canceled. While in this state, the job is counted against an organization’s concurrency limit, and the task-agent will be unavailable to handle other jobs. Therefore, it is recommended to cancel an SSH rerun job explicitly (through the web UI or CLI) when finished debugging.

Step 2 - Add the flag to your launch-agent-config.yml

To add the flag to your launch-agent-config.yml, you can do the following:

auth_token: AUTH_TOKEN
advertise_addr: HOSTNAME:54782

Where HOSTNAME would need to be set to an IP or Hostname that is reachable from where you would like to SSH from.


Additional Resources

Was this article helpful?
0 out of 0 found this helpful



Article is closed for comments.