Dokumentation

Bandito is a native Mac app and a small daemon that runs on a server you own, or on the same Mac. The agents are the official Claude Code, Codex and Grok command-line tools, signed in with your own subscriptions or keys. Bandito adds what a terminal does not: a crew of agents with roles and schedules, approvals before risky steps, and servers, terminals, files, a browser and the server screen in one window.

#How the pieces fit

• The Mac app is the window you look through. It stores nothing of your code.
• The daemon runs on the server, as a user service. It starts the agents, keeps their memory in Markdown files, runs schedules and answers the app.
• Agents run on the server with the rights of the user they run as, and talk to the model providers directly. Your code, keys and chat history stay on your servers.

#The modes of the app

Each part of the window is a mode with a shortcut:

• Team home ⌘0 and Team ⌘1: agents, chat, approvals, schedules, memory.
• Files ⌘2, Terminals ⌘3, Browser ⌘4, Server screen ⌘5: the workplaces of the server.
• Marketplace ⌘6: services, bots and skills.
• Server ⌘7: load, workplaces, secrets, ports, devices, updates, backups, log.
• Also: ⌘N new agent, ⌘K search and quick open, ⌘I agent details, ⌘, settings.

#Requirements

• The Mac app: macOS 14 or later on a Mac with Apple Silicon or Intel.
• The server: Linux or macOS, on x86_64 or arm64. It can be a VPS, a home server, or the same Mac.
• The agents need their own tools and subscriptions on the server (Claude Code, Codex or Grok). Bandito can install the tools; you sign in once.

#Install the Mac app

1. Download Bandito from bandito.dev (the Download button gives the disk image of the newest Mac build).
2. Open the disk image and drag Bandito to Applications.
3. Open Bandito.

#First launch

A short introduction opens: Welcome, Account, Server, First agent, Done. It takes about three minutes. Signing in is optional: an account only syncs your server list, shortcuts and prompts between devices. You can skip the introduction at any step and set everything up later in Settings; Help → Show the introduction again brings it back.

#Connect a server

Agents live on a server, so they keep working when your Mac is closed. The server step offers:

• This Mac. No SSH. Bandito is copied to ~/.local/bin, its service starts, and the app pairs with it. Agents and their tools run on your Mac.
• Your own server. Type its address. Bandito shows the server’s fingerprint and asks you to trust it once (“This is my server — trust it”), then installs what is missing. A changed key is refused: nothing is trusted until you check the server.
• By hand. Run the install command below on the server, then choose Add server in the app and enter the one-time code that bandito pair prints.

The app reaches a server over SSH (address, user, port and key), over Tailscale, or by a direct address. Settings → Servers keeps each connection.

#Install the daemon by hand

The script downloads the daemon, checks its SHA-256, puts bandito in ~/.local/bin and starts it as a user service (systemd on Linux, launchd on macOS). bandito pair prints a code that works once and is valid for a few minutes. Updating a server later runs the same script and keeps your data and settings.

curl -fsSL bandito.dev/install | sh
bandito pair

#Add more servers

Settings → Servers → Add server opens the same server step. Each server keeps its own agents and settings; the server picker at the top of the sidebar switches between them.

#Install what the server is missing

Server → Overview → Capabilities lists what the server has: the Claude Code, Codex and Grok tools, Chrome for the browser, Docker or Podman for containers. Press Install to add the missing items; the log shows the progress. Installs that need the administrator password never ask for it in the app: Bandito opens a terminal with the command typed in, and you type the password there.

#Sign in to the agents’ tools

Agents use the official tools and your own subscriptions. Sign in once on the server, in a terminal of Bandito (⌘T):

• Claude Code: claude
• Codex: codex login
• Grok: the Grok tool’s own login

The New agent sheet shows the state of each runtime: “Signed in · N% left”, “Not signed in on the server” or “Not installed on the server”.

#Create an agent

Press ⌘N, or type /new in a chat. Start from a template (Builder, Reviewer, On-call, Assistant, Researcher) or from scratch, then give the agent a name, a role (a short label, for example “builder”) and a face: a face from the set, an emoji or your own picture on a colour. Create is enabled once the agent has a folder.

