Skip to content

feat(computer): compose apps onto a Windows computer - #540

Merged
earakely-scale merged 26 commits into
mainfrom
edgararakelyan/windows-apps-compose
Nov 8, 2026
Merged

earakely-scale merged 26 commits into
mainfrom
edgararakelyan/windows-apps-compose

Conversation

@earakely-scale

@earakely-scale earakely-scale commented Nov 8, 2026 •

Copy link
Copy Markdown
Collaborator

Part of FD-5329. Follows #538 (an app's server on Windows), now merged.

A Windows computer can now have apps composed onto it, the same way Linux and macOS computers do. Until now _composed_windows_disk refused any app.

What changes

Composing apps. Each app becomes a layer of its own in provision.ps1, under C:\agentenv\apps\<name>, following its [install.windows]:

  • its files and downloads (checked by sha256);
  • a venv on the pinned Python, with the protocol's [app] extra (this checkout's source, or the version pinned to this release);
  • its .agentenv folder;
  • its PowerShell run scripts, then its install steps, both run elevated;
  • its server and services, written for agentenv-session.

The server runs as venv\Scripts\python.exe -m agentenv_protocol.computer.serve_app <file>:<Class> with ENVIRONMENT_NAME set. Program names come from gate.programs, as on the other OSes. windows_disk.Part gains served and steps, and write() takes the session user.

C:\agentenv is now only writable by Administrators, as /opt/agentenv is root's. Until now C:\agentenv inherited from C:\ the right for every user to change what's under it. The session user, which is what an agent acts as, could therefore edit a driver's or an app's files. After installing every layer, provisioning:

  • removes the inherited permissions;
  • grants Administrators and SYSTEM full control, and Users read and run;
  • gives the session user write access to the services' logs only.

This changes every Windows disk's provision script, so a driver-only disk gets a new key and recomposes once.

An app's .agentenv folder is the session user's only. The server writes its loopback port and token to .agentenv\server.json. The folder is created with inheritance removed and only the session user, SYSTEM and Administrators granted, so server.json gets those permissions the moment it exists. This answers Greptile's token finding on #538, and matches Linux, where only the session user can reach the server's socket.

Gate 1 refuses session-scope install steps on Windows. Composing installs each layer over ssh as agentadmin, so a step meant to run as the session user can't run. Gate 1 refuses such an app with a reason, both when the app env is put against a Windows computer and when it's composed into one. A step limited to other OSes (os="linux") still passes.

Where the served class is quoted. _Layer.served now holds the raw <file>:<Class>. Each shell command quotes it where it's used: the Linux Dockerfile, the macOS provision script and supervisord/launchd programs. Windows uses it unquoted, as one argv entry. Linux and macOS produce the same text as before.

A Windows notes test app in the Windows test bundle. It has:

  • a download checked by sha256;
  • a .ps1 run script that records whether it ran elevated;
  • an elevated install step that writes the env's build setting;
  • its window matched by its title.

The bundle also gains a notes-desk env (notes on windows-11 with cua-driver) and a notes task: deploy, verify, run the session checks, reset, verify. windows_test.py runs it.

The session step runs #538's Windows session inside the computer and checks:

  • a launch's exit code;
  • a pause of an app and a child it started;
  • stopping a windowless app, an obliging window and a stubborn one;
  • killing the helper;
  • refusing a missing program.

These are the chaos checks that caught #538's three bugs, kept as a regression test.

It lives in the Windows bundle, not the app bundle, because a module fixture plans the app bundle whole. The first CI run composed a Windows env there on the runners, which have KVM: it fetched the 7 GB ISO and hit the 20-minute timeout. The Windows bundle is only run where its media is.

A compose retries a failed download. The provision script's Fetch now tries 30 times, 10 s apart, as the base's setup.ps1 does. During this work, GitHub's release downloads returned 504 for several minutes and failed a compose.

Tests

