Bots and the bot server
A bot is a Maestrly agent that runs in Docker on a bot server you control, with its own Linux desktop, model accounts, memory and routines. You create, talk to and supervise bots from the Bots tab of the desktop app. Bots on a VPS keep working while your computer is off.
Experimental: the Bots tab is marked Experimental. Back up your bot data before changing or removing a server.
What a bot is
Each bot has:
- a conversation with you, using the same composer as desktop chats;
- its own Linux desktop with a browser, terminals, a file manager and the programs it starts;
- a main model chosen from its environment's accounts, plus its own memory and scheduled routines;
- an approval ceiling that limits what it does without asking you.
Bots run on the bot server: Docker on this computer, or a Linux VPS. Bots on this computer stop when it sleeps or shuts down. Bots on a VPS keep going; when you reconnect, open a bot to see what it did and check Awaiting you for anything that needs you.
Set up the bot server
Open Settings → Bot server and choose where bots run:
| Choice | What you need | What happens |
|---|---|---|
| This computer | Docker with the Compose plugin, running. Docker Desktop, OrbStack, Colima, Rancher Desktop and Docker Engine work. | Maestrly checks Docker, then Install bot server downloads the images, starts the server and pairs this computer. |
| A server (VPS) | Ubuntu 22.04+ or Debian 12+ on x86_64 or arm64, SSH as root or as a user with passwordless sudo, at least 4 GB of memory and 20 GB free disk. | Install on the server installs Docker when needed, starts the server and pairs this computer over SSH. |
| I already have a server | A bot server you run yourself. | Enter its Server address, a one-use Pairing code and a Device name, then Connect. |
If Docker is missing on this computer, use Download Docker, install it, then Check again. Maestrly does not install Docker here.
For a VPS, enter Server address, User and Password. Under Advanced options you can change the SSH port or Use a private key instead. The password or key is used for setup only: Maestrly creates its own administrator key, keeps it in the system's secure storage when available, and reaches the server through an SSH tunnel. You need no HTTPS certificate or VPN.
The installer also asks what the server hosts: Bots and artifacts, or Artifacts only, which downloads just the server image; the bot runtime downloads when you create your first bot.
Plan resources before installing. The first download is several GB, and each environment has a 4 GiB memory limit by default. To add a second computer, install against the same VPS from it: Maestrly only pairs that computer. Any paired computer can control every environment and bot on the server.
Disconnect this computer unpairs this computer and leaves the server and its bots running. Remove bot server permanently deletes every bot, environment and their data after you type remove.
Network access
Installer setups start with bots limited to the public internet. To let bots use a service on your machine or server, such as Ollama, turn on Let bots reach this computer and its local network (Docker here) or Let bots reach the server's private network (VPS). Each environment picks up the change when it next starts or restarts.
Environments
An environment is one container with one home folder and one set of model accounts, skills, MCP servers and site logins. Up to eight bots can share it.
| Shared by the bots of an environment | Each bot's own |
|---|---|
| Container and memory limit | Name, role, instructions and approval ceiling |
| Home folder, files and installed tools | Conversation, queue and pause |
| Model accounts: API keys and subscription sign-ins | Main model and compaction model |
| Skills and MCP servers | Memory, routines and requests in Awaiting you |
| Site logins (browser cookies) | Its desktop and screen |
Bots in one environment trust each other. They run as the same Linux user, so a bot that can run commands can read the other bots' files, conversations and credentials. Use separate environments for work that must stay apart, for example one per client.
Select an environment in the Bots tab to open its view: an overview of its bots and resources beside its Screen. Use Restart, Stop or Start environment, and change its Memory limit (server default, or 2 to 16 GB). Restarting, stopping and archiving name every bot they affect before you confirm. Archive in its settings removes the container and archives its bots but keeps their data; restore it from Archived environments on the Server page, which opens from the server card at the top of the Bots tab.
Create a bot
- In the Bots tab, choose +.
- Enter a Name and What it does.
- Under Where it runs, choose New environment for its own container, accounts, files and site logins, or Existing environment to join one that is already set up and signed in.
- For a new environment, use Accounts, skills, and MCP to bring items from this computer. Use the recommended ones selects everything that works outside this computer.
- Choose how far it goes without asking and which bots it may message, then Create bot.
Creation continues on the server if you close the dialog. API keys, GitHub Copilot and Cursor credentials, global skills and MCP servers are copied. ChatGPT (Codex), Claude, Grok and Google AI (Antigravity) sessions are never copied: you sign in again for the environment, which gets its own session.
Talk to a bot
Select a bot to open its Conversation. Choose Computer in the header to watch its desktop beside the chat.
- Attachments: drop files on the composer or use +. Send PNG, JPEG, WebP or GIF images up to 5 MiB, PDFs up to 10 MiB (four per message), and UTF-8 text or code files up to 256 KiB, with at most eight files and 20 MiB per message. DOCX, XLSX and ZIP are not accepted as attachments.
- Downloads: ask the bot to share a file it made, in any format up to 100 MiB. Download saves it to this computer's Downloads folder without overwriting existing files, and Show in folder reveals it.
- Composer: choose the bot's model, reasoning effort, Fast mode when supported and access ceiling; follow context use and estimated cost; dictate with the microphone.
- Search: press Command+F (Ctrl+F on Windows and Linux) to search the conversation.
- Pause and resume: Pause holds the bot and its queued work; Resume lets it continue. Other bots in the environment are not affected.
- Separate window: Open chat in new window keeps the conversation open while you view other bots.
Watch or take control
The bar under the screen says who is in control. Take control pauses the bot at the next safe step and gives your keyboard and mouse to its desktop; plain-text copy and paste work while you control it. Give back accepts an optional note: the bot reads it, takes a fresh screenshot and continues. If your computer disconnects, control returns to the bot after five minutes. Tool rows for its browser, computer or terminal offer Show on computer.
Awaiting you and alerts
Awaiting you, in the Bots tab, collects permission requests, questions and help requests from every bot. You decide; a bot cannot approve for you. While your computer is connected, bots use the Alert sounds in Settings → Appearance & sound: Turn ready or Turn failed when a bot finishes what you asked, and Permission request when it needs you. Routine runs and conversations between bots end silently. Turn off Bot alerts to silence bots without silencing your own chats.
Configure an environment
In the environment view, choose Environment settings (the gear). Its tabs apply to every bot in the environment; this computer's settings stay separate.
- Accounts: Add an API key for OpenAI compatible (Chat Completions), OpenAI Responses or Anthropic, with an optional base URL; sign in with ChatGPT (Codex), Claude, Grok or Google AI; or use Bring from this computer…. Subscription sessions are separate from your computer's but use your subscription quota, under the provider's terms.
- Models: choose which models appear for new selections. Hiding a model keeps existing bot choices working.
- Skills and Tools: install, create, edit and remove skills; add, edit and test HTTP and stdio MCP servers inside the environment.
- Components: see the Claude Code, Codex and Google AI (Antigravity ACP) runtimes, with Check for updates, Update, Automatic updates and Roll back.
- Preferences: rename the environment, set its default compaction model and the default availability of image generation.
- Archive: stop the environment and remove its container while keeping its data.
Changes wait until Save changes (Command+S, or Ctrl+S on Windows and Linux) or Discard. The environment must be running; an older server or image asks you to update and restart it first.
Bot settings
Bot settings, the gear in the conversation header, has one tab per section: Identity, Autonomy, Model, Conversations, Routines, Memory, This computer, Environment and Archive. In Model, choose the bot's Main model and its Compaction model.
Autonomy sets the bot's approval ceiling. The bot cannot raise it.
| Ceiling | Runs on its own | Waits for you |
|---|---|---|
| Ask for approval | Reading | Edits, commands, new sites and MCP tools |
| Approve for me | Reading and editing its own folder, opening sites, MCP tools | Commands and work outside that folder |
| Full access | Commands and edits anywhere in its container, including other bots' files | Actions that need separate authorization |
Routines
In Routines, choose Add routine and give it a title and a self-contained prompt. Run it at a fixed time on chosen days in a Time zone (no days means every day), or every 15 minutes to 24 hours. Routines run on the server, so on a VPS they continue while your computer is off. A run is skipped, not replayed, when the bot is paused or offline, the time was missed by more than 15 minutes, or the previous run is still going. Use Run now to test a routine and History to review its recent runs. Bots can create up to 10 routines of their own, marked Created by bot. Each run is a full model turn on your account, so prefer the longest useful interval.
Messages between bots
In Conversations, allow the bots this one may message, in its own or another environment. Messages appear in both conversations. The server allows at most 30 messages per bot per hour, and blocks a pair for 30 minutes after 20 messages within 30 minutes without a message from you.
Memory
Each bot has its own memory, separate from other bots and from project memory on your computer. Review, pin, archive or delete entries in its Memory tab. Memory about you, in the Bots tab, holds facts and preferences about you: an entry is for All bots or for the bots of one environment, chosen in Who sees it. Entries a bot saves belong to its environment; Make global shares one with every bot.
Artifacts
Turn on Publish artifacts in a bot's Identity tab to let it publish web pages on the bot server. Hosting must also be on in Settings → Artifacts. A bot works only with its own artifacts. See Artifacts.
Work in the projects of your computers
A bot can start and follow development conversations in the projects of computers paired with its server. Each computer decides on its own:
- On that computer, open the bot, then Bot settings → This computer.
- Turn on Give this bot access to this computer.
- Choose its Local projects, Accounts and models, what the bot can do (read its conversations, create conversations and send messages, cancel its running turns, answer ordinary questions), the Approvals ceiling and the name this computer shows the bot. Then choose Give access.
- Repeat on each computer the bot should reach. Other computers with access shows the others, online or offline, and lets you remove their access.
Each conversation the bot starts runs on that computer in a worktree of its own and shows in your sidebar with the bot's name. Plan approvals, and whatever the ceiling leaves to you, wait for you on that computer; the bot never answers them. Choose Full access only for a bot you control yourself.
Nothing connects into your computer: it keeps a connection open to its bot server, and calls travel on it. If the computer is closed, asleep or disconnected, the call fails immediately. Nothing is queued, and no other computer takes over. The bot sees project and model names, never local paths or credentials. Turning access off ends it at once; the bot's conversations and worktrees stay on that computer. To use this, update the desktop app, the bot server and the bot's environment.
Update bots
When an update is available, the Bots tab shows Update available and Update bots, also offered in Settings → Bot server. One click updates a server Maestrly installed, then restarts each environment on the new image as soon as none of its bots is working, waiting for you or under your control, even while your computer is off. Its home folder keeps accounts, site logins, files and conversations. While it waits, the environment shows Update scheduled, with Update now, which restarts it at once and interrupts its bots, and Cancel update. Maestrly never moves a server back to an older version; if another computer updated it past this app, update the app.
Bots also keep Claude Code and Codex current on their own (experimental). Each environment checks for new stable releases every six hours, verifies and tests a release before using it, never interrupts a turn in progress and never goes below the version its image ships. Check, update or roll back by hand in the environment's Components tab.
Security and limits
- The bot server runs on infrastructure you control: Docker on this computer or your own VPS. The server controls Docker, which amounts to root access on its host, so treat it and its administrators as trusted.
- A bot cannot use your computer's screen, browser, terminal, accounts or local files. It reaches your projects only through the access each computer gives it.
- A bot uses the credentials and files you bring to its environment, and every bot there can use them too. API keys are stored encrypted in the environment, but anyone with root on the server can decrypt them.
- Environments are separate containers, not a security boundary against the server itself. A program a bot starts that listens on a network port can be reached from other environments.
- Bots reach only the public internet unless you allow private networks.
- Pairing codes work once and expire after ten minutes. Any paired computer can control every bot, screen and setting on the server.
- Environments have no Docker or
sudo. They include Node.js, Python, Git and common command-line tools; tools you install in the home folder persist. - Model usage, including routines and conversation summaries, is billed to your own provider accounts and subscription quotas.
For a server you manage yourself, backups, ports and troubleshooting, read the full technical guide.
Next: Artifacts.