Shared repositories for server users
A repository owner, usually the server administrator, can let other server users start their own sessions in selected repositories. A user does not import, clone or synchronize the repository: the execution host keeps one canonical checkout per repository, and every session receives its own independent clone and branch.
This is a separate capability from shared sessions. Shared sessions grant view or control of somebody else's running session. A repository-use grant lets a user start their own sessions. The two grants never imply each other.
Model
The feature reuses existing pieces instead of introducing a parallel project namespace.
| Concern | Reused piece |
|---|---|
| Recipients | Server users and server groups (server-team), with dynamic group membership |
| Scope | Project-sharing scopes: one repository, an owned project group, or an exact set |
| Ownership of user runtime | Ordinary user-owned Project, workspace and sessions (server_entity_owners) |
| Per-session checkout | Existing isolated session checkout (devctrl/sessions/<leaf> branch, own clone) |
| User Git access | Existing user Git connections bound to an owned Project |
| Owner Git access | Existing encrypted Git connection bound to the owner's source Project |
| Project configuration | Existing durable Project configuration store on the execution host |
| Session launch | Existing POST /v1/sessions path and its authorization |
Repository-use grant
A grant record has a UUID id, an owner, exactly one recipient (recipientUserId
or recipientGroupId) and a project-sharing scope. Scope resolution is the same
as for project sharing: group scopes are dynamic, exact sets are fixed, Control
Room projects are never included, and only repositories the owner still owns
are effective. A grant reached through a group is effective only while the
recipient belongs to that group. Disabled owners or recipients have no effective
grants. Creating the same UUID twice is idempotent. An owner can have at most
256 active repository-use grants.
Grants are stored in the controller database (repository_use_grants). They do
not create session shares, approvals, compute administration or access to the
owner's accounts.
Per-repository sharing policy
The owner chooses, per source repository:
- Git access —
owner(default): the owner's Git connection is used by the host and never enters a user container; oruser: each user's own Git connection (for example aghlogin imported through Git Accounts). - Configuration —
shared(default): every user's sessions receive the owner's durable Project configuration (devctrl.md,.agent.env,.agents.envand declared local files); orper-user: each user keeps an independent configuration store for their own copy. - Session limit — maximum concurrent starting or running sessions per user in this repository (1–32, default 4).
- On revoke —
keep-running(default) orstop-sessions.
The policy is stored per source Project with an optimistic revision.
User copy ("seat")
On a user's first start, the controller creates an ordinary Project owned by the
user, with the deterministic ID shared-<sha256(user, sourceProject)[0..24]>
and a sharedRepository marker (sourceProjectId, ownerUserId, grantId,
gitAccess, configuration). It has the source repository's credential-free
HTTPS remote and display name. Its single workspace, named shared, is owned by
the user and runs in the user's own container. Different users therefore never
share a container, account home, checkout or writable cache, preserving the
existing invariant that users always run in different containers.
The seat is not an import: no remote clone is performed for the user. The marker is server-controlled; clients cannot set it.
Canonical checkout
Each execution host keeps one canonical checkout per source Project:
<DEVCTL_DATA_DIR>/shared-repositories/<sha256(sourceProjectId)[0..24]>/checkout
- It belongs to the host-agent service user (directories
0700), is never mounted into a container and is never edited by a session. - The host refreshes it before a seat workspace or a new seat session is
prepared, at most once per minute:
fetchof branches and tags from the credential-free remote, then a detached, clean checkout of the default branch. - Fetch credentials come from the source Project's bound Git connection. The controller delivers the token only to that execution host, only for a seat with a currently effective grant, and the host writes it to an ephemeral private directory under the canonical root that is removed after the Git operation. A public repository can be shared without a Git connection.
The seat workspace's primary checkout is a local copy of the canonical checkout
(clone --no-local --no-hardlinks), with origin reset to the credential-free
remote. No user process can modify canonical objects through hard links.
Per-session clone and branch
A new seat session uses the canonical checkout as its isolated-checkout source.
The existing preparation creates an independent clone in the user's persistent
sessions storage, on the branch devctrl/sessions/<leaf>, where leaf is the
opaque per-session checkout leaf. The source has no uncommitted context, so every
session starts at the current remote default branch. Continuations still use
their parent checkout as source, as before.
Credentials
user: the seat is bound to the user's own Git connection chosen at launch. It is delivered exactly as any user session credential. The owner's token is not involved.owner: the session container has no Git credential. To publish work, the user requests a brokered push (POST /v1/shared-repositories/sessions/:id/push). The controller rechecks the session owner, the seat, the effective grant and the policy, then queuesshared-repository.pushto the session's host. The host reads the session branch through a trusted Git metadata view, copies its objects into a private scratch repository and pushesrefs/heads/devctrl/sessions/<leaf>to the same branch name on the remote. The refspec is fixed and never forced, so the owner's token cannot be used to overwrite another branch. The token is fetched just in time and deleted with the scratch repository.
A user can never read the owner's token: it is not part of any API response to users, any snapshot, queued command payload, container mount or environment.
Configuration
shared: the host materializes the owner's stored configuration for the source Project into every seat checkout with a materialize-only operation. Edits inside a user's checkout are never captured back into the owner's store.per-user: the seat has its own durable store in the user's namespace, captured and restored like any ordinary user Project.
Revocation
A grant ends when it is revoked, when the recipient leaves the granting group, when the owner or recipient is disabled or offboarded, or when the repository leaves the scope. From that moment the controller refuses, for that user and repository: new sessions, seat workspace creation and start, owner-credential delivery and brokered pushes. These checks run on each request, so membership changes take effect without a separate reconciliation.
Running sessions follow the policy. With keep-running, they continue with the
material they already have; brokered pushes are refused. With stop-sessions,
an explicit grant revocation requests a stop of the affected running sessions
through the ordinary session stop command. A membership change or a disabled
account denies new work immediately but does not stop running sessions; the
owner can revoke the grant to apply the stop policy. Seats, workspaces and
session checkouts are retained, because they contain the user's work. The user
may delete them; deletion is never automatic.
Quotas
- Per user and repository: the policy's concurrent session limit, enforced at the session-launch perimeter.
- Per owner: 256 active repository-use grants.
- The existing aggregate per-user host allocation (CPU, RAM, PIDs, disk) still applies to the user's seat containers. Seat checkouts and session clones count as the user's retained disk. The canonical checkout is host infrastructure storage, counted once per host and repository.
Using it
Open Shared sessions / Shift+S, then Shared repositories / u, in the TUI or the browser console.
- An owner chooses Grant repository use, a recipient user or group and a
scope, and saves with
s. Policy on an owned repository changes Git access, configuration, the session limit and revocation behavior. - A recipient sees Available to you, selects a repository, chooses an agent
and account (and their own Git account for
userGit access), and starts a session withEnter. A brokered push is available on that screen for running sessions inownermode.
API
All routes are handler-scoped for server users; the handler derives the authenticated owner or recipient.
GET /v1/shared-repositories: owned choices, grants, policies, and the repositories available to the caller with seat and session counts.POST /v1/shared-repositories/grants:{ id, recipientUserId | recipientGroupId, scope }.DELETE /v1/shared-repositories/grants/:id:{ revision }.PUT /v1/shared-repositories/:projectId/policy:{ revision, gitAccess, configuration, sessionLimit, onRevoke }.POST /v1/shared-repositories/:projectId/sessions:{ clientRequestId, kind, accountId, gitAccountId?, hostId?, name? }. Creates or reuses the seat and its workspace, then calls the ordinary session creation withstartWorkspace: true.POST /v1/shared-repositories/sessions/:sessionId/push: brokered push of the session branch (ownerGit access only).GET /v1/agents/:id/shared-repositories/:workspaceId/credential: host-only delivery of the owner's fetch/push credential for an effective seat.
Limits
- The canonical checkout is per execution host. A second host keeps its own.
- Owner Git access requires the source Project's bound Git connection; without it, only public repositories can be fetched and brokered pushes are refused.
- Brokered push publishes only the session branch name. Opening a pull request is a separate step in the provider UI or with the user's own credentials.
- Submodules are not initialized, as for ordinary session checkouts.
- Container root inside a user's seat cannot reach the canonical checkout, but the owner and host administrator remain trusted infrastructure operators.