We use some essential cookies to make our website work.

We use optional cookies, as detailed in our cookie policy, to remember your settings and understand how you use our website.

树莓派 官方文档

Raspberry Pi Connect (Beta)

Introduction

hero

To use Connect, install the Connect software and link your device with an account on your Raspberry Pi. Then visit connect.raspberrypi.com to access the desktop or a shell running on your Raspberry Pi in a browser window.

Connect uses a secure, encrypted connection. By default, Connect communicates directly between your Raspberry Pi and your browser. However, when Connect can’t establish a direct connection between your Raspberry Pi and your browser, we use a relay server. In such cases, Raspberry Pi only retains the metadata required to operate Connect.

Connect is currently in the Beta phase of development.

Note
To use Connect, your Raspberry Pi must run Raspberry Pi OS Bookworm or later.

Install

$ sudo apt update
$ sudo apt full-upgrade

Run the following command on your Raspberry Pi to install Connect:

$ sudo apt install rpi-connect

You can also install Connect from the Recommended Software application.

After installation, use the rpi-connect command line interface to start Connect for your current user:

$ rpi-connect on

Alternatively, click the Connect icon in the menu bar to open a dropdown menu and select Turn On Raspberry Pi Connect:

turn on connect

Connect Lite

We distribute an alternate Lite variant of Connect that only supports remote shell access, with no ability to screen share.

Run the following command on your Raspberry Pi to install Connect Lite:

$ sudo apt install rpi-connect-lite

After installation, use the rpi-connect command line interface to start Connect for your current user:

$ rpi-connect on

Enable user-lingering to make your device accessible even when your user account isn’t logged in.

Tip
Lite commands use the same rpi-connect name as the full version of Connect. rpi-connect-lite is just a package name.

Manually start and stop Connect

To start Connect from the command line, run the following command:

$ rpi-connect on

To stop Connect, run the following command:

$ rpi-connect off

via the Raspberry Pi Desktop

If you’re using the Connect plugin for the menu bar, clicking "Turn On Raspberry Pi Connect" for the first time will open your browser, prompting you to sign in with your Raspberry Pi ID:

browser sign in

Alternatively, you can choose "Sign In…​" from the dropdown menu:

sign in

If you don’t already have a Raspberry Pi ID, click create one for free to create one.

via the command line

Use the following command to generate a link that will connect your device with your Connect account:

$ rpi-connect signin

This command should output something like the following:

Complete sign in by visiting https://connect.raspberrypi.com/verify/XXXX-XXXX

Visit the verification URL on any device and sign in with your Raspberry Pi ID to link your device with your Connect account.

Finish linking your Raspberry Pi

After authenticating, assign a name to your device. Choose a name that uniquely identifies the device. Click the Create device and sign in button to continue.

new device

You can now remotely connect to your device. The Connect icon in your menu bar will turn blue to indicate that your device is now signed in to the Connect service. You should receive an email notification indicating that a new device is linked to your Connect account.

sign in email
Warning
If you receive an email that says a device that you do not recognise has signed into Connect, change your Raspberry Pi ID password immediately. Remove the device from Connect to permanently disassociate it from your account. Consider enabling two-factor authentication to keep your account secure.

Click the Connect icon in your menu bar to open the Connect menu. This menu allows you to turn Connect on and off, sign in and out, and allow or disallow remote access methods.

Tip
Connect signs communication with your device serial number. Moving your SD card between devices will sign you out of Connect.

Access your Raspberry Pi device

Now that your device appears on your Connect dashboard, you can access your device from anywhere using only a browser. Connect provides multiple ways to interact with your device remotely.

Screen sharing

Connect includes the ability to share your device’s screen in a browser. Use the following instructions to share your device’s screen.

Note
Screen sharing requires the Wayland window server. Raspberry Pi OS Bookworm and later use Wayland by default. Screen sharing is not compatible with Raspberry Pi OS Lite or systems that use the X window server.

Visit connect.raspberrypi.com on any computer.

Connect redirects you to the Raspberry Pi ID service to sign in. After signing in, Connect displays a list of linked devices. Devices available for screen sharing show a grey Screen sharing badge below the name of the device.

devices

Click the Connect via button to the right of the device you would like to access. Select the Screen sharing option from the menu. This opens a browser window that displays your device’s desktop.

waiting for screen sharing

You can now use your device as you would locally. For more information about the connection, hover your mouse over the padlock icon immediately to the right of the Disconnect button.

screen sharing
Tip
Use the Copy from remote and Paste to remote buttons above your desktop to transfer text between your local and remote clipboards.

Once connected, a green dot appears next to the Screen sharing badge in the Connect dashboard. This indicates an active screen sharing session. Hover to see the current number of screen sharing sessions.

screen sharing in progress

The Connect icon in the system tray turns purple and displays a closed circle when a screen sharing session is in progress. A desktop notification will appear whenever a screen sharing session starts.

