Asteroboard on another device

Out of the box, only the computer running Asterobot can use Asteroboard. You can open it to the other devices of your home network: your phone on the sofa, a laptop in another room. For a machine that isn't on your network, such as a rented server, see Asterobot on a remote machine.

The examples call the computer running Asterobot "the Asterobot computer", and give it the address 192.168.1.20 on your network. Use yours instead.

Why it takes HTTPS

Asteroboard comes from https://asteroboard.asterobot.net, an HTTPS page. Browsers don't let an HTTPS page send plain http:// requests, except to the device the browser runs on, such as 127.0.0.1. That exception is why the default setup works on the Asterobot computer, and why a phone pointed at http://192.168.1.20:8080 stays disconnected.

Another device can still reach Asterobot in two ways:

This page sets up HTTPS. The SSH tunnel is explained in Asterobot on a remote machine, and works the same way on a home network.

Some browsers let an HTTPS page reach a plain http:// address on your local network once you give them permission. Not every browser does, so this page doesn't count on it.

Before you start

• Find the address of the Asterobot computer on your network. On Windows, ipconfig shows it as "IPv4 Address". On Linux, ip addr lists it. On macOS, it's in the network settings.
• Keep the device on the same network as the Asterobot computer.
• Read Security. Once Asterobot listens on your network, everything connected to that network can reach it, which is why the steps below add a password.

1. Add a password

The server.basicAuth setting holds user names and their passwords. When it holds at least one, Asterobot asks for a user name and a password on every request, from every browser, including the one on its own computer.

1. In Asteroboard, open Server > Config and type basicAuth in Filter settings....

2. Click Edit as JSON on the basicAuth row.

3. Replace {} with a user name and its password, each in double quotes:

   { "me": "a long password you use nowhere else" }

   For several people, separate the pairs with commas: { "me": "...", "alex": "..." }.

4. Click Apply.

The row now shows Modified and Restart required. If what you typed isn't valid JSON, Asteroboard shows That isn't valid JSON and keeps your text so you can fix it. If Asterobot refuses the value, Couldn't save appears.

2. Turn on HTTPS

On the same page, find tls and turn it on. The row shows Restart required.

The next time Asterobot starts, it serves HTTPS instead of HTTP on its port. If it has no certificate yet, it creates one first:

• The certificate is self-signed: Asterobot made it, not an authority your browsers trust. Every browser warns about it the first time.
• It only covers localhost, 127.0.0.1 and ::1. A browser that reaches Asterobot through 192.168.1.20 also reports that the certificate doesn't match the address.
• It's valid for 3 years, and Asterobot doesn't renew it. When it expires, stop Asterobot, delete the two files below, and start it again: Asterobot creates a new one.
• It's stored as tls/cert.pem, with its key in tls/key.pem, in Asterobot's data folder (Files and folders). The setting's description on the Config page mentions the cache folder, but the data folder is where they are.

Asterobot uses whatever pair of files it finds there. If you have a certificate of your own for the address you use, in PEM format, you can put it and its key in place of these two files.

3. Listen on your network

Find listenAddress, type the new value and press Enter:

0.0.0.0:8080 is the simplest. With a single address, the browser Asterobot opens as it starts goes to 127.0.0.1 and finds nothing there: open https://192.168.1.20:8080 yourself, or turn on server.skipOpenFrontend.

Keep port 8080 unless another program uses it.

4. Restart Asterobot

The three settings take effect when Asterobot starts again. Stop it with Ctrl+C in its terminal, or with Shutdown server on Server > Status, then start it the usual way (First launch).

As it starts, Asterobot opens https://127.0.0.1:8080 in the Asterobot computer's browser, unless server.skipOpenFrontend is on. In a tab that was already open, Asteroboard shows Server disconnected until the browser has opened the https:// address once, because its Server URL still starts with http://. When it does, the browser warns about the certificate and asks for a user name and a password, the same as in step 6.

5. Open the firewall

The Asterobot computer has to accept incoming connections on TCP port 8080. On Windows, the system may ask whether to let Asterobot communicate on your networks the first time it listens on them: allow it for private networks. Otherwise, add a rule for incoming TCP connections on port 8080 in your firewall, limited to your local network if it lets you.

6. Connect from the other device

1. In the device's browser, open https://192.168.1.20:8080, with the Asterobot computer's address. Type https:// in full.
2. The browser warns that the connection isn't private, or that the certificate isn't trusted. Check that the address is the Asterobot computer's, then choose to continue to the site. Most browsers keep that choice behind an option for advanced users.
3. The browser asks for a user name and a password. Enter a pair from server.basicAuth.
4. You land on Asteroboard. It saves https://192.168.1.20:8080 as its Server URL and shows Server connected.

Your browser may also ask whether asteroboard.asterobot.net can access devices on your local network. Allow it, or Asteroboard can't reach Asterobot.

Always open the address itself first, rather than typing it in Preferences straight away. The certificate warning and the password prompt only appear on a page you open. Requests from Asteroboard can't show them: they fail, and Asteroboard stays disconnected.

7. Check the connection

On Server > Status, the card under the connection status sums up the connection of the device you're on:

Preferences has a Server section too. Its Connection line shows Connected, Connecting… or Disconnected, and Test connection checks once more: Server reachable, with the round-trip time in milliseconds, or Server unreachable.

Type the address yourself

To set the Server URL by hand, for example on a device that has already accepted the certificate:

1. Open Preferences and find Server URL in the Server section.
2. Type the scheme, the address and the port, with nothing after them: https://192.168.1.20:8080.
3. Press Enter, or click outside the field. Asteroboard connects to the new address right away.
4. Click Test connection.

A browser keeps one Server URL. To come back to an Asterobot running on the device you're on, open http://127.0.0.1:8080, or type that address the same way.

When you come back later

Browsers don't keep the password and the certificate choice forever. Most forget the password when they close, and some forget the certificate choice after a while. When Asteroboard shows Server disconnected on the device while Asterobot is running, open https://192.168.1.20:8080 again, as in step 6.

Go back to the default

1. On Server > Config, click the Reset to default button, the round arrow, on the rows of listenAddress, tls and basicAuth.
2. Restart Asterobot.
3. On the Asterobot computer, open http://127.0.0.1:8080.

When it doesn't work

Asteroboard can't connect covers other connection problems.

Where to go next

• Security
• Preferences