Workspaces

A workspace binds Polygent to one or more Git repositories and is the access and configuration boundary for a team's sessions, tickets, bots, and operational settings.

Creating a workspace

Workspace creation validates the first repository before anything is saved.

1. Open Workspaces and select Create Workspace.
2. Enter a name, the repository URL, an optional access token, and the default branch (defaults to main).
3. Select Create. Polygent checks that the repository is reachable with the supplied credential and that the branch exists; creation fails with the reason otherwise.
4. Open the workspace's Users tab and add the members who need access.

Workspace and repository names may contain only letters, numbers, dots, and dashes. Creating a workspace requires Create Workspaces. The creator is not added as a member automatically: administrators always have access, but a non-administrator creator must be added under Users to see the new workspace.

Repositories

A workspace contains one or more equal repositories; there is no primary repository.

Field	Purpose
Name	User-facing repository name.
Git Repository	Clone, fetch, and push URL.
Personal Access Token	Optional credential for private Git and pull-request operations; encrypted at rest.
Default Branch	Starting branch used when no override is selected.
Folder Name	Subfolder used inside session working copies. Defaults to the repository name; must be a single folder name, unique within the workspace (case-insensitive).

Every session checks out all workspace repositories. Branch selectors appear per repository wherever a session, ticket, automation, plan, or deployment needs a starting branch.

A repository's URL or folder name cannot be changed, and the repository cannot be deleted, while any session using it is still active (not Done, Canceled, or Error). The last repository in a workspace cannot be deleted.

Chat and Develop working copies

Working-copy behavior depends on session mode.

Chat sessions with the same branch selection share one persistent working copy; Chat sessions with different selections use separate copies. Develop sessions use isolated working copies. Changing a default branch affects new sessions only.

Workspace tabs

Each workspace is configured through these tabs.

Tab	Purpose
Tasks	Named scripts reused by hooks and sessions.
Users	Workspace membership.
Repositories	Git URLs, credentials, folders, and default branches.
Hooks	Tasks or scripts run at session lifecycle events.
Guidelines	Workspace instructions added to agent runs, per context.
Tickets	Ticket source and sync, lifecycle, approvals, merge mode, Plan stage, and queue pause.
Start Templates	Saved ticket-start configurations.
Budgets	Workspace monthly AI budget and default per-task budget. See AI Cost Budgets.
Capability Ceiling	Upper bound on the tools and integrations any session in the workspace can use.
Deploy Templates	Commands and variables for deployment slots. See Deployment Worker.
Environment Variables	Values injected into workspace sessions and tasks.

Editing workspace settings requires Edit Workspaces; managing members requires Manage Workspace Users. Existing sessions keep configuration captured when they started where applicable.

Guidelines

Guidelines add workspace-specific instructions to agent runs, with a separate text for each context.

Guideline	Applies to
Chat	Chat sessions.
Development	Develop sessions.
Plan	Ticket Plan generation, revisions, and AI-assisted plan edits.
Merge Conflicts	AI merge-conflict resolution.
Insights	Insight extraction.
Code Review	Automated code review.
Verification	Automated verification.

Keep guidelines short, stable, and relevant to all repositories in the workspace. Put task-specific requirements in the session, workflow, bot, or ticket instead. Guidelines steer behavior but are not an enforcement boundary; use the capability ceiling and tool allowlists for hard limits. Do not place credentials in guidelines.

Environment variables

Workspace variables supply configuration to the workspace's sessions, hooks, and tasks on every session host.

Field / option	Behavior
Name	Unique within the workspace; case-insensitive on Windows hosts.
Value	Injected into new processes.
Secret	Encrypted at rest, masked in the UI, and never returned to the browser after saving.
Bash	Expose the variable to agent shell commands (on by default).
WebFetch header	Allow the agent to reference the value in web-request headers (off by default).

• Import / Export accepts .env, appsettings.json, and YAML files. Imported variables are not marked secret; review and mark them after import.
• Reserved names are rejected on create, update, and import. They cover home and profile folders (such as HOME, USERPROFILE, APPDATA), agent tool configuration folders, model provider API keys and base URLs (such as ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENAI_BASE_URL, GEMINI_API_KEY, OPENROUTER_API_KEY), and TLS/CA trust controls (such as NODE_TLS_REJECT_UNAUTHORIZED, SSL_CERT_FILE). Configure model credentials under Models & Backends instead.
• Running processes do not receive edited values; start a new session or rerun the task.
• Treat values printed by scripts or agents as disclosed, even when the UI masks them.

After rotating a credential, update the variable, cancel sessions that may retain the old value, and verify the new credential with a controlled run.

