Client Quickstart

Set up a client to connect to an Excalibur server.

important

This quickstart assumes that a server is already set up.

Installation

Windows

The Windows client can be obtained as an .exe installer.

1. Download the .exe installer from here.
2. Double-click the .exe file to begin installation.
3. After installation completes, Excalibur should open automatically.

macOS

The macOS client can be obtained as either a .dmg file or a zipped .app file.

• Disk Image (.dmg):
  1. Download the .dmg file from here.
  2. Double-click the .dmg file to open it.
  3. Drag the Excalibur application into the Applications folder.
• Zipped Application (.zip):
  1. Download the zipped .app file from here.
  2. Extract the downloaded .zip file to obtain the Excalibur application.

Double-click the Excalibur application to launch it.

"Excalibur Not Opened"

Due to Apple's security policy, you might see a notification that "Apple could not verify "Excalibur" is free of malware".

You will need to manually allow the app to open. On recent macOS versions, this can be done by following these steps:

1. Open System Preferences > Privacy & Security.
2. Scroll down until you see a message like "Excalibur was blocked to protect your Mac."
3. Click "Open Anyway". You might need to enter an administrator's password.
4. Excalibur should open.

Subsequent launches should not need to repeat this process.

Linux

The Linux client can be obtained as either a .deb file or an .AppImage file.

.deb

1. Download the .deb package from here.
2. In the same directory as the downloaded file, run

   sudo apt install ./<file>.deb

   where <file> is the name of the downloaded file.
3. Start Excalibur by running the command

   excalibur-electron

   in a terminal.

.AppImage

An AppImage allows you to run Excalibur without installation or the need for root rights.

1. Download the .appimage package from here.
2. Make the AppImage executable by running

   chmod a+x ./<file>.AppImage

   where <file> is the name of the downloaded file.
3. Start Excalibur by running

   ./<file>.AppImage

Android

The Android client is an Android app in the form of an .apk file.

1. Download the Android app from here; you should now have an .apk file.
2. Copy the .apk file to your Android device.
3. Install the app on your Android device.
   • Do note that you may need to enable installation from unknown sources on your Android device in order to install the .apk file.

warning

It is recommended to disable the installation of unknown sources on your Android device after installing the app.

Progressive Web App (PWA)

The PWA distributable is simply a zip file containing all the web assets to run a PWA.

1. Download the PWA distributable from here.
2. Extract the contents of the zip file to a folder of your choice. It should contain a dist folder. This is the PWA.

By running a HTTP server and serving the files in dist, you can access the PWA. For example, using Python, you can run

python -m http.server 8080

within the dist folder to serve the files. Navigating to http://localhost:8080 should bring you to the PWA.

warning

The above Python command is not safe for production use. It is only for trying out Excalibur via a PWA.

Onboarding

Upon opening the app, you will be greeted with the following screen:

Click on "Continue".

At this stage, one of two things might happen. If you started the server on localhost/127.0.0.1 with the default port (i.e., 52419), you should be automatically redirected to the login page. What happened is that the app autodetected a running Excalibur server instance on the host and thus set the server URL automatically. In this case, you can go straight to creating a new user.

Otherwise, you should see a screen that allows you to enter a server URL:

Enter the server URL in the provided text field. For example, if you are running the server on your local machine with port 8888, enter http://localhost:8888 and click "Continue".

Creating a User

You should now see a login screen.

Click on the "Sign Up" hyperlink. You should now see this page.

Enter your desired username and password into the fields. To create your user on the server, you will also need to provide the Account Creation Key (ACK) Mnemonic of the server. The mnemonic can be retrieved by running the command

excalibur user ack

on the server.

tip

You can just copy and paste the 24-word mnemonic into the text box. This is especially convenient if you are running the server on the same machine as the client.

Once you have entered the mnemonic, click "Confirm". If the ACK was entered correctly, you should see a new pop up titled "Vault Key":

This key is the actual key used to encrypt your data. Actually, what is shown is the vault key mnemonic, similar to that of the ACK mnemonic that you entered. It is extremely unlikely that you will need to use this key, but it is recommended to keep it in a secure location.

important

Please scroll down on the pop-up to see the full vault key mnemonic.

Once you have saved this key, click the "X" button to close the pop up. You should be redirected back to the login screen.

Logging In

Now, simply click on "Log In" to log in to your account:

Congratulations! You have successfully set up a client to connect to an Excalibur server. Move on to learn what the interface looks like.