Unit (tst/unit/env/envs plus the protocol suite: 2112 passed on a Linux box; ruff clean):

  • an app's layer, line by line;
  • the driver's layer gets none of the app lines;
  • the C:\agentenv lockdown lines;
  • gate 1 refuses a session-scope step for an app put alone and for one composed into a Windows env.

E2E on a Linux box with KVM. Four rounds ran the same task from the app bundle, as it was then. A fifth ran on this PR's head from the Windows bundle (agent-env run tst/integration/computer/windows --task notes): notes-desk composed in 4 min 55 s, gate 3 passed, and before: 1, after: 1 (85 s), with the chaos below repeated. The fourth round:

  • the notes desk composed in 4 min 29 s;
  • gate 3's full probe passed, including the app's data/get and exports through cua-driver;
  • the task passed before and after a reset (before: 1, after: 1).

Each round of the verifier saw:

  • the computer ready, with app notes ok;
  • .notes.json holding the deploy's settings, the secret resolved (-- Ada, t0ken, pro);
  • the window listed by the protocol's Windows session as pythonw.exe / TkTopLevel / Notes;
  • the Start Menu notes.lnk, and that the app launched;
  • run.txt reading elevated True in C:\agentenv\apps\notes, and installed.txt reading pro;
  • .agentenv and server.json limited to Administrators, SYSTEM and the session user;
  • the server returning 403 without its token and 200 with it.

pytest tst/integration/computer/windows_test.py -k notes passed on the box in 177 s, with before: 1, session: 1, after: 1.

Chaos on the deployed desk:

  • Session plumbing, run inside the computer:
    • a launch's exit code is the app's;
    • a pause holds both the app and a child it started (their files stop growing) and resumes them;
    • a windowless app is ended at once;
    • an app whose window closes when asked stops in 0.2 s;
    • one whose window won't close is ended at the 4 s timeout, with nothing of it left running;
    • killing the helper ends its app;
    • a missing program is refused with the reason.
  • App window killed: readiness reports no window with title 'Notes', and launching from the Start Menu shortcut brings it back ready.
  • App window hung (suspended) during data/reset: the reset waits out the 10 s stop timeout, ends the job and relaunches the app (new pid), and the computer is ready again.
  • data/add then data/get: returns the note.
  • Permissions: C:\agentenv\apps\notes is now Administrators and SYSTEM full control, Users read and run.

The first rounds caught three bugs in #538's Windows session, fixed there:

  • the helper ran on a venv launcher, so its pid didn't name its job;
  • stop didn't wait for a job it ended by force;
  • alive was true for an emptied job.

On modal_vm: the same task (from the app bundle, as it was then) with --sandbox modal_vm. The composed disk deployed on Modal in 130 s, the reset took 57 s, and it passed before: 1, after: 1 (194 s). Its sandbox was torn down.

Agent trial: the Windows bundle's Notepad task, with C:\agentenv locked. Its cua-driver desktop recomposed in 3 min 45 s, gate 3 passed, and an agent (Sonnet 5.5) saved the line in Notepad through cua-driver's tools: passed (check: 1), 73.9 s.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The changes since the last review appear safe to merge.

Summary

The PR lets Windows computers compose apps alongside their driver.

  • Windows computer environments can install each app as its own layer beside the driver.
  • Windows agentenv files are now protected from session-user edits.
  • Windows apps cannot ask installers to run as the session user.
  • Windows provisioning retries temporary download failures.
  • App class names stay one argument in shell commands.

The changes since the last review preserve app paths and permission commands while sharing helpers. No new actionable issues were found. No previous review threads were supplied, and no tests were run during this review.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Windows base] --> B[Install driver]
  B --> C[Install each app]
  C --> D[Create app venv and private folder]
  D --> E[Run installation scripts and steps]
  E --> F[Write server and service commands]
  F --> G[Restrict installed file access]
  G --> H[Pack disk and probe]
Loading

Reviews (12) · Last reviewed commit: "refactor(computer): a Windows app's fold..." · Reviewed by Greptile

earakely-scale and others added 14 commits November 7, 2026 23:06
…app servers on loopback

