Install
Agent Manager GD is two parts: a Godot app (the window) and a small Python engine that runs where tmux lives: inside WSL on Windows, directly on Linux.
| Windows | Linux | |
|---|---|---|
| The window | the release build (AgentManagerGD.exe) | Godot 4.7 on app/ (no Linux release build yet) |
| The engine | inside WSL: python3 3.10+, tmux, git, ssh | the same, directly |
| Agents (optional) | Claude Code and Codex installed and signed in inside WSL | the same |
| Cloud sandboxes (optional) | flyctl, installed by you (the app looks for it in ~/.local/opt/flyctl and on your PATH; it does not download it), and a Fly.io token in Keys | |
Windows, step by step
- Download
AgentManagerGD-<version>-win64.zipfrom the Releases page (pre-releases for now: take the newest) and unzip it anywhere. - Right-click
install.ps1→ Run with PowerShell. It installs to%LOCALAPPDATA%\Programs\AgentManagerGDfor your user only, without administrator rights, adds a Start menu shortcut, and downloads nothing. Options:-Target <folder>,-NoShortcut. - Start it. If something is missing, the Setup check says what and how. WSL itself
is Microsoft's:
wsl --installonce, in an administrator PowerShell; the rest installs inside WSL with your package manager (sudo apt install python3 tmux git openssh-client).
Update: close the app (sessions keep running), run the new install.ps1. Remove:
uninstall.ps1 in the install folder; your sessions, keys and settings stay until you delete them
(Where your data lives).
Linux, from the source
Get the source:
Download the source (zip),
or clone it (git clone https://github.com/sonixz/agent-manager-gd.git). This archive is the
source only: it holds no AgentManagerGD.exe, so it is not the Windows download above.
Build the terminal extension once (tools/build_native.sh), then open app/ with
Godot 4.7 and run it. The app starts the engine itself.
Setup check
The WSL button of the top bar (on Linux: Computer), or ◐ › Setup check, opens one page: the setup check, then the engine room. It opens on its own at the first launch when the engine cannot start. The setup check reads what Agent Manager stands on, from the ground up, and says what it found. On Windows it starts with Windows itself (its version, and whether virtualization is on), then WSL, then the Linux distribution WSL runs. Then, on Windows and on Linux alike: python3 (3.10+), tmux, git, ssh, the engine, and the optional Claude Code, Codex and flyctl, each with its version and path, or the command to install it.
It stops at the first thing that is missing: the lines under it are marked ·, because nothing can be said of them yet. When the engine does not answer, it says why: it is not running (Check again starts it), it is starting or stuck, another program holds its port, or it runs inside WSL and Windows cannot reach it. It looks first and changes nothing by itself. The window stays free while it reads, which takes a few seconds on Windows.
When python3, tmux, git or ssh is missing and the distribution has apt-get, the check offers
to install them: it shows the exact command, and Install … runs it in a terminal on the page, where
you see everything it does. Inside WSL it runs as the distribution's root, which needs no Windows
administrator and no password; on Linux it goes through sudo, which asks for your password in
that terminal. When it ends, the check reads again and starts the engine if that was all that was missing.
Everything else (WSL itself, the agents, flyctl) is still yours to install: the check says how.
When everything the app needs is there, the ladder is one line of marks, and Show every line brings the lines back. Under it, the Engine room is a dashboard of the ground: you will rarely look at it, and it is there when something is slow or full. Five tiles say the moment. Memory in use: what the programs hold, of what there is; on Windows also what Windows gives WSL, which is more, because Linux keeps files in memory. Sessions running: how many, what they weigh together, and about how many more would fit. Processors busy. Disk: on Windows, WSL keeps a distribution's disk in one file on a Windows drive, so the room left on that drive is the true room, whatever Linux reports; the tile is marked ! when the drive is nearly full. Up for: since WSL, or the computer, started.
Memory in use, by session shows the same over time: one bar per slice of time, one colour per session, and in grey what runs beside them (the engine, tmux, other programs). Choose Last hour, 6 hours, 24 hours or 7 days. Point at a bar to read its time and what each session held. A time when the engine was not running stays empty, and a small mark under the axis says where WSL started anew. When the bars come near all the memory there is, a dashed line shows it. Past eight sessions, the others are drawn together.
The table under the bars lists the sessions: how long each has been open, when its screen last changed,
its memory now and at the most in the span, its share of one processor (100 % is one processor busy all
the time), and whether its folder is on the Windows disk (/mnt/c/…), where git is slower than
inside Linux. The sessions that ended within the span come after the running ones. Click a running
session to open it.
The engine takes one reading every 30 seconds and keeps seven days of them in
data/host_history.sqlite3, in its data folder; nothing of it leaves the computer. Deleting the
file loses the bars and nothing else. AGMGD_HOST_SAMPLE=0 stops the readings, and another
number sets the seconds between two of them. Under the table: the sessions on the Windows disk, and the
Limits your .wslconfig sets, read and never changed.
Restart WSL… (Windows) stops WSL entirely and starts the engine again. It first names the sessions that would stop, then asks you to type « restart »: it also stops anything else you run in WSL. Conversations are kept; restart a session afterwards and it resumes.
How it fits together
Godot app
The window, the native terminal (libghostty-vt), the views, the voice.
Local engine
python3 -m engine, standard library only, on 127.0.0.1 with a token.
tmux
A private server, tmux -L agmgd: one tmux session per Agent Manager session.
Your tools
Claude Code, Codex, git, ssh, flyctl, Second Brain GD: found, never bundled.
Every session is a real terminal running in its own tmux session on a private tmux server. The app only shows it: close the app, and the agents keep working; reopen it, and they are where you left them. Even after a reboot, a session's conversation can be resumed.
Agents are launched as your own installed tools, with your login and your configuration. Agent Manager adds, for that session only, the hooks that report its state, its MCP servers, and (when asked) a short system note: never a change to your global settings, and it never reads, copies or relays your subscription tokens.
Where your data lives
| What | Where |
|---|---|
| Sessions, groups, history, summaries (the engine's database), state files, hooks settings per session | ~/.local/share/agent-manager-gd/ (inside WSL on Windows) |
| The engine's token | ~/.local/share/agent-manager-gd/runtime/api_token |
| Your API keys | the data folder, encrypted for your Windows user (DPAPI) on Windows; file permissions (0600) on Linux |
| Repository deploy keys | ~/.local/share/agent-manager-gd/keys/<id>/ (0600) |
| The window's settings (theme, view, shortcuts) | Godot's user folder: %APPDATA%\Godot\app_userdata\Agent Manager GD on Windows |
| Agents' own conversations | where the agents keep them (~/.claude, ~/.codex): Agent Manager only remembers their ids |
Sessions and live states
+ New session: a name, the tool (Claude Code, Codex or a shell), the group, where (this computer or a cloud sandbox), a connected repository or a folder, and options: its own git branch, the Second Brain, a journal in the Brain, Brief, Remote Control.
| State | Means | From |
|---|---|---|
| working | the agent is on a turn | its hooks (a prompt sent, a tool used) |
| waits for your OK | it asks permission (a command, a file) | its permission notification |
| asks you something | a question for you (ask_owner, or a question from the agent or one of its MCP servers; not the idle reminder after a turn); it clears as soon as you answer, from the app or in its terminal | its notification |
| done | the turn is over | its Stop hook (Codex: turn complete) |
| ready | started, nothing asked yet, or stopped | its session start, or a turn ended without Stop |
Sessions waiting for you go up into They wait for you, first come first, with Approve / Refuse (an OK) or Reply… (an answer), and Open. Approve presses the agent's highlighted choice (Enter), Refuse presses Escape. A toast and, if you turn it on, your system's voice tell you too. A shell has no state of its own.
Right click a session for the rest: rename, move to a group, show in Grid, restart, stop, wrap up, finish its branch, archive, remove. Drag sessions to reorder them or move them between groups; fold a group you are not watching.
The terminal, copy and paste
The terminal is our own: libghostty-vt (Ghostty's terminal core) drawn by Godot, in JetBrains Mono with fallbacks for symbols, CJK and colour emoji. Accents, true colour, the mouse and full-screen programs work as in a good desktop terminal. A change that degrades it is a bug.
- Copy: select with the mouse, then Ctrl+Shift+C. When the program uses the mouse itself, hold Shift while dragging. A long line the program wrapped (a sign-in link) is copied whole.
- Paste: Ctrl+Shift+V.
- Programs that copy (Claude Code's « c to copy »): their OSC 52 copy reaches your clipboard, through tmux too. Programs can write the clipboard, never read it.
Views and themes
The top bar has two families of buttons. View ▾ names the way the sessions are shown (it reads Focus ▾, Grid ▾…) and opens a panel: the five ways (Focus, Grid, Board, History, Review), each with its shortcut, then the seven themes. Beside it stand the managers, one button each: WSL (on Linux: Computer), ⚷ Keys, ☁ Cloud, ✦ Experts, ⎇ Repos. A click opens a manager's page; a second click on the same button comes back to the sessions as they were shown. In a narrow window the managers show their sign alone, and their names stay in the tooltips.
The WSL button is alive: ● when everything stands, ! when something deserves a look (a disk nearly full, memory nearly gone), ✗ when something the app needs is missing or the engine does not answer; then the memory in use. Its tooltip says why. It opens the setup check and the engine room.
- Focus: one session, full size, with its header (tool, folder, branch, Brain, state).
- Grid: up to four live terminals side by side (right click a session → Show in grid).
- Board: a tile per session with a live preview of its screen and its state.
- History and Review, in the same View ▾ list. Then ◆ Orchestrator · beta, ♪ (mutes the small sounds), and in ◐, the settings: Keys, Usage, Agent permissions, Shortcuts, Connect other tools, Setup check.
The seven themes are in the View ▾ panel, the same as Second Brain's: Focus, Terminal, Neon, Evening, Forest, Morning, Paper. Each is a chip drawn in its own colours. Click one and the whole window changes at once; the panel stays open, so you can try them one after the other. The interface and the terminal's colours change together.
The session list shows one session per line: its state dot, its tool, its name, short marks (its permission level, ▣ file access, ⇡ may push, ↻ a change waiting, the ✦ Brain light) and its state in a word. Twenty sessions fit where eight tiles did; hover a line for the rest (its last words, folder, branch, how long). ◐ › One session per line, or List: tiles in the palette, brings back the tiles, which say all of it at a glance. Your choice is remembered. They wait for you follows the same choice: one request per line, with the agent's name (click it to open the session), Approve and Refuse or Reply…, and what it asks in the tooltip.
Shortcuts and the palette
Outside a terminal, Ctrl alone works. Inside a terminal, plain Ctrl keys belong to its programs, so add Shift: with it, every shortcut works everywhere.
| Action | Keys |
|---|---|
| Command palette (every action and session, by name) | Ctrl+Shift+K |
| New session | Ctrl+Shift+N |
| Focus, Grid, Board | Ctrl+Shift+F / G / B |
| History, Review | Ctrl+Shift+H / R |
| Next, previous session | Ctrl+Shift+↓ / ↑ |
| Approve the first session waiting for an OK | Ctrl+Shift+A |
| Dictate, voice command (hold) | F8, F9 |
Change any of them in ◐ › Shortcuts: click one, press the new keys (Escape cancels).
History, resume, fork
Every session keeps every conversation id it ever had: Claude Code gets its id from Agent Manager at launch; Codex reports its own. History lists every session ever made, archived ones included, with its conversations, searchable by name, folder, group or id.
- Resume starts a session again on its latest conversation; Resume this one on any older one.
- Fork… opens a new session on a copy of a conversation; the original stays as it was.
- Archive puts a session away; Restore brings it back. Removing a session keeps its history.
A git branch per session
Tick In its own git branch in New session: the session works in a git worktree,
<repository>-worktrees/<name>, on branch am/<name>, so several agents can
work on one repository without stepping on each other. Finish its git branch… (right click) shows what
is ahead and uncommitted, can merge it into the repository's current branch (a conflicting merge is undone),
and removes the worktree. Uncommitted work blocks it; the branch is deleted only once merged.
Review
Review shows the selected session's changes, file by file (arrow keys), coloured, with line numbers: uncommitted changes, everything since the session started, or its branch against its target. Click a line to comment on it, or comment the whole file. Send review sends the open comments to the agent as one numbered request (file:line, your comment, the line's code). Sent comments stay visible until you mark them Handled.
Permissions
Each agent session has a level, chosen in New session › Permissions; a group can have its own default (right click the group › Default permission level…). The card shows it when it is not auto.
- Ask before acting: Claude Code asks before editing files or running commands (Codex: asks when it needs to, works in its folder).
- Auto edits: edits files without asking, asks before other commands (Codex: never asks, stays in its folder's sandbox).
- Auto, the default: Claude Code's own judgment decides what needs your OK.
- No permission: never asks (Claude Code
--dangerously-skip-permissions, Codex--dangerously-bypass-approvals-and-sandbox). Asked to confirm, marked ⚠ no permission on the card. - Per my config: Agent Manager passes no level option; your own Claude Code or Codex settings decide. Only for sessions you start.
Change it on an open agent: right click the session › Permissions…. A level is set when the agent
starts, so it starts again on its own conversation (nothing is lost): at once when it is idle, at the end of its
turn when it works (the card says ↻ new level after this turn), or at its next start. Its sessions above
the new level come down to it. Only you change a level, from the app; no agent tool does it, and the engine's
token is out of reach of the agents' file tools. Each change is kept in the session's
permissions.log.
Git rights (Claude Code), in the same dialog: Enable git push and Enable git merge and rebase. By default the orchestrator and its sessions may not push, merge nor rebase (pushing and merging are yours); a session you start may. A box lifts or adds the matching deny rules for that session only, applied like a level; the card shows ⇡ may push when you enabled it for an orchestrator's session. Like every deny rule, it covers the commands Claude writes, not a script that runs git itself.
File access, in New session and in Permissions…: Open (Claude Code's default: its file tools read
anywhere except your keys), Contained (its file tools neither read nor write outside its folder and the extra
folders you list: Claude Code's own blockReadsOutsideWorkingDirectories and
blockWritesOutsideWorkingDirectories), Read only (its folder only, no edits; Codex: its
read-only sandbox). Extra folders are read and write or read only; Agent Manager's own data is refused. A session
started by an agent is never less restricted than its parent. Shell commands are not contained: this is a
guard rail on Claude's own file tools, not an operating-system sandbox, unless you also tick the next box.
Contain shell commands too (Claude Code's own sandbox): the operating system refuses what the file access
says, scripts included: its home closed except its folder and the extra folders, your keys never readable, nothing
written in a read-only folder. It never falls back silently: if the sandbox cannot start, Claude Code stops
(failIfUnavailable) and no command runs outside it. Under Linux and WSL2 it needs
bubblewrap and socat, which take administrator rights: you install them yourself
(sudo apt-get install bubblewrap socat); until then the box stays greyed out and says so. Agent
Manager never installs them. Its network goes through Claude Code's proxy: a new domain may need your OK. The card
shows ■ contained instead of ▣ contained. A session started by an agent inside it stays inside.
Agent permissions (◐ › Agent permissions…, or Ctrl+K): every agent at a glance, its level, file access, Claude Code's sandbox and git rights, with Edit… to change them (↻ marks a change waiting for the end of its turn). Each group has a default level and a default file access for its new sessions (right click the group).
At every level, No permission included, Claude Code refuses to read or change ~/.ssh,
~/.aws, ~/.gnupg, the GitHub CLI's login, .env files, Agent Manager's
keys and the Second Brain's tokens (deny rules apply in every mode). This covers its file tools and the file
commands it recognises in a shell; a script it writes and runs could still open those files: only an
operating-system sandbox stops that. Codex has no such list: its sandbox limits writes to its folder. A
session started by an agent never gets a higher level than the agent that started it.
Wrap up and Brief
Wrap up (right click) asks the agent to write its own summary: what was done, decisions, files touched, what is left, how to continue. When the session shares the Second Brain, it also proposes it there. The summary is kept with the session (History, searchable, Read) and the session is archived. A new session in the same folder can start from it: Brief it with the latest summary of this folder sends a short first message pointing to that summary.
Voice
- Dictation: hold F8 and speak. A small see-through box opens at the bottom: what you say is written in it phrase by phrase, a moment after each pause; that first writing is only there to follow you. When you release the key, the box listens a moment longer for the end of your last word, then the whole recording is written down in one piece, and that text takes its place: it reads better, since every word is in its sentence, and it holds your last words. The text then stays in the box: read it, correct it, hold F8 again to add more. Enter sends all of it to the selected session; Shift+Enter is a new line, Esc hides the box and keeps its text. Nothing goes to an agent before your Enter. Into a shell it is only written at the prompt: a spoken line never runs by itself. Transcription by OpenAI with your own key (about $0.003 a minute, shown in the box).
- Commands: hold F9 and say approve …, refuse …, go to …, grid view, who is waiting?, wrap up …, new session …, in English or French. Understood by plain rules, no model. Approving, refusing and wrapping up always ask first. What is not a command is dictation: it joins the text of the box.
- Small sounds, no voice: a soft short blip when an agent waits for you, an even quieter tick when one finishes; ♪ at the top right mutes them. The voice only answers when you ask « who waits for me? ».
If your OpenAI project does not allow a transcription model, Agent Manager tries the next one (gpt-4o-transcribe, gpt-4o-mini-transcribe, whisper-1…) and says what to allow in the project's limits.
What you say is never lost: the box's text is saved on your computer and is still there after you close the app; Earlier brings back what you sent or emptied (the last twenty). A long dictation is written down piece by piece, so it never waits for one long transcription. A piece that cannot be written down is kept: Ctrl+K › Send my last recording again. The box shows how long it has been listening, and listening stops by itself after 5 minutes. Ctrl+K › Dictation box opens the box at any time. If the microphone gives nothing at all (Windows changed the audio device, a headset went off), the box says so after a few seconds and opens it again once; restarting the app brings it back too.
Put the box where you want: drag it by its top line, anywhere in the window; it stays there and remembers its place. A double click on that line sends it back to the bottom of the session. Drag its bottom right corner (◢) to make it larger and see more of a long text; a double click there gives it its own size back. It is see-through while it only waits, and solid while you use it (listening, writing, under the mouse, with the keyboard).
Usage
◐ › Usage: tokens per session, per day and per tool, read from the agents' own logs on this computer (Claude Code, Codex). No money amount for agents: their logs carry none, and subscriptions have no per-token price. Cloud sandbox costs are in Sandboxes.
The Second Brain
When Second Brain GD (its companion app) runs on the same computer, the badge at the bottom left says ✦ Second Brain ● connected, with how many agents are linked and how many proposals they made today, and each Claude Code or Codex session can share it:
- A key per session, named Agent Manager · <session>, at the « propose » level: it reads and searches the Brain; what it proposes waits for the Brain's archivist and your rules. The key is given at launch only, through the Brain's own relay. A fork gets its own key; removing the session revokes it.
- Who proposed what: the Brain's timeline names the session behind each change, and any change can be undone there.
- Sessions that document themselves (↳ Document this session in the Brain as it works, Claude
Code): the agent orients in the Brain first (project card, last session journal, open questions, recent
decisions, your documentation guidelines), checks them against
git logand the live sessions, then proposes your words, decisions and a session journal at each milestone. - The ✦ light on each card, Grid tile and in the header: ✧ faint, no Brain; soft violet, a key of its own; violet, it documents; amber, it documents but has proposed nothing for a while (ask it for its journal); soft red, its key no longer works or the Brain stopped. It pulses when the session just used the Brain; hover it for its calls and proposals. The badge is checked every 10 seconds and opens a small panel: every session's light, the latest proposals and how they ended. Agent Manager reads these counts from the Brain and keeps only titles and numbers, never a key.
- Keys: ⚷ Keys lists every Brain key Agent Manager made and what uses it; unused ones can be revoked, one by one or all at once, always confirmed.
- In the cloud: a sandbox reaches the Brain through its SSH tunnel and the engine, with a secret of its own; the Brain's keys never leave your computer.
Turn it off with AGMGD_BRAIN=off in the engine's environment.
Agent Manager's MCP server
Every agent session is offered Agent Manager's own MCP server, agent-manager:
| Tool | Does | On |
|---|---|---|
list_sessions | every session and its state | any session |
session_status | working, waits, asks, done | any session |
read_screen | what a terminal shows now | any session |
list_machines | every cloud machine: state, sessions, whether a port is bound to its public URL (and which), « yours » | all machines |
create_machine | asks you for a cloud machine, without a volume (a sandbox) or with one (for a service), persistent or not: repository, size, name, expert, secrets it holds; waits for your answer; its first session is the agent's child | on your approval |
destroy_machine, expose_machine | ask you to destroy one, or to bind one of its ports (port) to its public URL; wait for your answer | its own machines, on your approval |
stop_machine, start_machine, unexpose_machine, machine_status | pause, start again (within the budget), unbind its public URL, read one machine or a request | its own machines, at once |
list_experts | the experts: what they know, the tool, the secrets they need | the owner's experts |
start_session | a child session: Claude Code, Codex or a shell; with sandbox, on that cloud sandbox's machine (never a new machine); with expert, as that expert (its secrets only if the parent holds them) | new, shown « ↳ parent » |
send_to_session | write to a session | its own children only |
wait_for_session | until a child is done or waits | its own children only |
Cloud machines for agents. What costs money or faces the internet is asked, never done, by an agent:
create_machine, destroy_machine and expose_machine put a request in
They wait for you (« loop0 · Approve… · Refuse »); the confirmation says exactly what (kind, size, the
monthly price while it runs, repository, port, expert, secrets). Agent Manager does it only once you approve,
and the agent's tool waits for your answer. An agent acts only on its own machines (their first session descends
from its root session), at most two per root session (requests waiting counted); a session it starts in a machine
gets its level, never more than its own, and only reads on an exposed machine; it can give a machine only the
secrets its own session holds, by name. The pause after idle time still applies to sandboxes. When you drive an
agent from afar, its Permissions have Cloud machines without asking: its requests (and those of the
sessions under it) are done at once, kept in the requests with who allowed them; the limits stay (its own
machines, two per root session, your monthly budget, the secrets it holds).
No tool presses keys in someone else's session: an agent never approves on another's behalf. ◐ › Connect other tools gives the command to plug the same server into Claude Code, Codex or any MCP client outside the app; such a tool can list, read and start sessions, never type into one or approve.
A public URL per machine
Every cloud machine (ours, on Fly.io) made since Loop 48 can serve the internet, when you decide. It is made private: its own Fly.io app, and Fly.io's HTTPS (port 443, Fly's certificate) declared toward one door inside the machine, port 8443, with no public address: nothing reaches it. In the machine, the door passes each connection on to the one port you bound, and to nothing when none is bound.
- Bind to a public URL: in a machine's Tunnel and ports, each port that listens has it beside
Bring it to my localhost; its card also has Bind a port to the public URL…, which asks for the
number. You confirm first. The door is set toward that port, then the app gets two public addresses (an IPv6
and a shared IPv4, both free):
https://<its app>.fly.devreaches that port, live, without restarting the machine. The service may listen on127.0.0.1. - One public URL per machine: binding another port moves the door; the address stays, the port bound before is no longer reached. Its SSH, the door itself and everything else stay private.
- Unbind (on the port's line, or Unbind the public URL on the card) gives the addresses back and closes the door: nothing of the machine is reachable from the internet. The machine, its service and its data stay.
- The door, drawn: the internet, the gate 443 (lit with visitors flowing when a port is bound, barred when private), the door 8443, your service and its port, what stays private, and Agent Manager's own way in from below. A machine's line shows its gate and PUBLIC → :port; the tiles count the public URLs.
- Machines for a service: + A machine with a name, a volume, a repository… (☁ Cloud, step 2)
takes a name (in its address, optional), a volume in GB (0: none), its disk (Sandbox or
Persistent, below), its size (the smallest first, with its
price), a connected repository (cloned with its own deploy key), an expert, the secrets of Keys › Secrets
the machine gets, and the tool of its first session. With a volume,
/datalasts (about $0.15 per GB a month; its work in/data/work), the agent writes/data/start.sh, which runs at every start with its secrets (output in/data/start.log), and Fly.io starts the machine again if it stops; the card says whether the start script is there and shows the log's last lines. Without a volume it is a sandbox, in its own app. An agent on a machine is told the way (in its~/.claude/CLAUDE.mdor~/.codex/AGENTS.md): its public URL reaches nothing until you bind a port, the rest on127.0.0.1, never to bind or expose anything itself. - Test on your localhost first: Tunnel and ports › Bring it to my localhost opens the port on your own computer, nothing public; when it works, Bind to a public URL.
- Machines made before: a cloud sandbox (ours, on Fly.io) made before Loop 48 lives in the shared app and stays private for good. An Online machine made before keeps its door 443 → its own port: its public URL goes to that port only. The image must be rebuilt (☁ Cloud, step 1: Rebuild) for the door: a machine made from an older image says « door missing » and cannot be bound.
- Tried on Fly.io (2026-11-14, a throw-away machine): before the bind the name did not even resolve;
port 3000 bound,
https://…fly.devanswered with Fly.io's certificate from a server listening on127.0.0.1:3000; moved to 4000, the other server answered, the machine not restarted (same uptime, the same door, the same two addresses); unbound, nothing answered. A name your computer asked for before the bind can stay unknown to it for a few minutes (the « no such name » answer is kept). - No plain HTTP: an address typed with
http://does not answer. The budget's automatic pauses never stop a machine with a volume. Destroy destroys its whole app, volume and addresses included.
Experts
✦ Experts, in the top bar, holds agents that know a trade rather than a product: frontend, documents, an
API like Discord's. An expert is a short role, a set of skills, the names of the secrets it needs, and a
tool by default. A skill is a folder of the open Agent Skills format
(a SKILL.md with its name, what it is for and its instructions, maybe scripts): Claude Code and
Codex both read it, and load it only when the task needs it.
- Skills: Add Anthropic's skills… downloads github.com/anthropics/skills once, pinned to the commit it is at. Each skill has a card: what it is for, its licence (a mint dot for Apache 2.0 or MIT, amber otherwise), the scripts it holds (they run when an agent uses it) and the experts that use it; click it to read it. Check for updates shows what changed upstream, skill by skill (new, changed, removed, and in colour the scripts added); Update to … moves the pin, on your OK only. Import a folder… copies skills from a folder of your computer into your own skills (the folder of one skill, or a folder of skills; one of the same name is kept). Add a git source… adds any public git repository of skills (https), pinned and updated like Anthropic's.
- Experts: Add the three starters makes Frontend, Documents and MCP builder from Anthropic's skills; + New expert and Edit set its name, glyph, tool, model, its role (short: it is read at every turn), its skills and the secrets it needs. Its emblem draws its skills as beads (warmer when they hold scripts) and its secrets as small keys.
- ▶ Launch: a connected repository or a folder, its own worktree or not, Claude Code or Codex, a
level, a name. Its secrets must be in Keys › Secrets; they go to that session only. Claude Code gets the
skills as a plugin of that session only (
--plugin-dir: nothing is written in the repository) and the role in its instructions. Codex reads skills from its folder: it gets its own worktree, the skills are linked into its.agents/skillsand kept out of git (.git/info/exclude), and the role goes in its developer instructions. - Its memory: launched with the Second Brain, an expert first searches it for « Expert · its title » to read what it learned on other projects, and proposes each lesson that will serve its trade again (a trap of an API, a way that works), titled « Expert · its title · the lesson ». Its card counts its lessons and shows the latest. It is how an expert gets better from one project to the next.
- In the cloud: in a new cloud sandbox launches it on a new Fly.io machine; an Online machine's
form has an expert for its first session. Its skills are sent to the machine (Claude Code's
~/.claude/skills, Codex's~/.agents/skills) and its role into the machine'sCLAUDE.mdandAGENTS.md; on a machine every session sees every expert there. - For agents:
list_expertson Agent Manager's MCP server shows the experts, andstart_sessiontakesexpert: the orchestrator gives a task that matches one to it. An agent never gets a secret by launching an expert: the child gets only the expert's secrets its parent holds already; otherwise it is refused, and the owner launches it. - Where they live: no repository is needed: they work in Agent Manager's data folder; Keep them in a repository… uses a
connected repository instead (for instance a private
agent-experts), so experts, your skills andsources.lock(the sources and their pinned commits) are versioned and follow you. Downloaded sources stay in Agent Manager's cache.
The orchestrator
One Claude Code session with an orchestrator's instructions, for all your connected repositories, in a panel on the right (Ctrl+O, or Start in that panel). It plans, delegates, follows and checks; it rarely codes.
- It asks first. It reads the Second Brain, proposes a plan (tasks, repository, tool and model for each) and waits for your answer: the question shows in the panel and in They wait for you; reply there or in its terminal.
- It delegates with its own tools on Agent Manager's MCP server:
list_repos,start_session(a connected repository, a worktree, a permission level, a model, documenting in the Brain),send_to_session,wait_for_session,read_screen,ask_owner,finish_session. Its sessions appear under it in the panel and in the list. - You review and merge.
finish_sessionhands you a finished session (ready for your review); Finish merges its branch. The orchestrator and every session under it are refusedgit push,git mergeandgit rebase(Claude Code deny rules). - Limits: at most 4 sessions running under it at once, 2 levels deep (its sessions may start one level of helpers), never a higher permission level than its own. Their permission requests come to you. Stop all ends it and every session under it; nothing is deleted.
- Routing: Routing rules… in the panel says which tool and model for which kind of task (by
default: hard bugs and architecture → Claude Code Opus; everyday work → Sonnet; small edits → Haiku; a second
opinion → Codex). It reads them (
routing_rules) before choosing and says why when it departs from them; its routing choices go to the Second Brain with its journal. - Its plan, live: after your OK it writes its plan (
set_plan) and keeps it current (update_task): each task with its tool, model, why, and its session's state. - Budget: Budget… sets a daily token budget for it and its sessions; the panel shows today's tokens, read from the agents' own logs (UTC day, no money amount). Once it is spent, it cannot start sessions.
Repositories and their keys
GitHub CLI. At the top of ⎇ Repos, a band reads your own gh: installed or not (Agent
Manager does not install it), its version, the account logged in, the token's scopes, and where gh keeps its
token: the system's keyring, or a plain file of your home folder that every program you run can read, agents
included (said in orange). Log in with gh… and Log out… open a terminal with
gh auth login --web or gh auth logout: you answer there, and Agent Manager never
sees the token. Logged in, a GitHub repository's line has Add it with gh (with write access
ticked by default, so agents can push their branches): gh adds the repository's own public key as its deploy
key, then Agent Manager checks it and reads back from GitHub whether it may push. + New repository on
GitHub creates one under your account, private unless you choose Public (asked again), connects it here
with its own key and adds that key. The visibility of an existing repository is never changed. Agents never
get gh's token: each session gets its repository's own key.
⎇ Repos opens on four tiles (the keys that work, the repositories that need a hand, the sessions running, the hosts), then lists the connected repositories, one per line, each column a small drawing: Host, a chip (a disc for GitHub, a diamond for Azure DevOps, a ring for another host); Key, a disc when it works, a ring when it waits to be added, a cross when it does not work, with a thin bar that empties in ten minutes, the age at which the page checks it again, and a sign that turns while it is checked; The key opens, one square for this repository only, a pile of squares for your whole account; Folder, yours or Agent Manager's copy, its branch in a chip, then a triangle up for commits not pushed, a triangle down for commits behind, a square for files changed; Sessions, a dot per open session in the colour of its state (a session at work breathes; click a running one to show it); Started, 14 days, the sessions started on it day by day, today at the right. Rest the pointer on any of them for the words. The repositories that need a hand come first, already unfolded. Click a name or its arrow to unfold a line: the public key and Copy the public key, where to add it, the key's kind and age, Check, Rotate the key, Disconnect, the folder, and Branches and their folders, a map drawn like a metro's: the base branch is the line at the top, its latest commits as stations, now at the right; each branch that has commits of its own, a folder of its own (a worktree) or an open session leaves it where it was made and runs under it, one station per commit. At the right of each line: its name, a triangle up with its commits, a triangle down with what the base made since, a small folder when it is checked out in a worktree, and a dot per session working there. Rest the pointer on a line for its words, click a line whose session runs to show that session. Branches merged and left with nothing of their own are counted under the map, not drawn. It is read from the disk: nothing is fetched. New session starts a session on that repository. In a narrow window some columns leave, the host last. The ⎇ Repos button of the top bar carries a ! or a ✗ when a repository needs a hand.
+ Connect a repository opens the form: give the repository's SSH address and its folder (your own
clone, or Agent Manager clones it in its data folder). As you type, the form says which host it is and what
its key will open. A web address (https://…) is answered with its SSH form, filled in for you.
- GitHub (
git@github.com:owner/repo.git): an ed25519 deploy key for that repository only. Open GitHub's Deploy keys page from the line, paste the key, tick Allow write access so agents can push their branch, then Check. A leaked key never opens your other repositories. - Azure DevOps (
git@ssh.dev.azure.com:v3/organization/project/repository, the address under Clone › SSH): Azure DevOps accepts RSA keys only and has no key per repository. Agent Manager makes an RSA key; you add it to your profile (User settings, the icon beside your picture, then SSH public keys › New Key), then Check. That key opens everything your account reaches there, and the line says so. To keep agents to chosen repositories, add the key to an Azure DevOps account made for them, which reaches only those. Azure DevOps keys expire: it warns you by e-mail seven days before; Rotate the key then. Not tried yet against a real Azure DevOps repository. - Another SSH git host: an ed25519 key; what it opens is that host's rule.
Opening the page reads each folder again and checks again the keys that were checked more than ten minutes
ago; each line says checking…, then how old its answer is. Check all does it at once. A check
is one SSH connection to the repository's host with that repository's key (git ls-remote):
nothing is changed there, and nothing is checked while the page is closed. A repository still waiting for
its key is not checked until you press Check. The folder is read from the disk: nothing is
fetched.
Sessions on a repository use its key only, through GIT_SSH_COMMAND with
IdentitiesOnly=yes and a known_hosts of their own: nothing goes into your ~/.ssh or the
repository's git config, and the agent is told how git authenticates. A session opened in the repository's
folder, a subfolder or a worktree gets the key too.
- Rotate the key: a new key of the same kind replaces the old one; add the new one on the host and delete the old one there (its fingerprint is shown).
- Disconnect: the key is deleted here; delete it on the host too.
- The private key (
keys/<id>/id_ed25519orid_rsa, 0600) is never printed, logged or sent.
git ls-remote origin in the session. A bare
ssh -T git@github.com ignores the session's key and shows your own account.Remote Control
On by default for Claude Code: the session is started with Claude Code's own Remote Control under the name Group · Session, so you can follow and answer it from claude.ai/code or the Claude app. Its card shows ⇄ claude.ai. It needs a Claude account with Remote Control; untick it for sessions that should stay on this computer only.
Cloud machines and costs
☁ Cloud, in the top bar, holds every cloud machine (ours, on Fly.io), the sandboxes and the machines for a service on one page (Loop 48: they were two pages, Sandboxes and Online). A cloud sandbox is a throw-away Fly.io machine made for a session, with your Fly token (Keys). Each machine made now has its own Fly.io app and can be given a public URL, one port of it, on your word.
Several sessions on one machine. A sandbox's card lists Sessions on this machine, each with its state and Open. + Claude Code, + Codex or + Shell opens one more on the same machine: no new machine, no cost but its share of the processor, up to 8 sessions. Each has its own terminal in the machine (its own tmux session, found again after a reconnection) and its own SSH connection, so a connection that falls touches one terminal only. A Claude Code or Codex session added to a sandbox that holds a repository works in its own git worktree, on its own branch, beside the sandbox's clone: two agents never edit the same checkout. A shell works in the sandbox's folder. The Second Brain is the sandbox's, one for the machine. An added session can be archived or removed (its terminal in the machine closes; its worktree and files stay); the session that made the sandbox stays until the sandbox is destroyed, and destroying it closes every session on the machine. The pause after idle time counts the activity of all of them.
The ☁ Cloud tab is a dashboard: five tiles across (running, public URLs, paused, destroyed, at Fly.io), then two columns. On the left, what you use to make one: Deploy with the sizes, the Costs, and the Image (one line once it is built; Contents ▸ shows what it holds). On the right, the cloud sandboxes, one per line like the repositories; click a name or its arrow to unfold everything about it: its state, its actions, its tunnel and ports. In a narrow window the columns stack. The list is the inventory, and it is always there: every sandbox made from this computer, the destroyed ones too. Four tiles first: running now, paused (only their disk is billed), destroyed and kept in the inventory with what was measured in all, and At Fly.io now, the machines Fly.io holds at this moment, marked when one of them is unknown to Agent Manager. Then one line per sandbox: its state (a disc that breathes when it runs, a ring when it is paused, a cross when its machine is gone at Fly.io, a struck ring when it was destroyed), its name, its size and region, and its life over the last 30 days as a bar: filled where its machine ran, a small triangle where it was made, a cross where it was destroyed; then how long it ran in all and what that cost. The runs come from Fly.io's own machine history and are kept after the machine is gone. Rest the pointer on a line for its dates and its machine. When Fly.io cannot be reached, the inventory still shows what was last known, and says so.
Under the inventory come Your sandboxes. A running one has a block Tunnel and ports: this is
how a sandbox becomes an extension of your localhost. Connect opens one lasting SSH connection to
the sandbox, apart from its terminal (closing the terminal no longer closes it; it never starts a paused
sandbox). The block then shows how the cloud sandbox is doing, like htop: four small charts over the last
fifteen minutes (its processors, its memory, its network in and out, its load), each with the figure of now
and a word when it is busy or nearly full, and its busiest programs with the processor and memory each
takes; a reading every five seconds while the connection is open. It lists what listens there: a web server, a Streamlit dashboard. Bring it to my localhost opens that
port on 127.0.0.1 of this computer, on the same number when nothing holds it there, in WSL or
in Windows (Windows' own listeners are read with its netstat, read only); else on the next
free number, and the port's line says why in orange: « 8000 is held by a Windows program, so 8001 ». The
number chosen is kept for the next time, so a bookmark keeps working. Open in the browser shows it.
A cloud sandbox whose image has no ss still lists its ports (read from the kernel's own list,
without program names). A wire is drawn between this computer and the cloud sandbox for each
port brought here: dots run toward the cloud sandbox for what is sent and back for what is received, with
both rates and the totals. Pause keeps the port but carries nothing; Close gives it back;
Disconnect closes everything that connection brought. What you opened for a cloud sandbox is
remembered: it comes back, on the same address, the next time you connect. Two cloud sandboxes that listen
on the same port each get their own address here: the first keeps the number, the second takes the next
free one, and each keeps its own afterwards. A connection that falls comes back by itself (after 5, 15, 30
seconds, then every minute, ten times), with what it carried; the block says why it fell and when it tries
again. Open a SOCKS proxy gives one address on this computer through which a program set on it
reaches everything inside the cloud sandbox. In the other direction, a cloud sandbox reaches nothing of
this computer but its way back to the Second Brain (only the Second Brain's route passes it, request by
request; when the lasting connection is open it carries that way, so the agent keeps the Second Brain
after its terminal is closed), unless you make a rule:
Let the sandbox reach a port of this computer… makes that one port reachable from inside the cloud
sandbox, on the same number there, until you close it; its wire shows what is asked and answered. Nothing is ever made public: every port
listens on this computer only. The sandbox's host key is remembered at the first connection, and a key
that changed refuses. Not tried against a real sandbox yet: only against stand-ins for Fly.io and SSH.
Then the tab works in steps. In Deploy, one card per size a cloud sandbox can have on Fly.io (shared 1 CPU with 256 MB, 512 MB or 1 GB, shared 2 CPU with 2 GB, performance 1 CPU with 2 GB, performance 2 CPU with 4 GB), each with its price a month and an hour while it runs and a bar against the dearest; click one and the next cloud sandboxes get it (one that runs keeps its size). The prices are Fly.io's published ones, read on its pricing page on 2026-11-12, for its cheapest regions (iad, ewr); Fly.io says prices vary by region, so elsewhere the page says they are floors.
- The image: Ubuntu 24.04, tmux, git and OpenSSH, an SSH server with keys only, Node, Python, Claude Code and Codex. Deployed once to your organisation's private registry; Rebuild for newer agents.
- Deploy: the estimate first (per hour running, per day if left on, per month paused), then a shell or an agentic coding session. Ready in about 30 seconds; its terminal opens like any session and says what it does while it connects. If the cloud sandbox cannot be reached it tries three times, then waits for Enter; a lost connection comes back by itself, on the same session in the sandbox. A paused sandbox is never started again without you: its terminal asks first.
- Costs: today, this month and a chart against your budget, measured from Fly's machine history × the published price (Fly's invoice stays on its dashboard).
Each sandbox has a live card: time on, the SSH tunnel and its latency, the Second Brain through the tunnel, the branch, files not committed and commits not pushed, and its cost. Budget: a monthly amount (a warning past 80 %, no new sandbox at 100 %) and two caps you can turn on that only pause: a sandbox idle for N minutes, or all of them once the budget is reached. Stop everything pauses every running sandbox.
/data) is kept. Commit and push before you pause one, or before an idle pause
could come. Fly.io can keep the whole disk too (its --rootfs-persist setting, tried once on a test
machine: a file stayed across a stop and a start). So you choose it when you make a machine (☁ Cloud, step 2):
Sandbox, its disk starts again from the image after a pause (the default, and what New session › a
cloud sandbox makes); Persistent, its whole disk is kept across pauses. The card says which one a
machine is. Fly.io bills a paused machine's disk either way; whether keeping it costs more was not checked.Keys and secrets
⚷ Keys, in the top bar between WSL and Sandboxes (or ◐ › Keys), lays out three numbered steps, each needed only for what it opens: 1 · Voice dictation (the OpenAI key: hold F8, the sound is transcribed with your key), 2 · Cloud sandboxes (the Fly.io token, and an Anthropic key for Claude Code inside a sandbox), 3 · Your projects' secrets, with dotenvx (the vault below). A step's disc fills with a ✓ when its key is there; a dashed disc is a step you can skip. It holds your own API keys: OpenAI (voice dictation; Codex in sandboxes), Fly.io (sandboxes), Anthropic (Claude Code in sandboxes). On Windows each one is encrypted with DPAPI for your Windows user; on Linux the file is protected by its permissions (0600), and the screen says so. A key is never shown again, never written to a log, and read only when a feature needs it. Below them, the Second Brain keys Agent Manager made.
Secrets, at the top of the same page, hold the keys of your projects: an ElevenLabs key, a GitHub
token, a dotenvx private key. Each has a name in the form of an environment variable
(ELEVENLABS_API_KEY), a note, and the same encryption as the keys above. A secret goes only to the
sessions you give it to: tick it in New session, or use Give to a session… on its card (from that
session's next start: Restart it to give it now). When such a session starts, its program receives the
secret in its environment through a single-use ticket traded with the engine: the value is in no file, not in
tmux's environment, not on a command line, and the other sessions do not have it. AGMGD_SECRETS
lists the names a session received. Each card draws a padlock (closed when Windows encrypts it), a chip per
session that holds it and fourteen bars for how often it was handed over; the journal keeps who received what
and when, never a value. Take back from… stops giving it from that session's next start; a program
already running keeps what it had.
With dotenvx: keep the project's .env encrypted as dotenvx makes it, put its private key in the
vault as DOTENV_PRIVATE_KEY (or DOTENV_PRIVATE_KEY_PRODUCTION…), give it to the
session, and dotenvx run -- python script.py works as it is. Agent Manager does not install dotenvx.
What it does not do: a program given a secret can read it, and print it. The sessions run as the same Linux user, so a determined program could also read another session's memory. The vault keeps a key from being everywhere in WSL; it is not a wall between agents.
On a cloud machine (a sandbox or an Online machine), the secrets you give to its sessions are written
there when its terminal connects, in one file only root reads (/root/.agmgd/secrets; on an
Online machine also /data/.agmgd/secrets, for its start script), and are in the environment of
its sessions. On a machine every session is root: each can read every secret given to that machine. Taking
one back empties it from the file at the next connection; a program already running keeps what it had.
Each handover is in the journal (« given to cloud machine … »).
Agents' own logins (your Claude or ChatGPT subscription) stay with the agents: Agent Manager never reads, copies or relays them.
Local engine and settings
The engine listens on 127.0.0.1:8790 only, and every call needs the bearer token in
runtime/api_token (JSON in, JSON out; request logs never hold the token). The app is its main
client; the MCP server and the hooks use it too. Resources: /sessions, /groups,
/tree, /history, /summaries, /repos, /keys, /secrets,
/brain, /usage, /voice, /sandboxes, /health.
| Environment | Effect |
|---|---|
AGMGD_HOME | the data folder (default ~/.local/share/agent-manager-gd) |
AGMGD_PORT | the engine's port (default 8790) |
AGMGD_TMUX_SOCKET | the private tmux server's name (default agmgd) |
AGMGD_BRAIN=off | no Second Brain; AGMGD_BRAIN_HOME, AGMGD_BRAIN_REPO point to it when it is not found |
AGMGD_CLAUDE_DIR, AGMGD_CODEX_DIR | where Usage reads the agents' logs |
AGMGD_VOICE_MODEL | the transcription model to try first |
Security and privacy
- Local-first: nothing leaves your computer unless you ask (a transcription, a sandbox, a push).
- One public door, on your word: a cloud machine (ours, on Fly.io) faces the internet only once you bind one of its ports to its public URL, and then only that port, through Fly's HTTPS. Unbinding gives its addresses back at once. The engine and the MCP server never get a public address.
- Your agents, your login: agents run as you installed them; their subscription tokens are never read.
- No administrator rights: installs for your user only.
- No silent downloads: third-party binaries only with your OK, pinned and checked against a published checksum.
- Keys: encrypted (Windows) or 0600 (Linux), never shown again, never logged. Deploy keys open one repository each.
- Agents among themselves: through MCP they can read any screen but write only to their own children, and never approve.
- The Brain: agents only propose; the archivist and your rules decide, and nothing is ever erased.
Troubleshooting
The app says the engine is not running
- Open the Setup check: WSL, python3 3.10+ and tmux are needed. If a test run left
an engine on the port:
pkill -f "^python3 -m engine --port 8790".
A session's state is wrong or stuck
- States come from the agent's hooks, installed per session at launch: a session started before an update needs Restart. A turn ended with Escape shows ready after about 15 seconds.
Git asks for a password or uses another account
- Use the SSH address (
git@…), nothttps://. Check the deploy key with Check, and from the session withgit ls-remote origin. Push refused: tick Allow write access on GitHub.
The Second Brain shows as not connected
- Start Second Brain GD on the same computer; the status bar gives the reason. Sessions started before it ran need a restart to get their key.
Voice does nothing
- Check the OpenAI key in Keys, the microphone permission, and the toast's message. A 403 means the key's project does not allow a transcription model: allow one in its limits.
Something in the terminal looks wrong
- Accents, colours, keys or speed: that is a bug, and a regression for us. Please report it with what you ran.