#Runtimes and models

• Runtime: Claude Code, Codex or Grok, whichever is signed in on the server. You can change it later in Agent details (⌘I); memory and tasks move with the agent.
• Model: the runtime’s default, or any model name the tool accepts. A new Claude Code agent starts on Haiku.
• Effort: Low, Medium, High, Very high or Max. Higher levels think longer and use the subscription limit faster; the levels offered depend on the runtime.
• If the limit runs out: set a second runtime. The agent continues there until the first limit resets, and the thread says so (“Claude Code limit ran out — continuing on Codex until …”), then “Back on Claude Code”.

#Folder and workplace

By default every agent gets its own folder inside a shared agents folder (for example ~/Bandito/Researcher), made when you press Create. To work in a repository that already exists, choose Existing folder, or Clone from a link. A workplace is where the agent’s tool runs: Shared (the server itself) or Separate (a Docker container with its own limits); see Workplaces.

#Instructions and tools

Instructions are a text the agent gets with every task, like a brief for a new colleague. The tools an agent may use are Terminal, Project files, Browser, Message the team and Server screen; click a chip to switch it off. The server screen works on Linux servers only.

#Memory and chapters

An agent keeps its memory in plain Markdown files on the server: MEMORY.md (projects, decisions, open tasks), notes/, journal/ and files/. Long chats are split into chapters, so the agent remembers and messages do not get more expensive. Agent details → Memory shows the current chapter and how full it is, and lets you choose how to split:

• Smart (recommended): a new chapter when the conversation grows, and a fresh one each morning. The chapter length is 60K, 120K (default), 200K, 500K, 1M tokens or your own number.
• Every day: a clean page each morning.
• One long chapter: one chapter, the agent compresses old messages itself. It costs more.

Memory files open in Files; edit or delete them there and the agent reads the new version next time.

#The main agent and creating agents

The main agent of the crew coordinates the others: it hands out tasks to teammates and waits for their answers. It can also create agents for you, give them a schedule and a task. You decide on a card every time, and the limits do not depend on what it asks: the new agent gets at most the capabilities and services the main agent has, never a softer approval mode than its creator’s, only a runtime installed on the server, and it runs in the same workplace. The main agent makes at most 10 agents an hour.

#Move an agent to another server

Right-click an agent and choose Move to… to move it to another connected server of yours. Its settings, memory and chat history move; the project folder (the code) does not, so you choose a project folder on the new server. Keys and sign-ins stay on the old server, and the agent is paused there while it moves. To move an agent into a separate workplace on the same server, use Where it works in the inspector; it starts a new chapter there.

#Working with an agent

• Slash commands: /new, /model, /effort, /memory, /changes, /terminal, /files, /usage, /pause.
• Mentions with @: services, agents, files and the browser tab. Names work in your language and in English.
• Attach files and screenshots with the button, drag and drop, or ⌘V. Dictation and reading replies aloud work on the device.
• Pause (the agent’s menu, the inspector, or /pause) keeps the chat and memory and starts no work: messages wait until you resume, and scheduled runs are skipped. Stop (⌘.) ends the turn that is running.
• What changed (⌘⇧D) lists the files the agent changed, task by task, with a diff for each. Keep a file as it was, or roll the whole task back, and undo the rollback.
• A message you send while the agent is busy shows at once as “Queued”.

Agents work on your server with the rights of the user they run as. Bandito checks each action before it runs. Treat this as a safety net, not a wall: see the limits below.

#Approval modes

Each agent has one mode, set when it is created and changeable in Agent details → Ask for permission:

• Only the risky ones (default): routine work goes on, the risky list below is asked about.
• About everything: every tool call the tool asks about goes to you.
• About nothing: the agent runs without asking. Only for a sandbox you do not care about.

#The approval card

