Servers

The mobile app supports two types of servers:

A Stump instance, which will use native APIs for all interactions
Any OPDS v2.0-compatible server

A Stump server may be configured as both an OPDS server and a Stump server, as the functionality is split between two modalities of the app.

❌

OPDS v1.2 will not be supported. I don’t have any interest in maintaining an XML client for the app. I will consider outside contributions that successfully wrangle v1.2 vs v2.0 client-side negotiations without breakage

Multi-Server Support

There is no limit to the number of servers you can configure in the app. This is useful if you have multiple Stump instances or OPDS servers you want to access from the app, or if you have a mix of access points (e.g., via local network and via VPN).

Stump Enablement

If you don’t have a Stump server, you can disable Stump-specific features in the app settings. This will remove the Stump section from the root screen, so you are only presented with OPDS servers. A few things to note:

When disabled:
- You will not be able to configure a Stump server. However, if you already have a Stump server configured it will not be deleted
- You will still be required to choose unique names for an OPDS server. If you have a hidden Stump server, it will still be considered
- If a Stump server is set as the default server, that designation will be removed
When re-enabled:
- The Stump section will reappear on the root screen
- You will be able to configure a Stump server again
- Any preconfigured Stump servers will be unhidden

Authentication

The app supports 3 types of authentication:

Login-based authentication (e.g., username/password)
Basic authentication (e.g., username/password)
Token-based authentication (e.g., API key)

On the surface, login-based and basic authentication sound similar, but the difference is that login-based authentication will not store credentials on the device. Rather, you will be prompted to log in each time you try to access the server. This has drawbacks for OPDS configurations since you will be prompted each time you try to access the server. Stump servers will use short-lived JWT tokens when you log in, so you will only be prompted to log in when the token expires.

ℹ️

Stump will not use actual Basic Auth for native API operations. If you choose basic auth for a Stump server, it would only use Basic Auth for OPDS (if enabled) and fetch a token from the server for native API operations

Token-based Authentication

Token-based authentication will embed a provided token in the Authorization header of each request. While this should be an API key for Stump servers, it can be any valid token which the server will accept.

The following servers, besides Stump, have viable, long-lived, token-based authentication mechanisms:

Server	Status	Notes
Kavita	✅	❌ Does not support OPDS v2
Komga	✅	Must use `X-API-Key` header

Note that token viability does not equate to support for the app. Only OPDS v2-compatible servers are supported by the app.

Security Considerations

The mobile app uses native encryption to store credentials on the device. There is no in-house encryption or security mechanism, so the security of your credentials is dependent on the security of the device itself. For more information on the library being used, see the Expo SecureStore documentation.

Default Server

A server may be configured as the default server. When a default server is set, the app will take you directly to that server when you open the app. A few things to note:

You may only have one default server at a time
A dual-mode server will take you to the Stump server by default
You may change the default server at any time in the app settings

Tested OPDS Servers

📣

If you have tested the app with a server not listed here, please let me know so I can add it to the list!

Excluding Stump itself, the following servers have been tested:

Server	Status	Notes
Komga	✅	-
Codex	⚠️	Feed validation errors, some requests are forwarded to v1.2

Guides

Adding a Server

The process for adding a Stump server and an OPDS server is the same. The only difference is that an OPDS server requires a URL pointing to the root catalog for the feed

ℹ️

If you configure a Stump server as a dual-mode server, you may use the root URL for the Stump server instead of the catalog URL

Go to the Servers screen

This is the very first screen you will see when you open the app

Click the `+` button

The button is located in the top right corner of the screen

Select either `Stump` or `OPDS`

The very first field labeled Kind will allow you to select the type of server you are configuring.

If you wish to configure a Stump server with OPDS support, select Stump and then enable the Enable OPDS switch towards the bottom of the form

Fill in the required fields

The form will have the following required fields:

Name: A friendly name for the server
URL: The URL of the server. If OPDS, this will be labeled Catalog URL
Auth: The type of authentication to use

If you choose Login for auth, there will be no additional fields to fill in. If you choose Basic, you will need to provide a username and password. If you choose Token, you will need to provide a token

Fill in the optional fields

You may configure the following optional fields:

Custom Headers: Any custom headers you wish to send with each request

You may enable/disable the following optional fields:

Enable OPDS: If you are configuring a Stump server, you may enable OPDS support here
Set as default server: If enabled, the app will take you into this server when you open the app instead of the root screen

Click `Add server`

Editing a Server

Force press on a server in the list to bring up a context menu. Select Edit to edit the server.

The process for editing a server is the same as adding a server, so follow the same steps as above. The notable difference is that you may not name it the same as an existing server

Deleting a Server

Force press on a server in the list to bring up a context menu. Select Remove to delete the server.

You will be presented with a confirmation dialog before the server is deleted. If the server is a dual-mode server, an additional warning will be presented.

ℹ️

Any disk space used by the server will be freed up when the server is deleted. This includes any books downloaded from the server or cached data

Known Issues / Limitations

Non-local IP addresses (e.g., Tailscale machine IPs) seem to be blocked by both iOS and Android. While iOS has made this public knowledge, I haven’t found any official documentation from Google on this. This is a limitation of the OS, not the app itself. If you need to access a server on a non-local IP, you will need to configure a domain with the appropriate DNS settings

App Formats