Skip to main content
This page is for you if your Mac added a Linux server under Settings → Connections and installed Enconvo there. The server runs Enconvo without a screen, and your Mac opens its chats but not its settings. You can set the server up in three ways: in its web UI, from its command line, or by syncing your Mac’s setup to it.

What your Mac shares with the server

Pairing lets your Mac use the server’s chats, agents and files. It doesn’t share settings. The server keeps its own models, agents, plugins and API keys, and doesn’t copy them from your Mac.
  • Settings and API keys don’t open from your Mac. You change them on the server.
  • Out of the box, the server’s agents use the default model. On a new install that’s Enconvo Cloud, on the account the server signed in with, so its chats use your Cloud points.
  • To switch the model of one agent quickly, use the model picker in a server chat on your Mac. It sets the model, reasoning effort and speed for that agent on the server. A provider that needs an API key needs that key on the server first.

Open the server’s web UI

The server can serve the Chat Window and Settings as a website, so you can use Settings in your Mac’s browser. The install from your Mac doesn’t turn it on. Turn it on once over SSH.
1

Turn on the web UI

Connect to the server with ssh and run:
This rewrites the Enconvo service with the web UI on and restarts it. It listens on 127.0.0.1 only, so nothing outside the server can reach it. When you run enconvo service install again, the service runs with the options of the new run only.
2

Open a tunnel from your Mac

In Terminal on your Mac, use the same host name you use with ssh:
Leave it running while you use the web UI. Press Control-C to close it.
3

Open the web UI

Open http://127.0.0.1:54580 in your Mac’s browser. Settings work as on your Mac: pick models under Settings → AI Model, add plugins under Settings → Plugins, and enter API keys there too.
enconvo service url on the server prints the web UI’s address.

Reach it without a tunnel

To open the web UI from other computers without SSH, bind it to the network:
The web UI then needs a connection token. Run enconvo service url to print the address with it, ending in ?tkn=. Open that link once and your browser keeps the token. Behind a reverse proxy, add --web-url https://enconvo.example.com with the address the proxy serves, or --web-host <name> for another name the server is reached by. Both need the token too.
The token gives whoever has it your Enconvo account on the server and every file its user can read. Keep the link private, keep the port behind a firewall or VPN, and prefer the SSH tunnel. To replace the token, delete ~/.config/enconvo/.support/windows-shell/web-token on the server and run systemctl --user restart enconvo.

Configure from the command line

Every installed plugin’s routes are enconvo commands on the server: enconvo <plugin> <route> --flags, or --input-json for the whole request. Add -h at any level to see what’s there:
Quote keys that contain |, such as 'agent|main'. Unquoted, the shell reads | as a pipe.

Models

List the server’s model providers. Each one’s commandKey, such as llm|enconvo_ai, is the value you set:
Set the default model, which every agent set to the default uses:
Set the model of one agent. The main agent is agent|main; enconvo agent list shows the others’ command_key:
Set the value to default to follow the default model again. enconvo config preferences 'agent|main' lists every setting an agent has. To undo one setting, name it:
enconvo config reset without --keys resets every setting of that key, and for an agent or command it also deletes its workspace data. This can’t be undone.
config get shows stored API keys and tokens as [hidden]. Enter API keys in the web UI’s Settings rather than with config set, so they don’t land in your shell history.

Plugins

plugin install takes a GitHub owner/repo, a git URL, an https link to a .zip, npm:<package>, a folder, or <plugin>@<marketplace>. Plugins that need a screen are hidden on a server.

Agents

enconvo agent -h lists the rest, such as deleting or pausing an agent.

Use your Mac’s setup with Sync

Sync copies your Mac’s settings to the server through your Enconvo account. It’s part of Enconvo Cloud plans and lifetime licenses.
  1. On your Mac, open Settings → Sync, turn on Sync across computers, and choose Enconvo account under Storage. A Linux server can’t reach iCloud.
  2. In the server’s web UI, open Settings → Sync and turn on Sync across computers.
  3. Under What syncs, choose what to bring over on both computers, such as Settings, Plugins and Skills.
  4. To bring your API keys too, turn on API Keys on both. It’s off by default. Your Mac then shows a code: check that the server shows the same one, then click Allow.
What belongs to one computer stays there: hotkeys, folder paths and working folders, sign-ins, Automations and messaging bots. See Sync your Macs for what each choice covers.

Troubleshooting

CLI and Local API

Run Enconvo’s commands from Terminal and scripts

Account and Sync

Keep settings the same on every computer