When an action is asked about, the agent stops and a card appears in its thread with the agent’s name, the action and the exact command or diff. Approve allows it, Deny refuses it. “Always allow this here” allows that exact command for this agent from now on. A request nobody answers within 24 hours is denied. You can answer in the app, from the menu bar, from a notification, or in Telegram.

#What is asked about

In “Only the risky ones” the card says why, for example “risky: git push”. The list:

• git pushes and history rewrites (git push, reset --hard, clean -f, branch -D).
• Deleting many files (rm -r, find -delete, shred, chmod -R, chown -R).
• Publishing and deploys (npm publish, cargo publish, vercel --prod, fly deploy).
• Cluster and infrastructure changes (kubectl delete or apply, helm upgrade, terraform apply or destroy).
• Deleting data in a database (DROP TABLE, TRUNCATE, DELETE FROM).
• Shutdown and reboot, system services and cron jobs, user accounts.
• Sending data out (curl with a body, scp, rsync to another host, ssh with a command).
• Writing outside the agent’s project folder.
• In the browser: payments, sending forms, deleting on a site, signing in with a password.

#Your own rules

Settings → Approvals → New rule. A rule is a pattern such as terraform plan* (the * means anything) plus Allow, Ask or Deny, for all agents or for one. If two rules match, the rule for one agent wins, then the newer rule. A rule can never allow the protected actions.

#Always refused and never silent

• Bandito’s own files and controls are off limits for agents in every mode and under any rule: its data folder, its program and service files, and stopping or restarting Bandito.
• A command Bandito cannot read in full (an unset variable, code run from a string, a folder that cannot be worked out) is asked about, never allowed on its own.

#What approvals do not stop

The checks read the command line. They stop a mistake. They do not stop an agent that tries to get around them: a script, an interpreter or a build step can reach whatever the server user can reach. A real boundary is a separate workplace (a container) or a separate server.

• Keep the agents’ rights small: no keys you do not need.
• Keep “Only the risky ones” or “About everything” on for agents that touch production.
• Run work you do not trust in a container or on a separate server.

#Add a schedule

1. Open Agent details (⌘I) → Details → Schedule → Add schedule.
2. Choose Repeat: every N minutes or hours, Every day, Weekdays, Days of the week, or Other for a cron expression.
3. Set the time and the prompt: what the agent should do each time.
4. Save. The list shows the next run of each schedule; the switch in a row pauses and resumes it.

The main agent can create schedules for agents too, and bots can bring schedules; schedules that come with a bot start switched off.

#How a run looks

A scheduled run is one quiet line in the chat, “Scheduled run · name · time”, instead of a bubble with the whole prompt. A click shows the prompt.

#Quiet runs: “Nothing new”

When a scheduled run finds nothing worth telling you, the agent ends it quietly: the line says “Nothing new”, and there is no message, no notification and no Telegram message. A click shows what it did.

• Only scheduled runs can be quiet. A question you ask always gets an answer.
• Approvals, forms and sign-in requests always show, even in a scheduled run.

#Terminals

Real shells on the server, shown in panes (⌘3). A terminal keeps running when the app is closed. Split panes, choose a layout, collapse a pane, go full screen, rename a pane, and use Input to all to type into every pane. A terminal can open inside a container workplace.

#Files

The files of the server (⌘2): the same folders the agents work in. Open and edit files (read, edit, or side by side), create, rename, duplicate, move to the Trash, upload from your Mac and download to it. Quick look previews a file; hidden files can be shown. “Create agent in this folder” and “Terminal here” are one click away. If a file changes on the server while you edit it, Show difference lets you keep yours or take the server’s.

#Browser

A Chrome browser that runs on the server (⌘4). Your sign-ins are kept there and agents see the same tabs you see. Watch an agent browse, take control of the page and give it back. Open a preview of a server port, or open a link on your Mac. The server needs Chrome; the mode offers to install it.

#Server screen

The desktop of the server, shown on your Mac (⌘5). Watch an agent work, take control to click and type, and give it back. The screen wakes on demand and sleeps when nobody uses it; picture quality, full screen and a shared clipboard are in the toolbar. It works on Linux servers (including Windows with WSL); on other servers use Terminals or the Browser.

