# Migrate a Streamlit App from pages/ to st.navigation

Yes. An agent moves your Streamlit app from the numbered pages/ directory to an st.navigation entrypoint with titles and URLs, keeps tests passing and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-to-st-navigation/streamlit/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the pages are wired today. In an app shaped like streamlit/llm-examples, Chatbot.py is the entrypoint and five files under pages/ are ordered by a numeric prefix: `1_File_Q&A.py`, `2_Chat_with_search.py`, `3_Langchain_Quickstart.py`, `4_Langchain_PromptTemplate.py` and `5_Chat_with_user_feedback.py`. Each page sets its own `st.title` with an emoji, each has an API key `st.text_input` in the sidebar, and the sidebar labels are derived from the filenames, which is why the first page's own source link has to spell its ampersand as `%26`. requirements.txt pins `streamlit>=1.28`, and `st.navigation` with `st.Page` arrived in 1.36.0, so the pin has to move.

The migration keeps every page file where it is and changes how they are found. A new app.py calls `st.navigation` with a list of `st.Page` objects, one per file, each given the title the page already uses in `st.title`, an icon, and a short `url_path` such as `file-qa` in place of the numbered filename, and runs the selected page with `.run()`. Chatbot.py becomes a page too, with `default=True`, so the app opens where it did before. The numeric prefixes go, because order now comes from the list, and the sidebar links carried in each page's string literals are updated to the new file paths. Shared sidebar content, the Codespaces badge and the source link, moves into app.py so it is written once.

Three other files point at the old layout and the agent updates each. `.github/workflows/app-testing.yml` runs streamlit/streamlit-app-action with `app-path: Chatbot.py`, which must become app.py; .devcontainer/devcontainer.json's `postAttachCommand` runs `streamlit run Chatbot.py` and its `openFiles` list names the file; and README.md's run instructions name it. app_test.py uses `AppTest.from_file("Chatbot.py")` and `AppTest.from_file("pages/3_Langchain_Quickstart.py")`, which keep working because each page file still runs on its own, but the paths change with the renames and the agent adds one test that loads app.py and asserts the navigation renders without an exception.

The check is the repository's own. The agent installs requirements.txt and requirements-dev.txt, runs `ruff check` and `ruff format --check` with the 105-column `.ruff.toml`, and `pytest -v`, which is what the workflow runs through the app action. It starts `streamlit run app.py --server.headless true` in the sandbox and requests each `url_path` to confirm every page answers and no page is reachable at its old numbered path.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Migrate this Streamlit app from the pages/ directory to st.navigation. Read Chatbot.py, every file under pages/, app_test.py, requirements.txt, requirements-dev.txt, .ruff.toml, .pre-commit-config.yaml, .github/workflows/app-testing.yml, .devcontainer/devcontainer.json and README.md first. Create app.py that calls st.navigation with one st.Page per file, using the title each page already shows, an icon, and a short url_path instead of the numbered filename; move Chatbot.py under pages/ and make it the default page. Drop the numeric prefixes from the page filenames, keep each page runnable on its own, and move the shared sidebar links into app.py. Raise the streamlit pin in requirements.txt to a version that has st.navigation. Update app-path in the workflow, the devcontainer postAttachCommand and openFiles, the README and every source link inside the pages. Update app_test.py for the new paths and add a test that loads app.py with AppTest and asserts no exception. Run ruff check, ruff format --check and pytest -v, start the app headless and request each url_path, then open a pull request with the test output and the list of old and new URLs.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch that adds app.py, renames the five page files without their numeric prefixes, moves Chatbot.py under pages/ as the default page, raises the streamlit pin in requirements.txt, and touches app-testing.yml, devcontainer.json, README.md and app_test.py. No page's body logic changes; the diff on each page file is the rename, the removed sidebar duplicates and the corrected source link.

The description carries a table of each page's old sidebar label, its old URL path and its new `url_path`, so the team can update any bookmarks or docs that link into the app, and quotes the `pytest -v` run with the new app.py test and the ruff results. It also says which Streamlit version the pin now requires and why, with the release that introduced `st.navigation`.

Before merging, a reviewer opens the preview, checks that the sidebar order and titles match the list in app.py, that the default page is the chatbot, and that an old numbered URL no longer resolves. A follow-up on the same session can group pages into sections, which `st.navigation` takes as a dictionary, without starting over.

## Run it on every deprecation you keep postponing

This is the sort of change that waits because it touches every page at once: a `POST /o/{org}/sessions` with this prompt and the repository in `resources`, sent from the terminal, lets it happen while the team does something else. The run continues in its own sandbox after the laptop closes and the pull request is ready when someone looks. The sandbox parks with its disk when the turn ends, so a follow-up such as `add a Settings section with the API key inputs on one page` wakes it with the branch and the virtualenv still there.

With a webhook URL on the API key, Rush posts `run.completed` or `run.failed` with the `session_url` when the turn ends. A team that keeps several internal Streamlit apps can send the same prompt to each repository, one run per repository, and each run reads that app's own pages/ directory.

## Why run it on Rush?

A navigation migration is five renames, a new entrypoint and four configuration files that all have to agree, and the only way to know they agree is to start the app and click through it. The agent does that in its own sandbox, headless, and keeps the requests it made and the responses it got in the run's record, beside the pytest and ruff output.

The record is also what a reviewer reads instead of re-doing the work. The transcript shows the agent finding the `app-path` in the workflow and the `postAttachCommand` in the devcontainer, choosing each `url_path`, and checking that an old numbered path no longer answers. A reviewer who wants different slugs can say so in a follow-up and the parked sandbox applies them with the tests already in place.

## Frequently asked questions

### Do the page files still run on their own?

Yes. st.navigation only changes how the entrypoint finds them, so streamlit run pages/langchain-quickstart.py still works and AppTest.from_file on a page file still works. That is why the existing tests only need their paths updated.

### What happens to the old URLs?

They stop resolving, because a page's URL now comes from url_path on st.Page rather than from its filename. The pull request lists every old and new path so bookmarks and docs can be updated before the merge.

### Why does the streamlit pin change?

Because st.navigation and st.Page were introduced in Streamlit 1.36.0 and requirements.txt only asks for 1.28 or newer. The agent raises the lower bound and keeps it a lower bound, so Dependabot or the weekly upgrade run can still move it.

### Can pages be grouped into sections?

Yes. st.navigation takes either a flat list or a dictionary that maps a section label to a list of pages. The first pass keeps the flat list so the sidebar matches what users see today; a follow-up on the same session can add sections.

### Will it change the CI workflow?

Only the app-path input of streamlit-app-action, which must point at the new entrypoint; the ruff and pytest steps and the test results summary stay as they are. The agent runs the same checks locally before opening the pull request.

## More Streamlit jobs

- [Persist Chat History in a Streamlit App](https://getrush.ai/run/persist-chat-history/streamlit/)
- [Pin the Python Dependencies of a Streamlit App](https://getrush.ai/run/pin-python-dependencies/streamlit/)
- [Review Every Pull Request to a Streamlit App](https://getrush.ai/run/review-pull-requests/streamlit/)

## More jobs like this: Hand off a long task

- [Migrate Airflow DAGs From PythonOperator to the TaskFlow API](https://getrush.ai/run/migrate-to-taskflow-api/airflow/)
- [Migrate a Python Package to PyPI Trusted Publishing](https://getrush.ai/run/migrate-to-trusted-publishing/python/)
- [Migrate a Django REST Framework Project to uv](https://getrush.ai/run/migrate-to-uv/django-rest-framework/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
