> For the complete documentation index, see [llms.txt](https://docs.hello-robot.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello-robot.com/stretch-4-web-teleop/readme.md).

# README

## Overview

This interface enables a user to remotely teleoperate a Stretch robot through a web browser. This website can be set up to teleoperate the robot remotely from anywhere in the world with an internet connection, or simply eyes-off teleop from the next room on a local network. The codebase is built on ROS2, WebRTC, Nav2, and TypeScript.

## Setup & Installation

The interface is compatible with the Stretch 4. It currently only supports Ubuntu 24.04 and ROS2 Jazzy. Upgrade your operating system if necessary ([instructions](https://docs.hello-robot.com/stretch4_install/docs/install_ubuntu_24.04)) and create/update the Stretch ROS2 Jazzy workspace ([instructions](https://docs.hello-robot.com/stretch4_install/docs/ros_workspace)). This will install all package dependencies and install the web teleop interface.

## Launching the Interface

First, navigate to the folder containing the codebase using:

```
colcon_cd stretch4_web_teleop
```

Next, launch the interface:

```
./launch_interface.sh
```

In the terminal, you will see output similar to:

```
Hosting Mode: local (default)
  Robot: https://localhost/local/operator/
  WiFi: https://192.168.1.14/local/operator/
```

Look for a URL like `https://<ip_address>/local/operator/`. Visit this URL in a web browser on your personal laptop or desktop to see the web interface (`https://<ip_address>/operator/` also redirects to `/local/operator/` in local mode). Ensure your personal computer is connected to the same network as Stretch. You might see a warning that says "Your connection is not private". If you do, click `Advanced` and `Proceed`.

Once you're done with the interface, close the browser and run:

```
./stop_interface.sh
```

**Note:** Only one browser can be connected to the interface at a time.

## Firebase (optional)

The interface can optionally be backed by [Firebase](https://firebase.google.com/), which adds a hosted fleet dashboard (`https://<project-id>.web.app/`), user sign-in, fleet management, and WebRTC signaling that works over the public internet so no Tailscale or ngrok tunnel is required. A single dashboard hosts immutable release rails (`/r/<tag>/operator/`) side by side, routing each robot card to the operator interface matching the git release tag checked out on that robot so a mixed-version fleet can share one dashboard. This is entirely opt-in and self-hosted: you run it in a Firebase project you create under your own Google account (the no-cost Spark plan is sufficient), and sign-in, database access, and robot ownership are all scoped to that project.

A plain `./launch_interface.sh` defaults to `local` hosting (serving the LAN door at `/local/operator/`). Once a robot is onboarded, pass `-f` / `--firebase` (or `--hosting firebase`, or set `HOSTING_MODE=firebase` in `.env` or the environment) to open Firebase signaling in addition to the robot's local LAN door. To override a standing `HOSTING_MODE=firebase` for a single local-only run, pass `--local` or `--hosting local` (a bare `--hosting` with no argument also defaults to `local`). Run `./launch_interface.sh --dry-run` to validate the installation and print the resolved launch configuration and provenance without starting ROS2 or PM2. See [Firebase Setup and Multi-Rail Hosting](https://docs.hello-robot.com/stretch-4-web-teleop/src/pages/operator/tsx/storage_handler.md) for instructions to create a Firebase project, onboard robots, and manage release rails.

## Feature flags

Optional features are declared in [`features.json`](https://github.com/hello-robot/stretch4_web_teleop/tree/main/features.json), which is the single source of truth for each flag's name, default, and description:

```json
{
    "<flag_name>": {
        "enabled": false,
        "description": "..."
    }
}
```

Edit `features.json` to change a flag's default. To override a flag for a single run without editing the file, set `FEATURE_<NAME>` in the environment (`<NAME>` is the flag name upper-cased), which accepts `1`/`0`, `true`/`false`, `yes`/`no` or `on`/`off`:

```
FEATURE_<NAME>=1 ./launch_interface.sh
```

Each flag is read at launch by `server.js`, which registers the routes it gates only when it is on, and by `webpack.config.js`, which substitutes it into the bundle as `process.env.FEATURE_<NAME>`. Changing it therefore takes effect on the next `./launch_interface.sh`. Grep for `@flag <flag_name>` to find every seam for a given flag.

## Using the Interface Remotely

**WARNING: This is prototype code and there are security issues. Deploy this code at your own risk.**

This section covers remote access in `local` hosting mode, where the interface is served from the robot and needs a tunnel to reach the public internet. In `firebase` hosting mode your own Firebase dashboard already reaches the robot from anywhere, and none of the setup below is needed.

We recommend setting up the interface for remote use using [ngrok](https://ngrok.com/docs/what-is-ngrok/). First, create an account with `ngrok` and follow the Linux installation instructions in the `Setup & Installation` tab in your ngrok account dashboard.

Navigate to the `Domains` tab and click `Create Domain`. ngrok will automatically generate a domain name for your free account. You will see a domain similar to `deciding-hornet-purely.ngrok-free.app`. Follow the interface launch instructions and then start the ngrok tunnel by running the following command (replace `<NGROK_DOMAIN>` with your account's domain and `user:password` with a secure username and password):

```
ngrok http --basic-auth="user:password" --domain=<NGROK_DOMAIN> 443
```

In your browser, open `https://<NGROK_DOMAIN>/operator` to see the interface. You will then be prompted to enter the appropriate username and password. Note, anyone in the world with internet access can open this link.

### Storing Ngrok Tunnel Configuration

To store this configuration, open the ngrok config file:

```
ngrok config edit
```

Add the following configuration to the file. Make sure to update `<NGROK_AUTH_TOKEN>`, `<NGROK_DOMAIN>`, and `admin:password` with the appropriate values.

```
authtoken: <NGROK_AUTH_TOKEN>
version: 2
tunnels:
    stretch-web-teleop:
        proto: http
        domain: <NGROK_DOMAIN>
        addr: 443
        basic_auth:
          - "admin:password"
        host_header: rewrite
        inspect: true
```

Now run `ngrok start stretch-web-teleop` to start the tunnel and navigate to `https://<NGROK_DOMAIN>/operator`. You will then be prompted to enter the appropriate username and password.

## Developer Docs

The following primers provide codebase architecture, contracts, and invariants for developers and coding agents:

| Primer                                                                                                         | Description                                                                                                                                                                                                                                                           |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Software Architecture](https://docs.hello-robot.com/stretch-4-web-teleop/src/primer_software_architecture.md) | Overview of the system architecture — how the fleet lobby, operator browser, robot browser, ROS2, WebRTC, and signaling transports fit together, plus the `MobileOperator` render logic flow.                                                                         |
| [Launching the Interface](https://docs.hello-robot.com/stretch-4-web-teleop/src/primer_launch.md)              | How `launch_interface.sh` resolves `HOSTING_MODE`, validates the installation and Firebase readiness, prints the launch manifest, and brings up ROS2, the HTTPS server, and the robot browser.                                                                        |
| [Multi-Rail Hosting & Lobby](https://docs.hello-robot.com/stretch-4-web-teleop/src/primer_rails.md)            | How self-hosted Firebase Hosting serves the fleet lobby (`/`) alongside immutable release rails (`/r/<tag>/operator/`), webpack rail builds, release tag lockstep, deploy guards, RTDB rules compatibility, and test suites.                                          |
| [Operator Page](https://docs.hello-robot.com/stretch-4-web-teleop/src/primer_operator.md)                      | Deep dive into the operator page codebase — directory layout, the shared layer (`commands`, `RemoteRobot`, `util`, `webrtcconnections`, `signaling`), the entry point (`index.tsx`), function providers, component folders, storage handler, and adding new features. |
| [Robot Page](https://docs.hello-robot.com/stretch-4-web-teleop/src/primer_robot.md)                            | Deep dive into the robot page codebase — the `Robot` class, ROS2 subscriptions/services/actions, robot modes, joint state processing, video streams, and bidirectional data flow between ROS2 and the operator browser.                                               |

## Contributing

* This repository uses pre-commit hooks to enforce consistent formatting and style.
  * Install pre-commit: `python3 -m pip install pre-commit`
  * Install the hooks locally: `cd` to the top-level of this repository and run `pre-commit install`.
  * Moving forward, pre-commit hooks will run before you create any commit.
* Run automated Hosting, routing, and Realtime Database security suites before opening a pull request:
  * Offline unit and release-guard suites (also run in CI): `npm test` (alias for `npm run test:offline`)
  * Local Firebase Hosting and Database emulator suites (requires `java` on `PATH`): `npm run test:emulated`

## Troubleshooting

### Collecting logs

First, ensure that your robot has the latest version of Web Teleop by [updating your ROS workspace](https://docs.hello-robot.com/0.3/installation/ros_workspace/).

Then, launch the program normally, and if you see "FAILURE. COULD NOT LAUNCH WEB TELEOP.", then locate the zipped-up logs file and send them to Hello Robot Support (<support@hello-robot.com>).

To locate the logs, open a file explorer, go into "Home", go into "stretch\_user", go into "log", go into "web\_teleop", locate the folder with the latest timestamp, and send "stretch4\_web\_teleop\_logs.zip" to the support team.

### Manage PM2 logs

PM2 outputs logs to `~/.pm2/logs`. You can configure log rotation using [pm2-logrotate](https://github.com/keymetrics/pm2-logrotate) so the directory has a set size limit:

```bash
pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 10M # Clamps each log file to 10M
```

The `pm2 flush` command is also available but will delete every log file in `~/.pm2/logs`.

## Licenses

The following license applies to the contents of this directory written by Vinitha Ranganeni, Noah Ponto, authors associated with the University of Washington, and authors associated with Hello Robot Inc. (the "Contents"). This software is intended for use with Stretch ® mobile manipulators produced and sold by Hello Robot ®.

Copyright 2023 Vinitha Ranganeni, Noah Ponto, the University of Washington, and Hello Robot Inc.

The Contents are licensed under the Apache License, Version 2.0 (the "License"). You may not use the Contents except in compliance with the License. You may obtain a copy of the License at

<http://www.apache.org/licenses/LICENSE-2.0>

Unless required by applicable law or agreed to in writing, the Contents are distributed under the License are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

\============================================================

Some of the contents of this directory derive from the following repositories:

<https://github.com/hello-robot/stretch\\_web\\_teleop>

<https://github.com/hello-robot/stretch\\_web\\_interface>

<https://github.com/hcrlab/stretch\\_web\\_interface>

<https://github.com/hcrlab/stretch\\_teleop\\_interface>

Text from relevant license files found in these repositories.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hello-robot.com/stretch-4-web-teleop/readme.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
