Deployment Configuration and Interaction

This page defines the target configuration placement and interaction model for Deployment Control.

It makes the release-control model operable in the current Topoo Cloud information architecture. It is a target product model and interaction specification, not a claim that every control described here is already connected to a production backend.

Read it with Work Sessions and Local Runtime, Node Workbench and Editors, and Release Control.

Configuration hierarchy

Configuration and execution state belong to four placement levels:

Workspace
→ authorizes external accounts and developer tools
 
Project
→ organizes Nodes and owns Work Sessions, Agents, Environments, release policy, Production authority, and audit
 
Node
→ owns Source, build contracts, Context, Checks, Resource Bindings, versions, and delivery history
 
Work Session
→ represents one temporary Project task and links to one or more authorized Nodes and Base Revisions

Project Deployments presents the operational flow produced by those configurations:

Submission
→ Release Candidate
→ immutable Release Artifact Set
→ Preview
→ Production

Topoo does not create the conversation interface used by Codex, Claude, VS Code, or another external execution client. It maps that external Session to a Project-scoped Topoo Work Session, Agent identity, one or more Node scopes, Base Revisions, and an isolated Session Workspace.

Interaction principle

Deployment Control is configured once and then used ambiently.

The user should not operate a Git collaboration checklist for every Agent task. Topoo persists the durable configuration and performs routine version operations in the background:

One-time configuration
→ connect GitHub, Topoo Local Runtime, and external execution clients
→ define Project, Nodes, Agent identities, Checks, and release policy
 
Daily use
→ open a new external Session
→ state the task
→ Topoo resolves Project and Node scopes
→ Topoo Local Runtime isolates working state
→ Topoo records Checkpoints, Commits, Change Summary, and Submission
→ clean integration and Preview proceed automatically
→ only exceptions require attention

The default policy should not ask the user to confirm routine Branch creation, Checkpoints, Commits, Commit summaries, Submissions, required Checks, clean integration, or Preview creation.

The platform interrupts the user only when configured authority, deterministic integration, required validation, destructive changes, or Production policy requires a real decision.

Configuration placement

Account connection, Project permission, Session authority, and Production approval remain separate grants.

Existing Project navigation

The current Project detail navigation may remain:

Overview
Code
Environment
Resources
Deployments
Observability
Settings

The Deployment module itself should expose its operational objects directly:

Projects
Work Sessions
Nodes
Integration
Previews
Releases
Environments
Policies and Audit

These do not all need to become new tabs inside every Project detail page.

• Files are the content of the Code surface.
• Work Sessions are Project-scoped operational objects and also appear as filtered Node activity and audit evidence.
• Agents are durable Project configuration assigned to Nodes.
• Submissions are operational release inputs presented inside Project Deployments.

Code surface

Code presents Node-to-Source mapping and Source browsing.

The first selector is a Node selector, not a repository selector:

Node: Cloud Console
Source: topooai/topoo-cloud / main / apps/cloud-web
GitHub: Connected

Changing the Node changes the repository, branch, root directory, and visible Source scope. This supports several Nodes that share one repository while preserving distinct responsibility and delivery boundaries.

The Code surface may open or inspect a Session Workspace, but it does not own Session policy, integration, approval, or Production.

Project Settings

Project Settings uses internal navigation instead of one long undifferentiated form:

General
Structure
Connections
Agents
Release Control
Access
Danger Zone

General

General contains stable Project identity:

• name
• slug and Project ID
• description and kind
• entry route

Structure

Structure presents the Project's Nodes, responsibility boundaries, current accepted Node Versions, and declared dependencies.

It answers:

• Which Nodes form this Project?
• What durable problem does each Node own?
• Which Node Versions are currently accepted?
• Which Nodes must be checked or released together?

A Node row opens its Node Workbench. A repository is shown as a Source Binding, not as the structural parent of the Node.

Connections

Connections shows which Workspace-authorized external systems the Project may use:

• GitHub or another Source provider
• Codex
• Claude
• VS Code
• later execution clients

Workspace authorization is performed once. Project configuration grants or denies use of that connection within the Project.

Agents

Agents stores reusable Project identities such as:

• UI Agent
• Backend Agent
• Documentation Agent

An Agent profile contains:

• name and responsibility
• prompt and operating procedure
• allowed Nodes, paths, and Resources
• allowed tools and actions
• required Checks
• Checkpoint, Submission, and Preview permission

One Agent identity may be reused by several external Sessions. For example, several Codex Sessions may divide sidebar, top navigation, and component tasks while operating under the same UI Agent identity. Each writing Session still receives its own isolated Session Workspace.

Agent configuration does not carry Production authority by default.

Release Control

Release Control configures the fixed Topoo Release Controller:

Topoo Release Controller
Managed by Topoo
Locked

The Release Controller is not a free-acting Agent with a mutable personality. It is a deterministic program, state machine, authority model, and SOP.

The surface configures:

• dependency and integration order
• stale-base handling
• file and Resource conflict handling
• required integrated Checks
• Preview policy
• Production approval policy
• same-Artifact promotion enforcement
• retention and rollback policy