- session.py picks the OS's way: _session_posix (Linux, macOS, as before) or _session_windows, sharing _reaping.
- On Windows an app launches through _job, a standard-library helper that holds a Job object named for its pid: the
  app and all it starts are in it, it outlives the server, and a server finds it by name to stop it (its windows
  asked to close, then the job ended) or pause it (each process suspended). Windows are listed with EnumWindows, by
  program, class and title; the menu launcher is a Start Menu shortcut.
- served.py: an app's server answers on its folder's Unix socket, or on Windows on a loopback port it writes with a
  token, which it checks on every request and WebSocket; the driver's apps and svc, the launcher and the page driver
  reach it either way, through no proxy the environment names.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… reading its pipes to their end

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nstall under windows

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… name the window buffers' sizes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…posed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…app's

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, whose pid names its job

A venv's python.exe on Windows is a launcher that runs the interpreter as a child, so the pid a launch held wasn't the
helper's, and pausing, stopping and finding the job found none.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…', as /opt/agentenv is root's

C:\agentenv inherited the access C:\ gives every user to change what's under it, so the session user could change a
driver's or an app's files. Composing now leaves it the admins': every user reads and runs it, and the session user
writes only the services' logs and each app's own folder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s no process

Ending a job returns before its processes have, and a reset puts the app's files back once its stop returns, which a
process still holding one open would refuse. The session's windows are listed off the event loop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…not while the job is there

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale requested a review from a team as a code owner November 8, 2026 08:35
earakely-scale and others added 5 commits November 8, 2026 01:20
A fixture plans the app bundle whole, so a Windows env there composed Windows, ISO and all, wherever KVM was; the
Windows bundle is run only where its media is.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… a server's error

A 504 from GitHub failed a compose that a retry a few seconds later passes; the base's setup already retries its
downloads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…'s setup does

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tops apps on a real Windows computer

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… one module, and key the apps folder by OS

On Windows an app's server is reached on the address it wrote, and one that hasn't written it isn't answering, which
every caller handles; it used to fall back to a Unix socket, which Windows has none of, so a readiness check raised
instead of saying the server hadn't started or why it failed. Served opens an app's WebSocket too, so svc no longer
knows either transport, and app.py keeps the paths, so an app's own code still imports no websockets. apps_folder(os)
says where a computer of each OS keeps its apps, which composing uses for the computer it composes rather than the OS
it runs on. _Win32 names its DLLs, and kernel32's calls are typed in one place.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
earakely-scale and others added 4 commits November 8, 2026 05:21
…/windows-apps-compose

# Conflicts:
#	src/agent_env/env/envs/computer/utils/composer.py
#	src/agent_env/env/envs/computer/utils/windows_disk.py
…o have exited

Its job's list of processes says only that one is no longer in the job; its own handle says it has exited, so none
still writes once a stop returns and a reset puts the app's files back. Once in about 27 windowless stops on a real
Windows computer, a file still grew after the stop returned.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e and reports them

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Base automatically changed from edgararakelyan/windows-app-runtime to main November 8, 2026 16:22
earakely-scale and others added 3 commits November 8, 2026 08:22
…s-apps-compose

# Conflicts:
#	src/agent_env/env/envs/computer/utils/composer.py
#	src/agent_env/env/envs/computer/utils/windows_disk.py
… error

Retrying 30 times, 10 s apart, made a wrong URL take five minutes to fail; a 4xx but a timeout or rate limit now fails
the first time, while a server's error, a timeout and a refused connection are still tried again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… granted by named accounts

The Windows compose takes an app's folder from its staged layer, as _stage_app already puts it under apps_folder; the
well-known SIDs are named and one helper writes a folder's access alone; write() takes its user, build settings and
image by name. A test reads what a provision line writes with one helper, and the scripts the Windows bundle's
verifiers run inside the computer are checked to be Python, which no linter sees in a string.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit 92eb1eb into main Nov 8, 2026
34 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/windows-apps-compose branch November 8, 2026 18:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant