Workspaces
Workspaces
A workspace is a project's code checked out on one of your worker machines, so that an agent can read and change its files and run commands there. It is how an agent works on real code: on a separate machine, in a directory kept for that one project, never inside MaxSuite itself.
In the sidebar under Admin → Workspaces. Needs: Devices and Projects.
Workspaces screen
The screen lists each checkout: its project, state, branch, the machine it is on, its path there, the account it runs as, and when it was last used. Preparing and running happen from an agent, not from this screen.
How a workspace works
- One checkout per project. It lives on a worker machine from Devices that can host workspaces and has git. The first preparation goes to whichever such machine is free. After that, every command for the project goes to the machine that holds its checkout.
- One branch at a time. Preparing another branch switches that same checkout for everyone working on the project. A call that names the branch it expects is refused if the checkout has since been switched.
- One command at a time. A command holds the checkout until it finishes, so two agents on the same project cannot run over each other.
- Kept inside the checkout. Any file path or working folder that resolves outside the checkout is refused.
- Some commands are never run, whatever asks: wiping the disk, shutting down or rebooting the machine, formatting disks, changing system users, reading the system's password files, and piping a download straight into a shell.
- Who it runs as. Commands run with the rights of the account the checkout belongs to on that machine. That can be root, and then a command could read every other project on the machine. Each answer says who it ran as.
A command that prints nothing for 15 minutes is treated as stuck. No command may hold the checkout for more than an hour. Commands are never retried.
Who can do what
| Permission | What it lets you do |
|---|---|
workspace:read — See workspaces and read files in them | List the checkouts and read files and folders in them. |
workspace:write — Change files and run commands in a workspace | Prepare checkouts, write files and run commands. |
What happens on its own
Nothing runs on a schedule.
Needs
Devices (a worker machine that can host workspaces) and Projects.
What agents can do
Agents use workspaces to check out code, change it, and run its builds and tests. Pass the branch you prepared to every call after workspace.prepare, so work never lands on a branch someone else switched to. See Agents and approvals.
Read (run straight away):
workspace.readreturns one file.workspace.treelists what is in the checkout, leaving out.gitandnode_modules.
Change (need approval by default):
workspace.preparechecks out the project's repository, or brings the checkout up to date. Needed once before anything else works. The first time it needs the repository's address.workspace.writewrites one file, creating the folders above it.workspace.runruns a shell command and returns what it printed. A failing command is an answer, not an error. Classed as destructive, because a command can be anything.
Over MCP the same tools are named workspace__prepare and so on.