Access

Access explains and configures separate authority layers:

Node Workbench

The common Workbench shell surrounds the capability-specific editor.

Node identity · accepted version · Base Revision
Source Explorer | Editor | Context / Changes / Checks / Activity / Versions
Preview · Connect · Node Settings

Node Settings uses:

General
Source and Build
Agents and Context
Checks
Resources
Versions

The Workbench Inspector may show:

• Context: responsibility, dependencies, assigned Agents, allowed scope, and acceptance framing
• Changes: isolated working Diff and affected scope
• Checks: deterministic validation against the pinned state
• Activity: Project Work Sessions linked to this Node, Checkpoints, Submissions, and audit events
• Versions: immutable accepted Node Versions and consuming Project Releases

External client connection

The Node Workbench Connect action creates a scoped connection grant. It does not create a chat:

Connect external editor
 
Project       Topoo Cloud
Node scopes   Cloud Console; Domain System
Agent         UI Agent
Allowed       Read Context, allocate Workspace, save Checkpoints, run Checks, create Submissions
Production    Not allowed
Expires       24 hours
 
Open in Codex
Copy connection link
Advanced MCP configuration

After the execution-client adapter, account connection, and Topoo Local Runtime have been configured once, the user may begin in the execution client instead:

Open Codex
→ create a new Session
→ state the task
→ adapter resolves the Project and external Session identity
→ Topoo creates a Project-scoped Work Session
→ Topoo resolves one or more authorized Node scopes and Base Revisions
→ first write asks Local Runtime for an isolated Session Workspace
→ Agent process receives the scoped Context Pack, Session Grant, and exact cwd

If several Nodes are valid, Topoo may infer and expand the allowed scope under policy. It asks the user only when the task requires new authority or the intended boundary is ambiguous. It does not ask the user to repeat durable Project context.

Project Deployments

Deployments is one operational surface with three object views:

Submissions | Releases | Deployments

Submissions

Submissions shows work proposed by Agents, GitHub, or manual Source import.

Each record exposes:

• Agent and external Session identity
• Node and Base Revision
• Change Summary and reason
• changed files and affected Resources
• Checkpoint history
• Checks
• stale-base and conflict result
• review and acceptance history

Releases

Releases shows the one integrated Project Release Candidate:

Release Candidate #104
 
Cloud Console       v39
Deployment System   v12
Editor Platform     v21
Marketplace System  v7

It presents integrated Checks, the immutable Release Artifact Set, Preview, approval, and same-Artifact Production promotion.

Production approval belongs here, not in an Agent Session or Node Workbench.

Deployments

Deployments shows actual Environment and provider events:

• Release Artifact Set
• Preview or Production target
• provider and runtime identity
• traffic and health
• logs and operating evidence
• redeploy and rollback actions

Provider execution does not create a second release authority.

Environment and Resources

Environment owns:

• Preview and Production targets
• domains
• environment variables and secrets
• deployment protection
• traffic and rollout policy

Resources has two internal views:

Resources | Node Bindings

Project creates and owns the Resource. Node Binding grants a Node a named, reviewable relationship to that Resource. Node Workbench may display or request a binding change, but it does not silently create, delete, or replace Project Resources.

First-time setup

Workspace Settings
→ authorize GitHub
→ install and authorize the Topoo Cloud adapter for Codex
→ install and register Topoo Local Runtime
 
Project Settings / Structure
→ define Nodes and dependencies
 
Project Settings / Agents
→ define reusable Agent identities
 
Node Settings
→ configure Source, build, Context, Checks, and Resource Bindings
 
Project Settings / Release Control
→ configure integration, Preview, approval, promotion, and rollback

Daily interaction

Open Codex
→ create a new external Session
→ state the task
→ Topoo creates a Project-scoped Work Session
→ Topoo resolves Project, Agent, Node scopes, and Base Revisions
→ first write causes Local Runtime to create isolated working state
→ automatic Drafts and Checkpoints
→ automatic source Revision and Change Summary at meaningful boundaries
→ automatic Node-scoped Submissions
→ clean Release Controller integration
→ automatic Preview
→ Production follows the configured approval policy

Topoo preserves the Session identity, Agent identity, Base Revision, Checkpoints, Submission, Change Summary, Checks, approval, Deployment, and rollback evidence. It does not need to persist the full external conversation as the release contract.

GitHub remains visible as the source-history and portability provider. A normal Topoo user does not need to manually operate Branch, Commit, Pull Request, rebase, or merge steps unless they explicitly choose the provider-native workflow.

Implementation and acceptance boundary

The current production Project surface preserves the existing navigation and now presents real Submissions, Releases, and Deployments views. A ready Node Project Preview can create and deep-link to a persistent Project Submission.

This validates the information architecture and the first Preview-to-Submission segment. It does not validate the complete interaction model.

Unavailable integrations must remain labelled Not connected, Not configured, or planned. The UI must not simulate external Sessions, automatic integration, or Production authority as if those capabilities were already connected.

The remaining target controls become API contracts and are connected incrementally to real control-plane state.