#Shared and separate workplaces

A workplace is where an agent’s tool runs. Shared is the server itself, as the Bandito user: the agent works with the same files as you and can use the server’s browser and screen. A separate workplace is a Docker (or Podman) container: the agent sees only its own folder and the folders you add, with its own disk, network and limits (default 2 CPU and 2048 MB; the network can be switched off). Inside a container an agent has no browser and no screen tools.

Create and manage workplaces in Server → Workplaces; the container starts with the first message of an agent in it.

#Services

Services are MCP servers. Connect one once, on the server, and every agent you allow can use its tools: GitHub, Sentry, Linear, Notion and dozens more, in shelves by category with Connected on top (⌘6).

• Most services sign in through the browser: no keys, ids or headers. GitHub signs in with a code, like gh auth login.
• Services that still need a key link to the page where you get it.
• An agent that needs a service shows a card in the chat (“Agent needs Linear — Connect”) and continues once you connect. Only a connection made from that card gives the agent access.
• Your own integration: paste the server’s address; Bandito offers browser sign-in when the server supports it.
• Per service you choose what agents may do: everything, confirm writes, or read only, down to allow, ask or deny per tool. “Try a tool” runs one by hand; the journal lists every call.

#Bots

A bot is a ready-made agent: prompt, abilities, services, schedules and a starter message. Install one, create your own (Create bot, My bots), or install a bundle, a ready team in one click.

#Skills

Skills are open skills that agents can use. Install a skill for all agents or for one, update or remove it. Bandito never overwrites a skill you wrote yourself, and you can import the skills and commands you already have in Claude Code or Codex (files with keys and hidden files are never sent).

#Share by link

Share a bot or your own skill by link: public, or link-only (unguessable, not indexed). The page on bandito.dev/s/… opens it in Bandito. Installing shows everything first: risky abilities and schedules start off, a skill with scripts needs your explicit consent, and services are granted only when named. Bandito scans for secrets before publishing, and reports hide a share automatically.

#Set up the bot

1. In Telegram, create a bot with @BotFather (/newbot) and copy its token.
2. In Bandito: Settings → Telegram. Paste the token and press Connect. The token is stored on the server only, and the app never shows it again.
3. Press Link Telegram. Scan the QR code, or press Open in Telegram, then press Start in the chat. The code is valid for ten minutes; the window closes by itself when the chat is linked.
4. For each linked chat choose Approvals (be asked there when an agent needs approval) and Agent replies: All, From Telegram, or None. Unlink removes the chat.

The Telegram section appears when the server runs Bandito 0.1.8 or later.

#What you can do

• Approve or deny an agent’s action with one tap. A request that is too long for one message says to open the app instead, and creating an agent is only allowed in the app.
• Get the agents’ answers and message any agent: reply to a message, use /ask, or pick an agent.
• The bot answers only linked chats and leaves groups.
• Quiet scheduled runs (“Nothing new”) send nothing to Telegram.

#The Server mode

⌘7 opens the current server. Overview shows the health (CPU, memory, disk, network, the processes that use the most) and what the server has installed; Workplaces, Secrets, Ports, Devices, Updates, Backups and Daemon log are the other sections.

#Server settings

Settings → Servers → a server: name, icon and colour; the main server that opens at launch; notifications from this server; the connection (address, user, port, key, with Check the connection and Reconnect); the agents folder and the approval mode new agents get; how many agents run at once; screen sleep; backups; and the nightly update setting.

#Secrets

Keys and passwords agents need are kept on the server (Server → Secrets). An agent gets each one as an environment variable; values are never shown in the chat, and after saving only the last four characters are visible. Choose All agents or the agents that get a secret; removing a secret restarts those agents without it.

#Ports and devices

Ports lists the open ports and who opened them (an agent, a terminal, the daemon), with Open to preview one in the Browser. Devices lists the phones and Macs paired with the server: Add device shows a one-time code, and Revoke cuts off one device at once.

#Updates