screen sharing notification

Stop screen sharing

To close a screen sharing session, click the Disconnect button above your desktop.

screen sharing ended

Disallow screen sharing

To turn off screen sharing, click the Connect icon in the menu bar and unselect Allow Screen Sharing. Your device remains signed into Connect, but you won’t be able to create a screen sharing session from the Connect dashboard.

disallow screen sharing

Alternatively, you can disallow screen sharing with the following command:

$ rpi-connect vnc off

In the Connect dashboard, the Screen sharing badge and the Screen sharing option in the Connect via menu will appear crossed-out.

screen sharing disabled

To re-enable screen sharing, do one of the following:

  • click the Connect icon in the menu bar and select Allow Screen Sharing

  • run the following command:

    $ rpi-connect vnc on

Remote shell

Connect includes the ability to start a shell running on your device from a browser. Use the following instructions to access the remote shell.

Visit connect.raspberrypi.com on any computer.

Connect redirects you to the Raspberry Pi ID service to sign in. After signing in, Connect displays a list of linked devices. Devices available for remote shell access show a grey Remote shell badge below the name of the device.

devices

Click the Connect via button to the right of the device you would like to access. Select the Remote shell option from the menu. This opens a shell session on your device.

waiting for remote shell

You can now use your device as you would locally.

remote shell
Tip
On some operating systems, the browser intercepts key combinations like Ctrl+Shift+C and Ctrl+C. Instead, you can use the right click menu or Ctrl+Insert to copy and Shift+Insert to paste.

Once connected, a green dot appears next to the Remote shell badge in the Connect dashboard. This indicates an active remote shell session. Hover to see the current number of remote shell sessions.

remote shell in progress
Tip
Every remote shell connection creates a brand new connection, just like SSH. To persist background commands and configuration across multiple sessions, use screen or tmux.

The Connect icon in the menu bar turns purple and displays a closed circle when a remote shell session is in progress. A desktop notification will appear whenever a remote shell session starts.

remote shell notification
Tip
The CONNECT_TTY environment variable indicates that a session uses a remote shell provided by Connect.

End your remote shell session

To close a remote shell session, run the exit command or close the window.

remote shell ended

Disallow remote shell access

To turn off remote shell access, click the Connect icon in the menu bar and unselect Allow Remote Shell Access. Your device remains signed into Connect, but you won’t be able to create a remote shell session from the Connect dashboard.

disallow remote shell

Alternatively, you can disallow remote shell access with the following command:

$ rpi-connect shell off

In the Connect dashboard, the Remote shell badge and the Remote shell option in the Connect via menu will appear crossed-out.

remote shell disabled

To re-enable remote shell access, do one of the following:

  • click the Connect system tray icon and select Allow Remote Shell Access

  • run the following command:

    $ rpi-connect shell on

Enable remote shell at all times

Connect runs as a user-level service, not as root. As a result, Connect only works when your user account is currently logged in on your device. This can make your device unreachable if you reboot with automatic login disabled. To continue running Connect even when you aren’t logged into your device, enable user-lingering. Run the following command from your user account to enable user-lingering:

$ loginctl enable-linger
Tip
We recommend enabling user-lingering on all headless Raspberry Pi OS Lite setups to prevent your device from becoming unreachable after a remote reboot.

Manage devices

The Connect dashboard lists all of the devices linked with your Connect account and shows you the various ways you can access them.

devices

Click on a device name to open the device details page. This screen provides low-level information about your device. You can also edit the device name or remove the device from Connect.

device

Deleting a device from Connect automatically signs you out of Connect on the device. The Connect icon in the menu bar turns grey and the menu only provides a Sign In…​ option.

Update

To update to the latest version of Connect, run the following command:

$ sudo apt update
$ sudo apt install --only-upgrade rpi-connect
Tip
If you installed Connect Lite, replace rpi-connect with rpi-connect-lite in the above command.

Disconnect a device from Connect

Run the following command on your device to sign out of your Raspberry Pi ID, which will disable your device on the Connect screen:

$ rpi-connect signout

Alternatively, click the Connect icon in the menu bar and click "Sign Out".

Tip
To fully remove a device from your Connect account, remove it from the Connect dashboard.

Uninstall

Run the following command to stop and remove Connect from a device:

$ sudo apt remove --purge rpi-connect
Tip
If you installed Connect Lite, replace rpi-connect with rpi-connect-lite in the above command.

After uninstalling, the serial number of the device remains linked with your Connect account. The device still appears in the Connect dashboard, but can’t be used for remote access. If you install Connect again, even with a different SD card, on the same device, it will reuse the existing device name in the Connect dashboard.

To sever the link between a device and a Connect account, remove the device from the list of devices in the Connect dashboard.

Troubleshooting

Common issues

Screen sharing not available

If Connect states that screen sharing is unavailable, it cannot connect to the dedicated Connect WayVNC service.

