Server controller and application users
See features for supported capabilities and architecture for the implementation map. All clients use the same React screens, and the controller checks each user's role. The browser bundle and local clients do not manage identities or authorize resource access independently.
The existing standalone controller/web gateway can run on a server. The browser connects to that gateway; a TUI connects to the controller API using its connection profile and bearer token. Personal TUI clients connect over HTTPS; the separate operator shortcut uses SSH. Neither depends on a laptop remaining awake. Execution hosts still run host-agent. No second controller or client-side user registry is introduced.
This implementation does not move the current installation. Existing local
single-operator mode remains unchanged. Enable users on a standalone server with
DEVCTL_CONTROLLER_PROFILE=server and DEVCTL_SERVER_USERS_ENABLED=1. The standalone
Compose file accepts the latter variable (default 0). /v1/server/status reports
the actual profile and userWorkloadApi: "scoped".
First invitation and subsequent sign-in
- In Server Users, enter the display name and role, then save. The controller
generates the immutable user ID; it is shown read-only in the user's details.
Assign execution hosts and set resource budgets. API clients can omit
idinPOST /v1/server/users; explicit IDs remain accepted for existing integrations. - Issue a one-use invitation, valid for ten minutes. Send the user's own invitation, never the operator's link or controller transport token.
- The user opens it in web/app or enters it at the TUI invitation prompt, then sets a password (at least 15 characters). User IDs are case-sensitive.
- Subsequent sign-ins use the server address, user ID and password. Each client has a separate login; invitations do not need to be issued every twelve hours.
- Console → Account sign-in changes the password and lists remembered devices. Users can revoke another device without administrator involvement. At most twenty remembered devices may be active per user; sign out unused devices before adding more.
Personal TUI over HTTPS
devctrl tui connect https://console.example
# From an existing checkout:
./devctl tui connect https://console.example
The standalone launcher requires Python 3 and Node.js 24.22.1 LTS or a newer patched supported release. It downloads the existing bundled React TUI from the explicitly selected HTTPS server and runs it locally. No SSH account, Docker access, repository checkout, host-agent or local controller is required. To obtain just the launcher on a user's computer:
curl -fsSL https://raw.githubusercontent.com/devctrldev/devctrl/main/docker/remote_launcher.py -o devctrl
python3 ./devctrl tui connect https://console.example
Enter the user ID and password, or leave the ID empty to redeem the first invitation.
Passwords/invitations are prompted without echo. Passwords are not saved. Device
credentials are stored in private files under the user's configuration directory,
separated by server origin. HTTP is accepted only for loopback development.
The native client uses the same owned APIs and terminal transport as web/app.
Use devctrl tui connect https://console.example --logout to revoke this TUI
device and remove its saved sign-in.
devctrl tui remote remains an operator-only SSH shortcut and is not a tenant login.
Identity and access
Both local and server deployments use this same controller identity model.
Local mode automatically selects the existing operator without invitations or
user sign-in; /v1/server/me and the normal state snapshot expose that identity.
The private transport credential remains automatic and public access stays
protected. Invitation mode enables additional users; it does not select another
controller implementation or rewrite existing session/storage identities.
Terminal and account-login WebSockets distinguish the permanent private operator credential from invitation-issued user sessions. Only real user tokens undergo periodic expiry/revocation checks; local and recovery-operator attachments stay open. A policy or transport close reports its reason in TUI/CLI rather than silently returning to Projects. Disconnecting never stops the provider process.
Server Users appears in the shared TUI/browser navigation only for a server controller. Administrators create users, assign execution hosts, configure budgets, publish service resources and issue one-use, ten-minute invitations. Invitations are displayed/copied temporarily; treat them as secrets. Redeeming one starts a 12-hour server bearer session. After the first invitation, the user sets their own password and can sign in independently. Remember this device stores a rotating, 30-day device credential; clients renew the 12-hour access session automatically, including after a gateway restart. The 30-day device deadline is absolute, not extended by refresh. After it expires, the user signs in with their password. Passwords use salted, asynchronous scrypt; access/device tokens are hashed in SQLite. Guessing and concurrent hashing are bounded. Password changes require the current password and revoke other sign-ins. Disable/logout revoke access and remembered-device credentials; the gateway rechecks identity and closes revoked streams without stopping agent processes. There is no OIDC or email password reset. An administrator can reset a regular user's password in Server Users and issue a fresh invitation. Recovery-operator reset requires the private recovery credential; a tenant administrator or operator invitation cannot perform it.
Server Users separates hosts, quota limits, current usage and workspace paths.
The administrator overview is GET /v1/server/users/overview; an ordinary user
reads only their own GET /v1/server/me/overview. Fresh owned Docker inventory
supplies CPU/RAM even when no aggregate user allocation exists. Workspace and
auxiliary physical containers are counted once; missing/stale samples remain
unavailable. A fresh incomplete sample displays its measured portion with an
explicit measured/total container count, rather than claiming a complete total.
Disk accounting still requires its real filesystem measurement,
and an unset quota is not presented as measured usage. Viewing a host never
assigns access or creates an allocation. The migrated Operator retains the host's
existing projects layout; new tenant workspaces use their isolated user root.
Existing paths are inspected and copied separately, without moving mounts.
The web launcher detects server-user mode and generates a fresh operator
invitation for its private link. The gateway maps its own origin-bound browser
credential to the authenticated server user. It never substitutes its administrator
credential for a failed user request. Do not share the operator link with tenants;
issue their own invitations instead. Users may also redeem through
POST /v1/server/auth/redeem and use the returned bearer with the controller API.
The migrated operator is the recovery identity. Existing projects/accounts/
workspaces/sessions keep their IDs and receive immutable operator ownership.
Other users have separately named storage, accounts and runtime containers.
Sharing/reusing a physical container across different users is rejected, including
sidecars and account HOME mounts. Changing a resource owner in place is forbidden.
A tenant administrator role permits user administration; it does not confer the
canonical operator's global legacy recovery access.
Normal user APIs are an explicit allowlist: owned project/workspace/account/session
creation, owned terminal attach and kill, Claude browser authorization, scoped
state/usage, own MCP approvals, folder bindings, published service grants and
resource-budget visibility. Ownership is checked at HTTP, native session MCP,
asynchronous command creation and host execution boundaries. Runtime source
configuration is disabled for tenant workspaces: a repository's .devcontainer
and .devctl.yaml cannot request host mounts, privileged Docker or global secrets.
User workspaces use the managed base template and independent credential-free
HTTPS checkouts. Nested Docker is disabled for these workspaces.
Scoped snapshots include runtime-template metadata and global Session Settings for inspection. Users can override defaults only for their own repository/provider and cannot edit the operator's global defaults. Launch-profile create/edit/delete validates the profile ID, repository, eligible account, Agent Packs and existing service grants; an inaccessible or revoked shared account cannot become a recipe's credential. Tracked profiles are copied before editing. Profile CPU/RAM fields guide host placement and do not impose new limits on an existing shared container. Session configuration.
Context tool defaults and container overrides are owner-scoped. Users can select RTK OSS, sgrep, ast-grep, Repomix and Graphify for their approved template or owned workspace; host-wide prepared-image management remains an operator action. Live installation preserves provider processes and never merges user environments. Context tools.
Administrators can also distribute a Claude/Codex subscription to selected users through Server Users → user → Share eligible account. Each user gets a private profile and authorization-only host copy; quota remains one shared pool. Revocation blocks new starts and cleans authorization only after providers exit, without killing working sessions. Shared accounts (source access required).
Private Git accounts are owner-scoped and encrypted in the existing Vault. Import GitHub/GitLab credentials in Git Accounts and select that account for the project. Private checkouts receive a runtime-only, read-only credential helper restricted to the exact HTTPS repository host. Tokens are not put in Git URLs, command arguments, images or workspace metadata. Stop/delete, user disable and disconnect clear runtime credential material; accounts are never imported into a shared operator HOME.
Exchange works in both clients through the execution host's existing file RPCs: owned targets, browser downloads/drag-and-drop and native file transfers. No laptop mirror or operator SSH credentials are required. Uploads are chunked, staged and committed without overwriting an existing file; downloads detect file changes. Repository ignore rules apply. See server Exchange.
Owners can also share an existing live session with named controller users as View only or Control. Both roles use one native terminal stream; an explicit input lease prevents simultaneous prompts. Revoking a role closes its viewer immediately. Ownership, credentials, budgets and private projects remain separate; the grant does not permit a guest to kill, resume or reconfigure the session. Projects → Shared sessions / Shift+S uses the same React editor in TUI and browser. See shared sessions.
New user workspaces store runtime homes, transcripts, injected files and temporary
files under users/usr-<owner-hash>/workspaces/<immutable-id>/runtime, alongside
their independent repository checkout. Existing operator and existing pre-layout
user mounts keep their physical paths; running mounts are never renamed. The host
reads lifecycle/continuation files from verified existing session mounts instead
of assuming the old global workspaces/<id> root.
Arbitrary runtime templates, operator CLI actions and global
infrastructure/provider configuration remain administrator workflows. A shared
service is published to a user first, then granted to an owned workspace. Paid
Decisions integration requires an explicitly published Decisions resource; user
sessions cannot silently consume an operator's global integration. Host services
remain administrator owned and are accounted outside tenant container budgets.
Administrators can provision an owned folder through
POST /v1/server/users/:id/folders; ordinary users cannot turn arbitrary server
paths into readable resources.
Aggregate resources
A budget is per user and execution host, across all that user's managed containers. CPU/RAM/PIDs/concurrent-workspace reservations are atomic and durable; two simultaneous launches cannot both spend the same remaining headroom. Default child limits are 2 GiB, one CPU and 256 PIDs. Stop/failure does not release a reservation until a fresh host inventory observes the container and sidecar stopped. Retained backing storage keeps its accounting record. Restart/readmission preserves ownership. Offline/stale hosts and missing enforcement proofs reject new starts. Lowering a budget preserves live workloads and blocks further admission when over limit; it does not silently kill sessions. A replacement currently requires stopping its old workspace first rather than pretending overlapping containers cost nothing.
Hard mode requires a real, distinct parent cgroup per user. The host verifies its
RAM/CPU/PIDs envelope and actual Docker process membership. Container limits alone
are not aggregate enforcement. Configure DEVCTL_SERVER_CGROUP_CONFIG with the
path to a private JSON file describing verified delegation. Both cgroupfs and
systemd placement have adapters; rootless mode additionally verifies subordinate
UID/GID mappings, the matching daemon socket, writable delegated controllers and
the appropriate systemd bus. Effective capacity includes ancestor limits and
infrastructure usage. A separate ten-second maintenance loop refreshes proofs even
while a workspace build is running; stale proofs fail closed.
Hard disk caps use verified XFS/ext4 project quotas on configured, disjoint owned storage roots, including private Docker writable layers/logs/volumes. The adapter checks kernel quota enforcement, project inheritance and actual quota usage. It never assigns the whole Docker storage pool to one user. Assigning previously unowned populated storage requires quiescence; subsequent checks use private inode provenance and kernel readback instead of rescanning every dependency tree. Workloads must be in a non-initial user namespace so they cannot change host project IDs. Rootless quota administration needs an explicitly provisioned, trusted host bridge; the installer does not grant that privilege automatically. Legacy ext4 symlink blocks use a conservative bound, shown as such in the UI. Exchange writes pause when a required hard disk proof is missing; read and partial-upload cleanup remain available.
The UI shows reservations separately from measured usage and labels unavailable or stale measurements. Zero disk budget means unmetered, not empty storage. Kernel quotas cap bytes actually consumed; reservations are admission commitments rather than preallocated filesystem space. Concurrency counts admitted workspaces, not sessions within a workspace. CPU limits are maxima, not dedicated cores. An administrator may explicitly choose admission-only accounting; it is never labelled as a kernel cap. Unsupported or unverifiable hard enforcement rejects starts.
Server Users also shows every user's host workspace directories, retained roots, CPU affinity and CPU/disk quotas together. Administrators can select a host-provisioned storage base for new workspaces and pin a user's containers to an effective delegated CPU set. Existing workspace directories remain fixed when the default changes. Affinity updates use verified cgroup-v2 placement without session restarts; sessions sharing a container inherit the same user boundary. This does not provide exclusive-core reservations. See storage and CPU affinity prerequisites.
The controller can run as an ordinary SSH account with private writable state and
unprivileged ports. The existing installer supports --rootless for a preconfigured
rootless Docker host, without sudo, package installation, daemon changes or privileged
DinD. Canonical execution data paths match inside/outside infrastructure containers.
Optional --rootless-capabilities supplies a private, explicitly reviewed capability
configuration and its required mounts. Docker-group access remains root-equivalent.
See standalone installation and
resource adapter prerequisites for actual delegation,
namespace, systemd bus and filesystem requirements. Basic rootless installation
does not claim aggregate hard-limit support until those probes succeed.
Safe controller transfer
The controller has a durable authority ID/epoch and an installation ID stored
outside SQLite (<database>.installation-id, or
DEVCTL_CONTROLLER_INSTANCE_FILE). Copying an active database into another
installation cannot create another writer. Every upgraded host advertises
controller-authority-v1, verifies host-bound signed observations and persists
accepted epochs. Commands carry their originating authority; stale commands or
WebSocket channels cannot acquire a destination's newer authority retroactively.
Existing providers stay alive while authority is fenced.
Transfer is a deliberate operator action; no transfer occurs on startup. Private
operator API endpoints under /v1/controller-authority provide plan, drain,
cancel-drain, fence, manifest, prepare-destination and activate. A user
invitation, including an administrator invitation, cannot activate a controller.
Drain rejects mutations while existing queued commands finish. Fence requires zero
pending/in-flight work and authority support on every enrolled host. The final
manifest is ready only after every host has durably acknowledged the fence;
unreachable hosts are blockers, never assumed acknowledged.
For an existing local console with enrolled execution hosts,
./devctl controller move --host SSH_ALIAS reports a transfer plan;
adding --apply runs the acknowledged handover and installs a local transport-only
SSH proxy. Project containers and provider sessions are retained. The remote
controller continues automation after the laptop disconnects.
See migration and recovery (source access required).
Inventory/snapshot preparation is also available as an offline tool:
node docker/prepare-controller-transfer.mjs \
--database /absolute/controller.db \
--master-key /absolute/master-key-v1 \
--signing-key /absolute/run-signing-key-v1.pem
Add --prepare --destination /absolute/new-private-directory for a consistent
SQLite snapshot, exact key copies and checksummed manifest. Directory/files use
0700/0600. It contains secrets: encrypt external backups and use a protected transfer
channel. After the source fence is acknowledged, take the final snapshot,
configure a distinct destination installation ID, and review the exact source ID,
fence epoch, transfer ID, destination ID and manifest digest before activation.
Preserve enrolled host IDs, credentials and workload paths; do not recreate live
containers simply to move the controller. Redirect host connections separately
only during an explicitly authorized live cutover.
Rollback uses the destination's latest state: drain/fence/acknowledge it, then transfer that snapshot back and activate a new epoch. Restarting the original stale source database cannot safely undo destination writes. The preparation command never stops services, changes hosts/URLs or activates a writer.
Validation and operational boundary
Unit/in-process integration tests exercise ownership, credentials, invite expiry, API/gateway denial, host authority replay, concurrent admission, aggregate caps, stop/restart accounting, cgroup filesystem verification, checkout failure recovery and transfer activation/rollback. They do not prove that a production host has correct delegation: that is checked by the opt-in host adapter before hard starts. No running installation or session is migrated by these source changes.