Remote workspaces and chats
Maestrly can run your chats and workspaces on your bot server instead of this computer. They keep working while this computer sleeps or is off, and you use them from the same window: the sidebar lists the chats and workspaces of this computer and of the server side by side.
Experimental: remote workspaces need Maestrly 0.16.0 or later, on the desktop app and on the server.
How it works
The server runs one more Maestrly, in a container of its own, for your chats and workspaces. That container is the workspaces environment. It holds no bots: bots and workspaces can share a server, but never a container.
| On the server | On this computer |
|---|---|
| Conversations, their messages, and the agent's turns, including Maestro, subagents, plans, and reviews | The window: sidebar, chat view, drawer, and settings |
| Workspaces, their Git repositories and worktrees, and terminals | Sound, keyboard shortcuts, window layout, and updates of this app |
| Model accounts, skills, MCP servers, and memory of the server's own profile | This computer's own chats, workspaces, accounts, and settings, unchanged |
| The agent's browser, with its cookies and site logins | The microphone and voice transcription |
| VS Code in the Code tab, with its extensions | Your editor settings, applied to the server's editor |
A turn running on the server keeps running when this computer sleeps, loses its connection, or closes the app. When you come back, the conversation shows what happened meanwhile.
Set up
- Set up a bot server and connect this computer to it. See Bots and the bot server. A server on a VPS is what keeps working while this computer is off.
- Open the Bots tab, select the server, and under Workspaces choose Set up workspaces on this server. A server hosts workspaces in one environment; use another server to keep work apart.
- On the environment's page, add the model accounts it will use: an API key, a subscription sign-in, or accounts brought from this computer. It starts with no accounts, skills, or MCP servers of its own, and nothing is copied from this computer unless you ask.
Once it runs, the Chats and Workspaces tabs show two sections: This computer and the server's name. If Workspaces says Update the server to run workspaces on it, use Update bots first.
Use it
- New chat on the server: use the + on the server's heading in the Chats tab. The header's own New chat still creates a chat on this computer.
- Add a workspace on the server: use the + on the server's heading in the Workspaces tab, then open a folder that is already on the server, create a project, or clone a Git repository. Folders are chosen in a dialog that browses the server. Cloning uses the server environment's Git credentials, not this computer's.
- Drawer: a conversation on the server offers Browser, Code, Terminal, Files, Plan, Review, and Notes, all running on the server.
- Settings: in Settings, the sections that belong to a profile, such as Maestrly Chat, Usage & cost, and Execution, get a Settings of selector. Choose the server there to change its accounts, models, skills, and defaults.
- Memory: chats on the server use the server's personal memory, and its workspaces keep their own project memory there; nothing is shared with this computer. The personal memory panel has a Memories of selector.
- Start, stop, restart, update, and archive: on the environment's page, reached with Manage under Workspaces or Open server page in the menu of the server's heading. Stopping, restarting, or updating at once interrupts the chats running on the server.
Where files live
| Server | Folders offered when you add a workspace |
|---|---|
| A VPS set up by Maestrly | Workspaces (/srv/maestrly, a folder of the server itself) and Home (the environment's home folder) |
| Docker on this computer | Home only; no folder of this computer is mounted |
| A server you manage | Workspaces when you set MAESTRLY_GATEWAY_WORKSPACES_ROOT, and Home |
Prefer Workspaces for projects: its files are ordinary files of the server, so you can reach them over SSH, back them up, and keep them when the environment is archived.
Browser, Code, and Files
- Browser shows the agent's browser on the server, live, with the server's cookies and site logins. You can click, scroll, type, and use its tabs and address bar; accents, input methods, and copy and paste work as on this computer. When another computer opens the same browser, this one says This browser is open on another device, with Show here to take it back.
- Code opens VS Code on the server, in the conversation's folder; its terminal, Git, extensions, and debugger work on the server. The server downloads VS Code from Microsoft the first time, which can take a minute. Your VS Code settings and theme apply the first time; extensions are installed in the server's editor.
- Files browses the server's folders, previews, renames, and deletes files, and moves them to and from this computer. Use Upload… or drag files onto the tab; downloads go to your Downloads folder, and Open on this computer opens a file with your default app. Transfers shows progress and can pause, resume, and retry. Transfers survive sleep, dropped connections, and restarts, and every file is checked with SHA-256. Folders move as files one by one: compress them first, or use Git.
Connection states
The server's heading shows how this computer reaches it:
| State | What to do |
|---|---|
| No label | Connected. |
| Connecting… or Reconnecting… | Wait. Work on the server continues, and the section keeps its last list. |
| Update required | The server and this app run different versions. Use Update bots, or update the app. |
| Stopped, Starting…, or Failed to start | Start the workspaces environment, or open the server page for details. |
| Not connected | Check the server in Settings → Bot server. |
Messages queued behind a running turn are kept by this window only and are lost if the connection drops before they are sent. Two computers paired with the same server see the same chats and workspaces, and either can answer a permission request, a question, or a plan.
Not available yet
- Moving whole folders through Files, page sound, file uploads through a page, and downloads from the remote browser.
- Alert sounds, floating drawer windows, ChatGPT Web Companion sessions, paired reviews between two conversations, and workspace groups, for conversations on the server.
- More than one server: this computer pairs with one bot server.
- Isolation between workspaces of one server: they share one container, one user, and one set of accounts.
Security and limits
- Pairing a computer with the bot server already lets it control every environment there. For the workspaces environment, that means everything Maestrly can do on its own computer: read and write its files, run commands, and use its accounts.
- The server and its administrators can reach your remote projects and accounts. Treat the server as you would your own computer.
- The server and the app must run the same version. Back up the gateway volume before updating the server: 0.16.0 changes its database, and older servers cannot open it.
- Model usage on the server is billed to the accounts you add to its environment.
For troubleshooting and details, read the full technical guide.
Next: Artifacts.