To find out more about the cause of the issue, run the following commands to check the status of the Connect WayVNC service:

$ systemctl --user status rpi-connect-wayvnc
$ journalctl --user --follow --unit rpi-connect-wayvnc

If the service fails to start or doesn’t exist, ensure that your environment meets the following criteria:

  1. You use rpi-connect version 1.1.0 or later.

  2. You do not use rpi-connect-lite, which lacks screen sharing support.

  3. You use a Wayland compositor such as wayfire or labwc, not X. You can control this setting via raspi-config's Advanced Options.

  4. You use a desktop environment supported by WayVNC, e.g. Raspberry Pi Desktop. For instance, using KDE switches your Wayland compositor to kwin, which is unsupported.

  5. You have an active graphical desktop session running as the same user as the one you signed into. For most, this means enabling "Desktop Autologin" via raspi-config's System Options.

Can’t connect after restarting or ending SSH session

Connect runs as a user-level service and is therefore only available if there is an active session for the user signed into the service. If you want remote shell access without also running another login session, enable user-lingering for your user, which will keep Connect running at all times.

For screen sharing, Connect can only share an existing graphical desktop session: it does not create entirely new sessions. There must already be a desktop session in progress. To start such a session automatically on boot, enable Desktop Autologin via raspi-config's System Options.

Networking and firewall issues

Connect usually communicates between devices without requiring changes to your network or firewall. However, especially restrictive networks can sometimes block Connect communication. To help debug problems with such networks, rpi-connect and rpi-connect-lite include the rpi-connect doctor command. rpi-connect doctor runs a series of tests to check that Connect communication functions properly on your network.

To run these tests on your device, run the following command:

$ rpi-connect doctor

If Connect can communicate properly on your network, you should see output similar to the following:

✓ Communication with Raspberry Pi Connect API
✓ Authentication with Raspberry Pi Connect API
✓ Peer-to-peer connection candidate via STUN
✓ Peer-to-peer connection candidate via TURN

If Connect can’t communicate properly on your network, you’ll see an "x" instead of a check next to the failing test case. Ask your network administrator to enable the following connections on your network:

  • unauthenticated HTTPS requests to the Raspberry Pi Connect API on port 443 of api.connect.raspberrypi.com

  • authenticated requests to the Raspberry Pi Connect API on port 443 of api.connect.raspberrypi.com

  • requests to Raspberry Pi Connect STUN or TURN servers on UDP port 3478 of all of the following:

    • stun.raspberrypi.com

    • turn1.raspberrypi.com

    • turn2.raspberrypi.com

    • turn3.raspberrypi.com

  • requests to Raspberry Pi Connect TURN servers on TCP ports 3478 or 443 of all of the following:

    • turn1.raspberrypi.com

    • turn2.raspberrypi.com

    • turn3.raspberrypi.com

  • requests to Raspberry Pi Connect TURN servers on UDP ports 3478, 443, or 49152 → 65535 of all of the following:

    • turn1.raspberrypi.com

    • turn2.raspberrypi.com

    • turn3.raspberrypi.com

View Connect status

To view the current status of the Connect service, run the following command:

$ rpi-connect status

You should see output similar to the following:

Signed in: yes
Screen sharing: allowed (0 sessions active)
Remote shell: allowed (0 sessions active)

The output of this command indicates whether or not you are currently signed in to Connect, as well as the remote services enabled on your Raspberry Pi.

If you see output including "Raspberry Pi Connect is not running, run rpi-connect on", run rpi-connect on to start Connect.

Enable enhanced logging

You can enable debug logging for both rpi-connect and its dedicated WayVNC server for a detailed account of local operations on your Raspberry Pi.

Enable enhanced logging in rpi-connect

Override the rpi-connect service definition with the following command:

$ systemctl --user edit rpi-connect

Enter the following lines of configuration between the comments:

[Service]
ExecStart=
ExecStart=/usr/bin/rpi-connectd -socket %t/rpi-connect-wayvnc.sock -v
Note
You need both lines that begin with ExecStart=.

Finally, restart Connect with the following command:

$ rpi-connect restart

Enable enhanced logging in the dedicated wayvnc server

Override the rpi-connect-wayvnc service definition with the following command:

$ systemctl --user edit rpi-connect-wayvnc

Enter the following lines of configuration between the comments (including the -Ldebug flag):

[Service]
ExecStart=
ExecStart=/usr/bin/rpi-connect-env /usr/bin/wayvnc --config /etc/rpi-connect/wayvnc.config --render-cursor --unix-socket --socket=%t/rpi-connect-wayvnc-ctl.sock -Ldebug %t/rpi-connect-wayvnc.sock
Note
You need both lines that begin with ExecStart=.

Finally, restart Connect with the following command:

$ rpi-connect restart

View Connect logs

To view logs for the Connect service and its dedicated WayVNC server, run the following command:

$ journalctl --user --follow --unit rpi-connect --unit rpi-connect-wayvnc