Skip to main content

Native App Setup

This guide covers connecting the O.D.I.N. companion app to your self-hosted instance.

Prerequisites​

  • O.D.I.N. instance running and accessible from your device
  • An account on the instance (any role: admin, operator, or viewer)
  • The companion app installed from the App Store (iOS and iPadOS) or the Mac App Store (macOS). There is no Android app.

Step 1: Enter Your Instance URL​

Open the app and enter the URL of your O.D.I.N. instance:

http://<host>:<port>

Examples:

  • http://192.168.1.100:4000 — local network, default port
  • https://odin.example.com — behind a reverse proxy with TLS

The app validates the URL by hitting the /api/v1/health endpoint. If the connection fails, verify:

  1. The URL is reachable from your device (try opening it in a mobile browser)
  2. The port is correct (default: 4000)
  3. If using HTTPS, the certificate is valid (self-signed certs require an additional trust step on mobile)

Step 2: Authenticate​

Option A: Username and Password​

Enter your O.D.I.N. username and password. If MFA is enabled on your account, you will be prompted for a TOTP code after submitting credentials.

The app receives a session JWT (24-hour expiry) and refreshes it automatically.

Option B: API Token​

If you prefer token-based authentication:

  1. In the O.D.I.N. web UI, go to Settings → Account → API Tokens
  2. Create a new token with the scopes you need (at minimum: read:printers, read:jobs)
  3. Copy the token (it starts with odin_)
  4. In the app, tap Use API Token and paste the token

API tokens do not expire by default and do not require MFA on each login, making them convenient for mobile use.

Step 3: Verify Connection​

After authentication, the app loads your printer list. Verify:

  • Printer statuses match the web dashboard
  • Camera feeds load (if cameras are configured)
  • Push notifications arrive (trigger a test from Settings → Notifications → Send Test)

Push Notification Setup​

Push notifications require the O.D.I.N. instance to reach Apple's push notification service (APNs). If your instance is on an isolated network without outbound internet access, push notifications will not work.

The app registers its device token with the O.D.I.N. instance on login. No additional server-side configuration is needed — push routing is handled automatically.

Multiple Instances​

The app can save multiple O.D.I.N. instances. To add another:

  1. Open the app settings
  2. Tap Add Instance
  3. Repeat the URL and authentication steps

Choose which saved instance to use at sign-in. Switching to another instance signs you out of the current one, so switching back requires signing in again.

Troubleshooting​

ProblemSolution
"Connection failed" on URL entryVerify the URL is reachable from your device. Check firewall rules and port.
Camera feeds show black screenEnsure go2rtc ports are accessible. WebRTC may need STUN/TURN configuration for remote access.
No push notificationsCheck that the instance has outbound internet access. Verify notification permissions in your device settings.
Token authentication failsEnsure the token has not been revoked. Create a new token if unsure.
Self-signed certificate errorImport the CA certificate to your device's trust store, or switch to a publicly-trusted certificate.

See Also​