Tasks

A task is a named script stored in the workspace and reused by hooks and sessions.

Field	Behavior
Name	Display name.
Category	Build, Test, Start, or Uncategorized.
Script Type	Bash, PowerShell, Cmd, Node.js, or Python.
Working Directory	Relative to the session working-copy root.
Script	Commands to run non-interactively under the host service account.

Test each task directly before attaching it to a hook.

Session hooks

Hooks run tasks or inline scripts at session lifecycle events — install dependencies when a session is created, run tests when the agent finishes. Configure them on the Hooks tab; the events, options, limits, and failure behavior are described in Session Hooks.

A failed blocking hook can prevent lifecycle progression. Open the session's Hook Logs, correct the command, credentials, working directory, or timeout, and retry the action.

Workspace users

Workspace membership decides where a non-administrator can work; role permissions decide what they can do there.

Add or remove members on the Users tab with Manage Workspace Users. Administrators have access to every workspace and cannot be removed from one. Removing a member blocks future workspace access; review their active sessions, assigned tickets, automations, and approval responsibilities first. See Permissions.

Ticket configuration

The Tickets tab holds the workspace-wide ticket lifecycle, approval, and delivery settings.

Setting	Behavior
Source	None, GitHub, or TFS / Azure DevOps. See Ticket Sync.
Pause Ticket Queue	Stops automatic ticket starts in this workspace. See queue pause controls.
Ticket Lifecycle	Off: QA First. On: Merge First. Applies to every ticket in the workspace.
No QA Approval	Skip the QA Approval stage for every ticket.
No Developer Approval	Skip the Developer Approval stage for every ticket.
Merge Mode	Pull Request (create a pull request) or Merge (merge directly into the starting branch).
Auto Accept Merge Conflict Resolution	Complete validated AI conflict resolutions without review. Off by default. See Merge Conflicts.
Plan Stage by Default	Run the Plan stage before implementation (Planner license required).
Skip Plan Approval	Advance a successfully generated Plan straight to Implementation (Planner license required).

Individual ticket starts and templates cannot override the lifecycle. Changing it applies to subsequent transitions for all workspace tickets. Ticket concurrency is set per session host on the Hosts page, and the Low Priority Execution Hour is a global setting.

Pull requests are created through the workspace's ticket source integration; with Source set to None, pull-request creation fails. Configure GitHub or Azure DevOps/TFS sync with a dedicated least-privilege token and test import and pull-request behavior with a non-critical item before enabling auto-start rules. See Tickets.

Start Ticket Templates

A Start Ticket Template stores a repeatable ticket-start configuration, used from the ticket start dialog, bulk start, completed plans, and auto-start rules.

A template holds: name, a starting branch per repository, Plan-stage override and Plan model, implementation model, auto-implementation workflow, session mode toggles, Manual Implementation, allowed tools, skills, MCP servers and Polygent MCP tools, and whether it is the workspace Default Template. Assignments and priority are set on the ticket, not the template. An explicit empty capability selection grants none; use the unrestricted control when all enabled capabilities are intended. Review templates after renaming workflows, changing repositories, or rotating integrations.

Capability ceiling

The capability ceiling is a hard upper bound on what any session in the workspace can use, regardless of who or what started it.

Set allowed Tools, MCP Servers, Polygent MCP Tools, and Skills on the Capability Ceiling tab (requires Edit Workspaces). The ceiling is intersected with every bot, template, automation, subagent, and system job allowlist, so it can only remove capabilities. It does not change user permissions.

Troubleshooting

These checks cover common workspace incidents.

Symptom	Check
Workspace creation fails	Verify URL, token validity and scope, network access from the API host, and default branch spelling.
Creator cannot see the workspace	Add the creator on the Users tab; only administrators have implicit access.
One session fails during setup	Polygent retries a transient network or Git lock failure once with a brief backoff. If setup still fails, correct the reported revision, network, credential, permission, or lock issue. Do not delete shared repository storage as a recovery step.
Repository cannot be edited or deleted	Complete or cancel active sessions that use it; the last repository cannot be deleted.
Wrong branch is used	Check that repository's default and the per-repository selection on the session or ticket.
Variable is rejected	The name is reserved; model credentials belong in Models & Backends.
Variable is missing in a session	Confirm its name, the Bash option, and whether the session started after the value was added.
Hook fails	Review task output, working directory, environment, timeout, and host permissions.
User cannot see the workspace	Confirm membership, enabled account status, and required role permissions.
Pull request creation fails	Confirm the workspace Source is GitHub or TFS / Azure DevOps and its token can create pull requests.