Session folders
Folder grants use the same controller ownership and policy model as services and server Exchange. A subscription grant does not grant a folder, and sharing a folder never authorizes cross-user container reuse. See the current feature boundaries and server users.
Folders are project resources. Add them under Folders in either TUI or web, then attach them to selected sessions. The launch wizard offers the same folders before starting a new session. Gateway changes take effect on the next operation without restarting sessions or containers. Shell mounts are an explicit creation-time choice for a dedicated container; they never restart an existing container silently.
The existing domain names are ProjectGroup for a product/project containing
repositories and Project for one repository. A folder belongs to a ProjectGroup.
Its base permission is r or rw. A repository restriction may narrow rw to r
or disable access. A session needs an explicit attachment, which can only narrow
that access further. Reducing a gateway base grant affects existing attachments on the next operation;
active native mounts require an explicit stop/recreation.
A repository cannot grant a resource from another project group. r blocks create,
write, truncate, mkdir, delete and rename at the gateway, not just in agent instructions.
Sources
Two real transports are implemented behind the runtime driver:
local: an absolute folder on a registered host, read by that host-agent. The host may be the operator machine or a remote execution server. The path must actually be visible to its host-agent; a Mac path is not interpreted on Hetzner.ssh: an absolute remote folder accessed through a configured SSH alias on a selected registered host. Uses OpenSSH withBatchMode=yes, strict known-host verification and a connection timeout. Both source and relay host require Python 3. SSH keys/configuration use the existing host credentials; metadata contains only the alias, never credentials or authenticated URLs.s3: a bucket and optional prefix, accessed from a registered source host through the optional@devctl/provider-s3package and the official AWS SDK. An explicit HTTPS endpoint and region support S3-compatible storage. Credentials refer to an existing encrypted managed secret; they are fetched only for an authorized operation and are not copied into the Project container, inventory or queued command.
An operator-host source remains dependent on that machine being online. Traffic flows source host-agent → authenticated controller connection → requesting session; it does not require a fake mount of a laptop folder on the execution server. The default host-agent container must have an explicitly provided mount of any operator directory you want it to serve. Adding a resource does not bypass container visibility or silently modify its mounts.
SFTP-only endpoints, SMB, NFS and WebDAV are not implemented by this feature.
An S3 folder is configured in Folders, alongside local and SSH sources; the
existing S3 HTTP service integration remains available independently. Managed-service
provider packages can contribute a folderDriver factory without changing the common
permission, health or accounting model. Removing an optional package preserves its
folder definitions and makes that transport unavailable.
Connect an S3 bucket
In Folders → Add folder, select s3 with the protocol selector. Choose the relay
host, enter the bucket and optional prefix, and select an existing managed credential
secret. Configure a region (us-east-1 by default), optional endpoint, and path-style
addressing when required by the storage provider. Set the project grant to r or rw,
then attach the folder to a session or narrow it for a repository.
The secret uses the existing encrypted secret API/UI and contains JSON:
{"accessKeyId":"YOUR_ACCESS_KEY","secretAccessKey":"YOUR_SECRET_KEY","sessionToken":"OPTIONAL_TEMPORARY_TOKEN"}
Omit sessionToken for long-lived credentials. The folder stores only the secret ID.
The same managed secret can be reused or rotated; credentials are decrypted at execution
time. There is no ambient AWS profile fallback and the Project is not granted the keys.
Folder r rejects all mutating operations regardless of the underlying credential's
permissions. Use bucket/prefix-scoped infrastructure credentials as well when possible.
An operator API source example:
{
"id":"dataset",
"name":"Dataset",
"projectGroupId":"my-project",
"permission":"r",
"source":{
"protocol":"s3",
"hostId":"remote-server",
"bucket":"my-inputs",
"prefix":"project/dataset",
"region":"us-east-1",
"forcePathStyle":false,
"credentialSecretRef":"dataset-s3-credentials"
}
}
S3 folder access currently uses the MCP gateway, not a POSIX mount. Keys appear as
files, / prefixes as directories. Listing, stat and bounded range reads are supported.
Write replaces one complete object, up to 256 KiB, and counts its uploaded payload;
append, partial/chunk writes and atomic rename are rejected explicitly. For large
archives, retain the existing S3 integration or a signed upload workflow.
mkdir creates an empty directory marker. Remove deletes a single object or an empty
marker; it never recursively deletes a prefix. Directories report size zero rather than
inventing a recursive aggregate. Ambiguous keys containing . / .. segments,
consecutive slashes, backslashes or NUL are not exposed as filesystem paths.
The adapter uses official S3 listing/prefix semantics
and range reads.
Health performs a real scoped-prefix listing; it does not require whole-bucket
HeadBucket permission. Empty prefixes are healthy when authorized and reachable.
Listing is bounded at 10,000 immediate entries and supports the usual offset/limit.
S3 calls have a 15-second timeout, one SDK attempt, TLS verification enabled, and
provider errors are redacted. A network/result failure can leave the result of a
write/delete uncertain; inspect the object before retrying.
Hosts advertise session-folder-s3-v1 only when the optional adapter loads. An older
host receives no S3 command until its host-agent is updated; existing sessions do not
need to restart. Revocation/narrowing is checked before credentials are returned to
the exact source host. The encrypted secret is not exposed through MCP discovery.
S3 as a shell filesystem
For ordinary ls, cat and shell tools, a host administrator can first create an
actual S3 mount with rclone mount, then add
that mounted directory as a local folder source on the execution host. For example,
with an existing host-only rclone remote named datasets:
mkdir -p /srv/devctl-datasets/inputs
rclone mount datasets:my-inputs/project/dataset /srv/devctl-datasets/inputs \
--read-only --allow-other --vfs-cache-mode off
Run the mount under host service supervision; rclone mount remains a foreground
process. Credentials belong in a protected host-only rclone configuration, outside
all Project-visible mounts. --allow-other requires FUSE user_allow_other; configure
the mount's UID/GID and Unix modes for the intended session user. The selected
host-agent must see the mount at the same absolute daemon-host path before using
the existing dedicated-container shell mode. A host-agent bind established before
the FUSE mount may need explicitly configured host-to-container mount propagation.
Do not substitute a plain unmounted directory when the remote mount is unavailable.
devctrl does not install FUSE, provision this rclone mount, or change a running
host-agent/container's mounts automatically. A future managed shell adapter needs
an explicit host capability, persistent mount supervision/reconciliation, scoped
runtime credentials, mount propagation and cache/cleanup accounting. FUSE privileges
must remain in the host mount service; Project containers do not receive /dev/fuse,
SYS_ADMIN or privileged mode. Native I/O remains unknown in per-session statistics.
The existing native safety scan and its size/time budget still apply to a premounted
source. S3-compatible storage is not a full POSIX filesystem: locking, metadata,
writeback, renaming and caching behavior depend on the mount adapter.
Agent access and live attachment
Agents discover attached folders with list_session_folders and operate through
folder_operation. Arguments contain resourceId and an operation object:
{"resourceId":"inputs","operation":{"operation":"read","path":"example.txt","offset":0,"length":262144}}
Supported operations: list, stat, read, write (base64 payload), mkdir, remove
(nonrecursive), rename (regular file only, no replacement). Reads/writes are bounded
at 256 KiB per operation so requests and responses fit the managed MCP framing. Read large files with offsets; write the first chunk with default truncation, then subsequent chunks with offset and truncate:false. Directory listings support offset and limit (default 100, maximum 200).
Write truncates by default. Explicit offset and truncate:false permit bounded
chunk writes without buffering a large file in one MCP message. Directory enumeration
is bounded at 10,000 entries, and results are paginated.
There are two attachment modes:
- MCP gateway (default): live, permission-enforced operations on local, SSH or S3 sources. Safe file payload counters are available without container recreation.
- Shell mount: choose the mode button or press
min the launch folder picker. This creates a fresh dedicated worktree/container for the named session. The source must be a real directory local to the execution host. Files are visible at/run/devctl/folders/<resource-hash>; effective permissions are shown in the generated runtime document. Existing containers are never repurposed silently.
A shell container has a persisted owner/repository/session-name lease. It cannot accept a second session, retained sibling history, or another repository. Sources cannot overlap mutable checkout, Git or private runtime storage, or another writable bind alias. Mounts go only to the main container, never its Docker sidecar. Imported privilege/capability/Compose configuration is rejected before lifecycle hooks run; actual container privileges, bind flags and kernel mount namespace are checked too. Native source trees reject symlinks, hardlinks, sockets, devices and nested mounts, with a preflight budget of 100,000 entries / 15 seconds of traversal. Larger or unsupported trees should use gateway access.
Read-only shell mounts explicitly require recursive read-only support
(bind-recursive=readonly); unsupported Docker/kernel combinations fail instead of
quietly retaining writable submounts. Docker documents the requirement for
Linux 5.12 or later.
Writable mode disables recursive submounts. Source Unix ownership/ACLs are preserved;
devctrl does not chmod/chown an attached external dataset to manufacture write access.
The selected agent UID still needs normal Unix access to the directory.
When the host-agent itself runs in Docker, a native source must be explicitly exposed as a bind at the same absolute host path. An internal container directory is not accepted as a daemon-host folder. For SSH or an operator machine different from the execution host, shell mount mode is unavailable; real gateway transport remains available. S3 protocol sources also use the gateway; use a separately premounted local source for shell access as described above. There is no pretend live mount implemented by copying a stale snapshot. Network filesystems mounted beforehand on the execution host may be configured as local sources, but devctrl does not provision their mounts or credentials.
Changing a native grant while its container is active returns a stop/recreate requirement. Stop it explicitly first; the next start refreshes the lease and mounts against current narrowed grants. Revoked sources refuse to start until a new container is configured. Renaming a resource and idempotent bindings remain safe live operations. Gateway access can still be configured live for containers without native mounts.
Hosts advertise session-folder-gateway-v1 and session-folder-native-v1; controller
checks them before queuing new commands/plans. Older agents receive no incompatible
folder command and cannot silently drop native lease fields. Upgrade controller and
host-agent before using the feature; no provider session restart is required.
Native bind I/O has unknown per-session/folder bytes; its statistics are shown
separately from measured gateway traffic. Existing hostVolumes remain independent
and their direct traffic is unknown too. A shared same-user container is not a hostile
session credential boundary: gateway attribution trusts the authenticated MCP identity.
Use separate containers when filesystem or credential isolation between sessions is
required. Different server users always require separate compute/storage boundaries.
Gateway traversal uses descriptor-relative, no-follow operations. Symlink traversal,
hardlinked file reads/writes, special devices, FIFO/socket operations, absolute paths
and .. traversal are rejected. This conservative design does not support legitimate
symlinks either. SSH aliases must already have known-host entries; autoaccept is disabled.
Remote errors do not return raw SSH stderr or secret file content. Read payloads are
not persisted into controller result history; only counters and metadata are retained.
Health and statistics
Saving a resource and Check health perform a real stat through the selected transport. Source-host offline status is shown separately; a healthy probe is an observation at its timestamp, not a guarantee of continuous connectivity. File-not-found operations do not mark an otherwise reachable source unhealthy.
Counters use actual completed read/write syscall payload bytes, attributed by the authenticated session identity and aggregated by repository. Metadata/listing does not count as file content. Receipts are deduplicated by command ID. Failed operations can have partial I/O; their bytes are unknown, with an explicit unknown-operation count. Direct filesystem I/O, sync caches, transport overhead and unrelated processes are not included. Do not interpret gateway counters as total container filesystem traffic.
Commands are reauthorized against current grants immediately before execution. Revoked or narrowed grants reject pending operations. Commands expire after 20 seconds rather than running an old queued write indefinitely after reconnection. A started operation can finish after revocation; operations have a 15-second transport bound. A controller/host crash during a write can leave a partially written file; write uses truncate/write/fsync, not atomic replace. Operation-result loss can require checking file state before retrying writes, rename or delete. There is no cross-host distributed filesystem transaction guarantee.
API and server users
Operator API: GET/POST /v1/folders, DELETE /v1/folders/:id,
POST /v1/folders/bindings, POST /v1/folders/:id/check,
GET /v1/sessions/:id/folders. New-session POST accepts
folderAttachments: [{resourceId,permission}], persisted before a runnable session.
Workspace creation also accepts nativeFolders: {sessionName, attachments: [{resourceId,permission}]}
with preferredHostId; this is a plan for a fresh dedicated container, never a live
mount change. Health command completion appears in the normal command result/state API.
MCP tools can use existing attachments; they cannot grant themselves a new folder.
Use request_permission to ask the operator, then attach it in Folders.
Records are namespaced by controller-issued owner identity. Single-operator
controllers use operator; server-mode requests use their authenticated identity,
and MCP requests derive the session owner. No request body can choose an owner.
Source definitions require administrator provisioning in user mode: an arbitrary
host path is not proof of ownership. Bindings and discovery check target ownership.
Server-user middleware must enforce source-host/path grants before enabling broader
self-service source provisioning. Different
users must always use separate containers, sidecars, HOME and storage. Shared resources
require separate authorized grants; sharing a folder does not permit sharing compute.
This feature does not add an independent local user database; the server controller
is the only user authority. The shared-resource provisioning API and overall tenant
authorization belong to the server-controller implementation.
Shared containers require identical folder grants and MCP security policies for every retained session. A differing policy is rejected before it is saved; choose a separate container. Per-session tokens do not isolate processes sharing a UID. Native shell mounts always reserve a dedicated container, and their native I/O counters are explicitly unknown.