Choosing a session container

Start from Projects

Use New session or Shift+T in the Projects list or Mosaic. With a session tile selected, the wizard opens for that session's repository and defaults to its container. With a group selected, choose a repository from that group, including repositories without sessions. An empty Mosaic offers the available projects. Escape returns to the same view and selection without creating a session. The shortcut can be changed in Settings → Hotkeys.

The browser and desktop show New session directly in the Projects toolbar. Opening an existing session remains a separate action.

Numeric selection in Projects

Press 1–9 to select positions 1–9 and 0 for position 10. With Mosaic tabs focused, numbers select views/groups in their current displayed order, including All and custom views. With session tiles focused inside a multi-session view, numbers select its sessions in displayed order. A view with zero or one visible session always selects groups, even when its sole tile has focus. Number keys only move focus; Enter attaches.

In the regular Projects tree, numbers select group rows unless a session in a multi-session group has focus; then they select sessions belonging to that group. Moving or filtering views changes the displayed order used by shortcuts. Missing positions do nothing; Ctrl/Cmd-modified digits and input inside a modal are not navigation shortcuts. The behavior is shared by TUI and browser.

The container-selection wizard is available in the operator workflow. Sharing is only for repositories owned by that same operator. Optional server-user mode enforces immutable ownership in controller and host execution: different users always have different containers, sidecars, HOME and backing storage, even within the same organization. Group membership is not a user isolation boundary. Shared external services require publication and separate grants. Server-user workflow.

The terminal and browser use the same launch wizard. After selecting the host and runtime template, the wizard offers existing managed containers when any suitable container exists on that host. An existing container for the selected repository is the default. Choose Separate container to create another container with its own Git worktree; the generated name does not overwrite main or another existing container. If no existing container is suitable, this step is skipped and a new container is created.

A running container for another repository in the same explicitly configured Project group and using the same runtime template is also offered when the selected repository's checkout is already present on that host as Project container · other repository. Repositories without a group and repositories in different groups are not sharing candidates. Disposable compute workspaces continue to use their explicitly selected workspace.

If the selected container becomes unavailable during setup, the wizard returns to container selection and preserves the chosen account and session settings. It does not silently launch in a different environment. A confirmed running container remains selectable when an older lifecycle record temporarily says failed; containers being started or stopped remain excluded.

Before a fresh Claude process starts, devctrl records trust for that exact managed checkout in the selected account's native .claude.json. Existing credentials and other project settings are preserved. Trust is not granted to the filesystem root or parent directories. Reattaching to a running session does not rewrite its trust or upgrade its CLI. See Claude's workspace trust documentation.

Sharing saves the duplicated runtime and Docker sidecar overhead. Each new coding session receives separate Git working files, index and branch, including when two sessions use the same repository in one container. Existing sessions keep their original paths. Container reuse remains a shared trust boundary: sessions can see the container filesystem, processes, ports, service network routes, Exchange files, and other repository checkouts. Separate containers are appropriate when independent environments are needed. Selecting a repository keeps its session rules, settings and issued credentials scoped to that repository; container reuse is not a grant to another project's integrations. Because service routes belong to the container, agents in shared repository sessions cannot implicitly grant or revoke the owning repository's services. Operators configure shared-container service routes explicitly. Secrets require an explicit grant on the actual chosen container; selecting a shared container never imports secret grants from another container. A selected repository's secret environment reference remains unavailable until that actual-container grant exists.

For a different repository, devctrl first prepares a repository base inside the selected container's persistent session storage. It then creates the new session's checkout from that base. The shared container is not restarted to attach the repository. A new checkout copies the source commit, tracked changes and nonignored untracked inputs; generated ignored directories are not copied. Project instructions and private environment files are delivered separately from durable configuration. A continuation starts from its parent's checkout without changing the parent. See per-session Git checkouts for compatibility, resume and cleanup details.

Session Settings groups shared-container sessions under their actual repository, preserving separate defaults and exact restart targets. Launch Profiles selects a new-session recipe before the ordinary container choice; its placement requirements do not change the shared container's limits. Context tool overrides apply to the whole physical container. Live tool notifications refresh each session's own guide without copying another repository's grants. Configuration, tooling.

Ending the only session retains this persistent container for reuse. Explicit container/Project deletion processes authorized manifests and removes its owned runtime and sidecars; pending sibling work defers removal. Retained data and volumes require a separate cleanup decision. Exit and deletion.

Creating a session without staying connected

After the controller accepts the creation request, it stores the session together with its launch operation. The execution host prepares the container and starts the agent independently of the terminal or browser connection. You can close the interface, disconnect, or let your computer sleep after the wizard reports Session saved. Reconnect through Projects to see progress or attach to the running session. A disconnected terminal does not cancel the saved launch.

For an existing account and the container's main repository, the wizard saves the request before waiting for a stopped container to start. The server performs container preparation before launching the agent. Account sign-in and preparation of an additional repository inside a shared container still happen before this saved request; complete those interactive setup steps first. An offline or failed execution host cannot finish launch until it recovers, and startup errors remain visible on the session.

If the connection breaks while the creation response is returning, Enter retries the same request with its original request ID and exact settings. It does not create another account, container, or session. Changing the selected settings deliberately starts a separate creation attempt. Esc closes the dialog without cancelling a request that may already have been accepted. Once the agent is running, its existing stop action remains available in Projects.

Projects navigation

The default Projects list has four selectable levels: group → repository → container → session. Right enters the next level; Left or Escape returns to its parent. Up/Down navigate peers at the current level, including containers with no sessions. Container rows are also clickable in the browser.

The number next to a group counts visible sessions, not repositories. Projects lists only repositories already added to devctrl, rather than every repository in a Git organization. Add another through Projects → Add project → Git account. Hiding inactive containers with i keeps repository rows available for launching new sessions, even when none of their containers are active.

Enter on a repository opens the launch wizard. Enter on a container opens it with that container selected by default. Enter on a session attaches to the session. On a container row, x starts or stops that exact container, c cancels its active build, and Shift+D reviews deletion of that container. Closing the launch dialog returns to the prior selection.

A shared container is listed under each repository it hosts, with the sessions for that repository. The owning repository still controls its physical container. Shift+U on a container row updates installed CLIs for future launches across that physical owner's runtimes; existing sessions keep their processes and versions. Shift+B prepares images separately. Starting, stopping or deleting a shared container likewise affects all its sessions. Shared-session handoffs and cleanup manifests use the container's existing Exchange mount and retain the selected repository in their metadata.

Repository history includes sessions from every container, including shared containers. Resuming an existing provider conversation attaches to its original container. Native cross-provider import and existing handoff continuation currently require selecting that history entry's original container; moving a transcript to another container is not part of container reuse.