When the server has a newer release, a banner above your profile says so with “Update server”, and so does the server menu. The server downloads the release, checks its signature and restarts; the connection drops for a few seconds and comes back by itself. In the server’s settings, Server updates can be Off, Notify, or At night, when no agent works. Server → Updates also shows the manual way: the same install script as the first setup, which keeps your data.

#Backups

The daemon copies its database at start, before an update and once a day, and keeps the newest 14. Server → Backups lists them, makes a copy now and restores one; the current database is kept first and never deleted. If a restore ever leaves no usable database, the server starts in safe mode until a restore works. From a terminal: bandito backup list and bandito backup restore.

#Daemon log

The newest 500 lines of the daemon’s log with a level filter. Secrets and Bandito’s tokens are masked before they are shown.

• There is no Bandito cloud for your code. Code, API keys, sign-ins and chat history live on your servers, and agents talk to the model providers directly, under their own terms.
• An account is optional. It only syncs your server list, shortcuts and prompts between devices.
• Agents can never touch Bandito’s own files or stop its service, in any mode and under any rule.
• The app sends anonymous usage counts and a daily check-in (version, system, number of servers and agents as ranges); crash reports only if you agree. Never messages, code, file names, server addresses or keys. Turn it off in Settings → Privacy; “Delete my data” removes what was sent.
• The website counts visits without cookies or identifiers.

The details are on the privacy page. Report a security problem to security@bandito.dev.

#The app

A banner above your profile says when a new version is out. Update downloads it, installs it and restarts Bandito, with no extra windows. Settings → Updates shows the app’s and the server’s versions and can check now; checking automatically can be switched off.

#The servers

A server with an older Bandito gets an “Update server” button in the banner, in Server → Overview and in the server menu. Some screens need a newer daemon and say “Update the server” instead of the feature. See Servers for nightly updates and the manual way.

#What changed

Every release has notes: see What’s new.

#SSH: host key and connection errors

A host this Mac has not seen asks for its fingerprint to be checked. A changed key is refused: check the server first. A refused or timed-out connection means SSH is not running on that port or the server is not reachable. Check the address and port, make sure the server is on, then press Try again.

#The server does not answer

Check that the server is on and the connection works, then press Retry. The app also reconnects by itself.

#The server did not accept this Mac’s key

The server answers but does not know this Mac: it was reinstalled, lost its data, or the device was removed. On This Mac the app pairs again by itself; otherwise press Connect again and connect it as the first time. Devices are listed in Server → Devices.

#This server runs an older Bandito

Some screens need a newer daemon. Open Server → Updates and run the update, or press Update server. It keeps your data.

#An administrator password is needed

Bandito never asks for the password in the app. Press Open terminal: the command is typed in, you type the password there and press Return.

#Could not install a component

Read the last lines of the log above the message, fix the cause (free disk space, or run the command by hand), then press Install again.

#Chrome is needed, or the browser is not running

Press Install to add Chrome to the server, or Start browser if it is not running. If the preview of a port does not load, check that something is listening on it in Server → Ports.

#The screen does not start

If the screen is asleep, press Start screen. The server screen needs a Linux server; elsewhere use Terminals or the Browser. Start screen names the programs the server is missing and installs them.

#A terminal does not open

Read the message after the colon and press Retry. If it says the server is old, update the server.

#Usage limit reached

The agent’s subscription has no quota left. It waits for the reset, or continues on the fallback runtime you set in its details. The bars are in Settings → Subscriptions and limits.

#The runtime is not logged in

The tool is installed on the server but not signed in. Open a terminal on the server (⌘T) and run the command the message names, for example codex login.

#The file changed on the server

Someone, or an agent, saved the file while you were editing it. Press Show difference, then Keep mine or Take the server’s.

#The pairing code is not accepted

A pairing code works once and is valid for a few minutes. Press Add device (or run bandito pair) again for a new one.

Still stuck? Settings → Servers → a server → Copy report copies versions and the system for support, with no addresses, tokens or paths. Write to hello@bandito.dev or open an issue on GitHub.