This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Debug a workflow run with SSH
Edit page
Learn how to open an SSH session on the worker that runs a job in Expo Workflows.
SSH access is experimental. Its commands, flags, and behavior may change.
An SSH session gives you an interactive shell on the worker that runs a job. Use it to inspect a job while it runs or after it fails. For example, you can:
- Inspect the files that a failed step created.
- Run a failing command again on the same worker, with the same tools and environment variables.
- Check the versions of the tools that the job uses.
3 requirements
3 requirements
1.
Install or update EAS CLI:
2.
The ssh command must be available in your terminal.
3.
To connect, your role on the project's account must be Developer, Release Manager, Admin, or Owner. A member with the Runner role can start a run with --ssh but cannot connect.
Start a run with SSH
Add the --ssh flag when you run a workflow:
Each job that runs on a worker opens an SSH session before its steps start. Jobs that run without a worker, such as slack and require-approval, do not open a session. If the run calls reusable workflows, their jobs also open sessions. If you re-run the workflow on the Expo dashboard, the jobs that run again also open sessions.
You can enable SSH only when you start a run with eas workflow:run. To debug a workflow that GitHub started, run the same workflow file at the same Git reference:
Connect to a job
-
Open the job logs on the workflows page of your project, or with
eas workflow:logs. -
Find the Start SSH session step. It prints the command to connect:
SSH session ready. Connect with: eas workflow:ssh ID -
Run that command in your terminal:
Terminal
If the session is not ready yet, the command waits for it.
The job does not wait for you to connect. Its steps continue to run while you are connected.
When you connect, the shell starts in the build directory, ~/workingdir/build. Your project files are in this directory after the Prepare project step in a build job, or after the eas/checkout step in a custom job. These steps replace the directory. If you connected before the step ran, run cd ~/workingdir/build to see your project files.
Keep the session open after the job ends
The session is open for the whole job. When the job ends, the session stays open while you are connected. It closes when no one is connected.
To get time to connect after the job ends, for example after a step fails, set --ssh-idle-timeout in seconds. The value must be from 0 to 3600. The default is 0.
With this value, the session closes after 10 minutes with no client connected. Each time the last client disconnects, the 10 minutes start again.
While the session is open after the job ends, the job and the run stay in progress. The job gets its final status, such as Failure, when the session closes. This time uses build minutes and a concurrency slot on your account.
If you cancel the workflow run, its open sessions close without waiting for the idle timeout. The jobs that still have an open session end with the Canceled status.
Connect with another SSH client
To connect with a different SSH client or from a script, print the connection command:
The output contains a token. Anyone who has the token can connect to the session until it closes. Do not share the output or save it in logs.
The output also shows a second command. Use it if your network blocks SSH connections.