Skip to main content

Understanding Workspaces

Workspaces are organizational containers that group related projects, code, and resources together. They're the fundamental unit of organization across all Lovelace products, providing consistent structure whether you're using the CLI, Studio, or Agents Cloud.

The Core Insight

Software development involves juggling multiple contexts: different projects, different teams, different environments. Traditional tools make you manage these contexts separately in each tool you use. Lovelace workspaces solve this by providing a single organizational model that works everywhere.

Think of a workspace as a room in your development house. Everything related to a particular effort—code, conversations, documentation, AI agents—lives in that workspace. When you switch workspaces, you switch context completely, and every Lovelace product understands that switch.

Organizational Hierarchy

Lovelace uses a clear hierarchical structure to organize work:

Organizations represent companies, teams, or collaborative groups. They're the top-level container for everything else.

Accounts belong to organizations and represent billing entities and access boundaries. A single organization might have multiple accounts for different departments or projects.

Workspaces sit within accounts and organize related development efforts. This is where most work happens—grouping repositories, agents, and resources that belong together.

Projects exist within workspaces and represent specific work initiatives. They can map to external project management systems like Linear or GitHub Projects.

Modules are the actual software units within projects—repositories, libraries, microservices, or any coherent piece of software.

This hierarchy provides natural isolation: agents in one workspace can't accidentally access another workspace's data unless explicitly granted permission. Teams get clear boundaries, but can share resources when collaboration makes sense.

Workspace Contents

A workspace contains everything needed for a development effort:

Code and Repositories: Link git repositories to workspaces. When you clone a repo through Lovelace CLI, it automatically associates with the current workspace. Changes to code trigger workspace-aware AI assistance.

AI Agents: Agents are configured per-workspace. An agent working in your production workspace has different tool access and permissions than the same agent type in your development workspace.

Resources: Knowledge bases, documentation, API connections, and execution resources are workspace-scoped. This keeps sensitive production credentials separate from development environments.

Conversations: AI conversations and collaboration threads live in workspaces. When you switch workspaces, you switch context—the AI understands it's working on a different project.

Settings and Preferences: Workspace-specific configurations for build tools, deployment targets, coding standards, and team conventions.

Cross-Product Workspace Experience

The same workspace works identically across all Lovelace products:

CLI uses workspaces to organize local development. Commands run in the context of the current workspace, and AI assistance understands which project you're working on.

Studio displays workspaces visually with project boards, agent management, and resource configuration. The visual workspace view shows the same structure the CLI uses.

Agents Cloud runs agents within workspace boundaries. When an agent executes in the cloud, it operates within its workspace's permissions and resource access.

Web App provides collaborative workspace management where teams coordinate work, manage permissions, and oversee cross-product activities.

Desktop synchronizes workspace state locally, enabling offline work that syncs when reconnected.

Workspace Registry

The workspace registry maintains the canonical state of all workspaces across the platform. When you create a workspace in the CLI, it appears immediately in Studio. When you update permissions in the web app, CLI commands respect those changes instantly.

This registry handles:

  • Workspace definitions including name, description, and organizational relationships
  • Access control specifying who can access the workspace and what they can do
  • Resource links connecting repositories, projects, and external services
  • Configuration storing workspace-specific settings and preferences
  • State synchronization ensuring consistency across all products

Changes propagate in real-time through event subscriptions. Applications maintain local caches for offline operation, syncing changes when connectivity returns.

Workspace Linking

Workspaces don't work in isolation—they connect to external tools and systems:

Repository Links: Connect GitHub, GitLab, or Bitbucket repositories to workspaces. Lovelace understands repository structure and can navigate code across linked repos.

Project Management: Link Linear projects, GitHub Projects, or Jira boards. Issues created in these systems appear in workspace context, and AI agents can reference them.

Documentation: Connect Notion databases, Confluence spaces, or Google Docs folders. Workspace knowledge bases automatically include content from linked documentation.

External Services: OAuth connections to Google Workspace, Figma, Slack, and other services are workspace-scoped. Different workspaces can connect to different external accounts.

Access Control and Permissions

Workspaces implement fine-grained access control:

Workspace Owners have full control including deletion, member management, and configuration changes.

Workspace Members can create projects, run agents, and access workspace resources based on assigned roles.

Workspace Guests have limited access to specific projects or resources within the workspace.

Agent Permissions are workspace-scoped. An agent granted file system access in one workspace doesn't automatically have it in others.

Resource Permissions control access to sensitive data like production credentials, customer information, or proprietary code.

Enterprise integrations support SSO, RBAC, and compliance requirements through workspace-level policies.

Workspace Lifecycle

Workspaces progress through a natural lifecycle:

  1. Creation - Define purpose, link repositories, configure initial settings
  2. Development - Add projects, create agents, build knowledge base
  3. Collaboration - Invite team members, set permissions, establish workflows
  4. Scaling - Add more projects, refine agent configurations, optimize resource usage
  5. Archival - When work completes, archive workspace preserving history but removing active resource allocation

Archived workspaces remain accessible for historical reference but don't consume active resources or appear in default workspace lists.

Related Concepts