How Botman runs your agents’ work on your own machine, safely. Each conversation, workflow run, and scheduled routine gets its own private, sealed space — a room — with everything it needs inside and a single, guarded way out.
A message from you — or a tick of the schedule — reaches the control plane, becomes one job, and the runner on your machine opens the right room for it. Inside the room is everything the work needs; the only way out is its door. Everything below breaks this picture down, piece by piece.
A room is a Docker container — an isolated, sealed environment on your machine — plus a folder on disk, created for exactly one piece of work. The container starts with no special privileges, runs as an ordinary user, and has limits on CPU, memory and number of processes. It can see its own folder and the read-only toolbox, and nothing else on the machine: not the runner’s files, not any other room.
Every job for that piece of work runs inside the same container. So a conversation keeps its files and history from one message to the next, and step 4 of a workflow can open the files step 1 produced — nothing is copied around or re-explained.
Before rooms, every job started from a blank slate: a fresh container per chat message and per workflow step, files copied between steps, a conversation rebuilt each time from its last fifteen messages, and any tool the agent installed gone when it finished.
A room cannot reach the internet directly. Its only way out is its door: an Iron Proxy sidecar — a second, small container that sits between the room and the outside world on a private network of its own. Iron Proxy is an open-source (Apache-2.0) egress proxy built for exactly this job: it refuses all outbound traffic by default, inspects HTTPS traffic using a certificate the room is set up to trust, swaps in real credentials at the boundary, and writes a structured log of every request. Botman pins an exact version of it.
So for every request an agent makes — fetching code from GitHub, calling the AI model, opening a web page — the door does three things:
The door is started when a job starts, with exactly that job’s allowed places and credentials, and removed when the job ends. The room’s private network has no other route: no direct internet, no raw connections, no way around DNS, no cloud metadata address. A room with no job running can’t reach anything at all.
| Room | What it is for | What its door lets through | How long it lives |
|---|---|---|---|
| Chat | One conversation or thread. Each new message wakes up the same room, so the agent still has the files it opened and the things it worked out last time. | the tools you have connected — GitHub, Slack, Linear, and so on, through Botman | Goes quiet when the conversation does, wakes on the next message, and is removed after 7 days without a message. |
| Workflow | One run of a workflow, all its steps. Steps run one after another in the same room, so a later step can read an earlier step’s files directly — nothing is copied between them. | your code repositories + the tools of the agents in that workflow — known the moment the run starts | Until the run finishes or is cancelled, then removed 2 days later. While it waits for your approval, the room is paused, not deleted. |
| Routine | One run of a scheduled routine — usually a few minutes. A small note carries over between runs (for example, what was already posted). | only the websites you named when you created the routine + the channel it reports to | Until it finishes and reports (or stays quiet when there is nothing to say). Then it is removed right away. |
A room lasts as long as its piece of work. Jobs come and go inside it; the door goes up for each job and comes down after. Here is the whole life of a room, in order.
The toolbox is read-only inside a room, so one session can’t change what other rooms run — and a package’s install script never runs on your machine itself. When an agent needs a tool, it asks with a small command, botman-tools install node (or botman-tools npm <package>, botman-tools pip <package>). That writes a request into the room’s requests/ folder — the one and only channel from a room to the runner, and it carries nothing but names.
The runner sees the request and installs the tool while the agent waits: well-known tools through pinned installers, npm and pip packages inside a temporary container that can see the toolbox and nothing else. The result lands in the toolbox, ready for every room, and it is still there long after the session that asked for it has ended.
A browser works the same way. When a testing agent uses one (Playwright, driving a Chromium inside the room), it runs inside the room and every page it loads goes through the door. Which websites it may open comes from your project’s test address and the run’s own deployment previews — set by Botman, never chosen by the agent on the spot.
Every step below happens inside a room, and every request to the outside world goes through a door. Replies come back to the thread you started in.