Skip to main content
Mibyan Desktop is a window onto an agent backend, also called a gateway. The backend can run on this computer or somewhere else. Profiles are separate agent identities that live on a gateway. This page explains both.

​
Four kinds of gateway

A remote agent runs commands and reads files on that machine, not on yours. Connect only to hosts you trust.

​
Manage gateways

Open Settings, Gateways. It lists every registered gateway, marks the one in use (Current), the default (Primary), and the one the app manages (App-managed).
1

Add a connection

Choose Add connection, pick the kind, and give it a name. Names must be unique and appear everywhere the gateway does, for example Homelab or Work laptop.
2

Test it

Test checks that the gateway is reachable. The test exercises the connection and sign-in path the app will actually use, so a pass means it works.
3

Use it or make it primary

Switch gateways from Sessions. Make primary sets which gateway the app opens on.
Good to know:
  • Profiles, chats, messaging, and scheduled jobs stay with their gateway. Work on a gateway you switch away from keeps running.
  • The setting At startup, return to Sessions on the last-used gateway decides where the app opens. When it is off, the app opens on the Primary gateway.
  • You cannot add a second local connection, and duplicate URLs or SSH hosts are rejected with the name of the existing one.
  • Remove takes the connection out of this app only. The instance itself is not touched, and you can add it again any time.
  • Update all instances sends an update to every gateway that can be updated. See Install and update.

​
Set up a remote gateway

1

Enter the URL

The base URL of the gateway. Path prefixes such as /mibyan are supported.
2

Let the app detect how it signs in

The app asks the gateway. Hosted gateways use OAuth (for example, sign in with your identity provider) or a username and password. Self-hosted ones use a session token.
3

Sign in or paste the token

Sign-in opens a browser window and refreshes itself afterward. A pasted token is used for both REST and WebSocket access. Leave the field blank to keep a saved token.
4

Test, then save

Test remote verifies the connection. Save and reconnect applies it now and keeps the app open. Save for next restart waits.
In your operating system’s secure storage (Keychain, Credential Manager, or the Linux keyring). If no secure storage exists on the machine, Mibyan asks before saving the token unencrypted in the app’s connection settings file, where any process running as your user could read it. On Linux, install or enable GNOME Keyring or KWallet to avoid that.
For gateways behind an access proxy such as Cloudflare Access, add headers like CF-Access-Client-Id and CF-Access-Client-Secret. They are sent with every HTTP and WebSocket request to that gateway and stored encrypted. Headers Mibyan manages itself (such as Authorization and Cookie) are ignored.
If the environment variables MIBYAN_DESKTOP_REMOTE_URL and MIBYAN_DESKTOP_REMOTE_TOKEN are set, they control the session and the app tells you. Unset them to use the saved settings.

​
Set up SSH

SSH mode starts Mibyan on the remote host and tunnels it to this app, so nothing needs to be exposed. It needs working key-based SSH access, because Mibyan runs ssh non-interactively. The first host key presented is trusted and pinned, and any later change fails closed. Test SSH confirms the host is reachable and Mibyan is found. Save applies on the next launch, and Connect reconnects now. Remote hosts running Linux, macOS, or Windows are supported. Common SSH messages and what to do:

​
Use Mibyan Cloud

1

Sign in once

Choose Sign in to Mibyan Cloud. There is no URL to paste.
2

Choose an organization

If your account belongs to several, pick one. Your role in it is shown.
3

Pick an agent and connect

Your agents are listed with their status. A new one shows Provisioning until it is ready. Choose Connect.
If no agent exists, create one in the Mibyan portal and refresh. Cloud agents are managed by Mibyan, so the app does not restart or update them. If a cloud agent is down, the app offers Check Portal status and a way to get help.

​
What the status bar tells you

The status bar shows the current connection (for example Remote: host, SSH: host, or Cloud: host), whether the gateway is ready, needs setup, connecting, offline, or restarting, and both versions. Its gateway menu offers Reconnect gateway, the recent activity log, and your messaging platforms. If the connection drops, the app keeps trying in the background, and you can still read and draft.

​
Profiles

A profile is an independent Mibyan environment: its own config, skills, memory, and persona (SOUL.md). Use profiles to separate work and personal, or to give different agents different jobs.

​
Create and manage

​
Switch profiles

  • Use the profile picker, or Cmd/Ctrl with 1 to 9 for the first nine (Cmd/Ctrl with Alt and a number for 10 to 18).
  • Cmd/Ctrl with D returns to the default profile. Cmd/Ctrl with Shift and the square brackets steps to the next or previous one, and Cmd/Ctrl with Shift and 0 toggles the all profiles view.
  • /profile <name> sets the profile for new chats.
  • Switching does not reboot the app. The window stays put, and other profiles’ chats keep streaming in the background.
Settings pages show which profile they apply to, so you always know whose config you are changing.

​
Run one profile on a remote host

You can send a single profile to a remote machine while everything else stays local. From the profile menu choose Connect to a remote host, enter the address and an access token, and confirm.
  • New chats in that profile run on the remote host, and it will run commands and read files there, not on this computer. The profile shows a Runs on host badge.
  • This is separate from Settings, Gateways, and does not change a gateway that has the same name.
  • If the host rejects the saved token, the app tells you and lets you Enter new token. Remove remote connection puts the profile back on this computer.

Next: skills, tools, and automation

Extend the agent with skills, MCP servers, plugins, schedules, webhooks, and messaging.