Workspaces

A workspace is a folder on your machine that an agent works inside. You can have as many as you like, and each one is a separate agent.

What a workspace is

Each workspace has its own memory, model configuration, job queue, schedule, connectors and extensions. Workspaces are isolated, so an agent can't see another workspace's memory or files unless you set it up to delegate work.

Good ways to split work into workspaces:

• By project: one agent per code repository or client folder
• By role: a Personal Assistant, a Research agent, a Build agent
• By trust: a supervised agent for sensitive work, an auto-mode agent for routine jobs

Create a workspace

1. Open the web UI at http://localhost:3456.
2. Click New Workspace in the sidebar, or go to /workspaces/new.
3. Enter a name and the path to the folder. The folder can be new or existing.
4. Choose a model provider and model.
5. Click Create.

When you create a workspace, AgentOS:

• creates a .agentos/ folder inside your chosen path;
• generates a BRAIN.md with a default identity for the agent;
• registers the workspace in ~/.agentos/workspaces.json.

Give the agent a purpose: BRAIN.md

.agentos/BRAIN.md is the most important workspace file. It is loaded into every request and tells the agent who it is, what the workspace is for, its goals, its conventions and how independently it may act. Edit it in Workspace Settings or in any text editor, and type /brain in chat to view it.

# Workspace Brain

## Purpose
Maintain the TaskFlow REST API (Node.js + Express, PostgreSQL via Prisma).

## Description
Customer-facing API for the TaskFlow project-management app.

## Goals
Ship the v2 endpoints and keep test coverage above 80%.

## Preferences & Constraints
New endpoints follow REST conventions and validate input with Zod. Tests use Jest.

## Agent Trust Level
supervised

## On Job Failure
continue

## Notes
<!-- Add your own notes here. The agent will also update this file. -->

Workspace settings

Open Workspace Settings from the sidebar (/workspaces/:id/settings) to change:

Setting	Stored in	What it controls
Agent name	workspace settings	The name the agent goes by in chat and to other agents
Purpose, description, goals, preferences	BRAIN.md	The agent's standing context
Trust level	BRAIN.md	Supervised (you approve jobs) or auto
Provider, model, host	MODEL.md	Which model this agent uses
Context size, temperature	MODEL.md	Inference parameters
Connectors	workspace config	Which connected services this agent may use
MCP servers	.agentos/mcp-servers.json	MCP servers for this workspace only

Organizing the sidebar

Group related workspaces in the sidebar to keep many agents manageable. The General group always exists and holds any workspace you haven't grouped.

Removing a workspace

Deleting a workspace in the web UI unregisters it from AgentOS. Your project files stay where they are. To remove the agent's memory and history completely, also delete the workspace's .agentos/ folder.