Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/workflows/local-backends.yml
Original file line number Diff line number Diff line change
Expand Up @@ -229,7 +229,8 @@ jobs:
if: always()
run: |
.venv/bin/python .github/scripts/check_skip_policy.py junit-integration-slow.xml \
--allow model_endpoint_configured remote_sandbox default_a2a_agent mcp_server_sources windows_media
--allow model_endpoint_configured remote_sandbox default_a2a_agent mcp_server_sources windows_media \
omarchy_image
# The tests' times, for .github/scripts/slow_test_durations.py to rebalance the shards with.
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
if: always()
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ and deserialized through a registry.
| `explorer/` | Optional local web UI: `agent-env up`, binds loopback `:8234`. |
| `cli/` | Click CLI with the groups `a2a-agent`, `artifact`, `bundle`, `config`, `env`, `eval`, `plugin`, `run`, `task`, `up`. `task run`, `task run-batch` and `eval run` hand their runs to the configured `[runner]` and follow them. |
| `agents/` | The `agents` bundle: the agents agent-env ships, one folder each under `agents/agents/`, with a smoke task each under `agents/tasks/`. Its Claude Code, `@local/agentenv-framework/agents/claude-code`, is the default agent. An agent's Python packages are its folder's `requirements.txt`, installed in its image, never in agent-env's own environment. A run that pulls one of its agents reads the whole bundle, so `tst/unit/bundle/shipped_bundles_test.py` parses and checks every shipped bundle. |
| `computers/` | The `computers` bundle: the base computers agent-env ships as `computer` artifacts, `ubuntu-24.04` (XFCE on Xvfb, supervisord as the session user, settings as `AGENTENV_SETTING_<NAME>`), aliased through `[artifacts]`. It has no tasks either. `disk/linux/` is the Linux disk form's recipe: `boot/`, whose Dockerfile makes a disk form (a GPT disk of an EFI system partition holding one UKI, Ubuntu's kernel with a busybox initramfs whose init reads a NoCloud seed and `switch_root`s into the image's entrypoint, and an ext4 root filesystem that is a container image's, plus `/etc/agentenv/vm/image.env` from its OCI config), `tools/`, the disk tools that make it unprivileged on the builder's own platform (`mkfs.ext4 -d`), and `launcher/`, the QEMU launcher that boots one under KVM. A base's `[forms.disk]` with no image is made from its container form; the composer makes each arch's disk from its composed container, keeping the base disk's EFI system partition, keyed by the container's key, the base disk and the recipe; gate 3 probes it where a provider boots disks natively (`disk_image_platforms()`), and a deploy's first boot with KVM probes one left `unverified`; a deploy naming `form = "disk"` boots it through `create_vm(image=..., env=...)`, its settings in the seed. |
| `computers/` | The `computers` bundle: the base computers agent-env ships as `computer` artifacts, `ubuntu-24.04` (XFCE on Xvfb, supervisord as the session user, settings as `AGENTENV_SETTING_<NAME>`), and `omarchy-4.5`, a disk alone built on the composing machine from Omarchy's own VM image (its `[forms.disk]` `source`) by `disk/omarchy/`'s recipe, its services systemd user units of the graphical session that start through `with-seed`, booted by the launcher as a `linux-desktop` guest (`env/envs/computer/utils/omarchy_disk.py`, on `thin_disk.py`, which Windows' disks use too), aliased through `[artifacts]`. It has no tasks either. `disk/linux/` is the Linux disk form's recipe: `boot/`, whose Dockerfile makes a disk form (a GPT disk of an EFI system partition holding one UKI, Ubuntu's kernel with a busybox initramfs whose init reads a NoCloud seed and `switch_root`s into the image's entrypoint, and an ext4 root filesystem that is a container image's, plus `/etc/agentenv/vm/image.env` from its OCI config), `tools/`, the disk tools that make it unprivileged on the builder's own platform (`mkfs.ext4 -d`), and `launcher/`, the QEMU launcher that boots one under KVM. A base's `[forms.disk]` with no image is made from its container form; the composer makes each arch's disk from its composed container, keeping the base disk's EFI system partition, keyed by the container's key, the base disk and the recipe; gate 3 probes it where a provider boots disks natively (`disk_image_platforms()`), and a deploy's first boot with KVM probes one left `unverified`; a deploy naming `form = "disk"` boots it through `create_vm(image=..., env=...)`, its settings in the seed. |
| `browsers/` | The `browsers` bundle: the website browsers agent-env ships, today `chromium`, a `computer_app` env (Chrome for Testing at the build Playwright pins, for amd64 and arm64, set up for unattended use by managed policies in `/etc/opt/chrome_for_testing/policies/managed`, opened at boot on its `start_urls`, its profile its data). All of it, its pin, install step, policies and command, is in `envs/chromium/chromium.py`; `tst/integration/computer/chromium_app_test.py` runs it. Like `drivers`, it has no tasks. |
| `drivers/` | The `drivers` bundle: the computer drivers agent-env ships as `computer_driver` envs, the reference driver (X11 on Linux, recording through `x11grab`) aliased `reference`, and trycua's cua-driver aliased `cua-driver` (its daemon from the pinned PyPI wheel, its own instructions, tools and skill resources served to agents through `@server_instructions`, `forwarded_tools` and `@resource`, its tools beside `computer_*`, `computer/v1` on its desktop-scope calls, its skill pack leading the computer skill; `tst/integration/computer/cua_driver_test.py` runs it). It has no tasks: a bundle with neither tasks nor evals is refused unless its `aliases.toml` names something for other bundles to use. The shipped `desktop` example composes it with the `ubuntu-24.04` base into a computer env, which `tst/integration/computer/` deploys, probes, records and has an agent use. |
| `examples/` | The example bundles agent-env ships (`hello`, and `echo-mcp`, which needs Docker, and `desktop`, a computer env of `ubuntu-24.04` and `reference` with a probe task and an agent task). Tests run them, but they are examples for users, not fixtures. Every shipped bundle is registered under `agent_env.bundles` in `pyproject.toml`, `<name> = "<package>"` shipping `src/<package as a path>/<name>/`. |
Expand Down
67 changes: 48 additions & 19 deletions src/agent_env/artifact/artifacts/computer.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@
model_validator,
)

from agentenv_protocol.computer.platform import entry_for, platform_key

from agent_env.artifact.artifact import Artifact
from agent_env.artifact.artifacts.docker_image import DockerImageArtifact
from agent_env.artifact.ref import ArtifactRef
Expand Down Expand Up @@ -89,11 +91,13 @@ class WindowsOS(BaseModel):

#: The OS types a computer is, by ``os.type``.
OS_TYPES: dict[str, type[BaseModel]] = {"linux": LinuxOS, "macos": MacOS, "windows": WindowsOS}
#: The forms each OS type's computers have: a Linux computer is a container and may be a disk too, a macOS one a VM
#: bundle alone, a Windows one a disk alone.
OS_FORMS = {"linux": ("container", "disk"), "macos": ("vm_bundle",), "windows": ("disk",)}
#: The init that starts a disk's programs on each OS type with a disk form.
DISK_INITS = {"linux": "supervisord", "windows": "agentenv-session"}
#: The forms each platform's computers have, by platform key, a distribution's replacing its OS type's: a Linux computer
#: is a container and may be a disk too, an Omarchy one a disk alone, as Hyprland needs a GPU a container doesn't get, a
#: macOS one a VM bundle alone, a Windows one a disk alone. The first is the one every computer of it has.
OS_FORMS = {"linux": ("container", "disk"), "linux/omarchy": ("disk",), "macos": ("vm_bundle",), "windows": ("disk",)}
#: The init that starts a disk's programs on each platform with a disk form, by platform key: on Linux the boot recipe's
#: supervisord, on Omarchy systemd's user units in its graphical session, on Windows agentenv-session.
DISK_INITS = {"linux": "supervisord", "linux/omarchy": "systemd", "windows": "agentenv-session"}


class Session(BaseModel):
Expand Down Expand Up @@ -136,17 +140,29 @@ class ContainerForm(BaseModel):
input_channel: Literal["env"]


class DiskSource(BaseModel):
"""The VM image a disk's base is built from: a distribution's own, fetched by ``url`` and checked by ``sha256``."""

model_config = ConfigDict(extra="forbid")

url: str = Field(pattern=r"^https://\S+$")
sha256: str = Field(pattern=r"^[0-9a-f]{64}$")


class DiskForm(BaseModel):
"""The computer as a disk a VM boots from UEFI, whose init reads deploy settings from a NoCloud seed
(``input_channel``): on Linux, an EFI system partition holding one UKI and its root filesystem, the image's own
``init`` started; on Windows, agentenv-session at the session user's sign-in. With no ``image``, it's made when
composed: the container form's root filesystem on agent-env's Linux boot recipe, or Windows installed from
Microsoft's media on this machine (``computers/disk/windows``)."""
``init`` started; on Omarchy, systemd's user units in its graphical session; on Windows, agentenv-session at the
session user's sign-in. With no ``image``, it's made when composed: from its ``source``, a distribution's own VM
image, on its recipe; else from the container form's root filesystem on agent-env's Linux boot recipe, or Windows
installed from Microsoft's media on this machine (``computers/disk/windows``). A disk that names no source is
written without one, so an agent-env from before sources still reads it."""

model_config = ConfigDict(extra="forbid")

image: ArtifactRef | None = None
init: Literal["supervisord", "agentenv-session"]
source: DiskSource | None = Field(default=None, exclude_if=lambda source: source is None)
init: Literal["supervisord", "systemd", "agentenv-session"]
input_channel: Literal["nocloud"]
firmware: list[Literal["efi"]] = Field(default=["efi"], min_length=1)
min_disk_gb: int = Field(ge=1, description="Its virtual size, which a deploy's disk is at least")
Expand Down Expand Up @@ -238,21 +254,32 @@ def _os_type_supported(cls, value: Any) -> Any:

@model_validator(mode="after")
def _forms_fit_os(self) -> Self:
allowed = OS_FORMS[self.os.type]
platform = platform_key(self.os.type, getattr(self.os, "distribution", None))
allowed, kind = entry_for(OS_FORMS, platform), platform if platform in OS_FORMS else self.os.type
if others := [form for form in FORMS if getattr(self.forms, form) is not None and form not in allowed]:
raise ValueError(f"forms.{others[0]}: a {self.os.type} computer's forms are {' and '.join(allowed)}")
raise ValueError(f"forms.{others[0]}: a {kind} computer's forms are {' and '.join(allowed)}")
if getattr(self.forms, allowed[0]) is None:
raise ValueError(f"forms.{allowed[0]} is required: every {self.os.type} computer has one")
raise ValueError(f"forms.{allowed[0]} is required: every {kind} computer has one")
if self.os.type == "macos" and self.arch != ["arm64"]:
raise ValueError(f"arch: a macOS VM bundle runs on Apple silicon, arm64 alone, not {self.arch}")
if self.os.type == "windows" and self.arch != ["amd64"]:
raise ValueError(f"arch: a Windows computer is amd64 alone, not {self.arch}")
if self.forms.disk is not None and self.forms.disk.init != DISK_INITS[self.os.type]:
raise ValueError(f"forms.disk.init: a {self.os.type} disk's init is {DISK_INITS[self.os.type]}, not "
f"{self.forms.disk.init}")
if self.os.type == "windows" and self.forms.disk.image is not None:
raise ValueError("forms.disk.image: a Windows disk is installed from Microsoft's media on the machine that "
"composes it, so it names no image")
disk = self.forms.disk
if disk is not None and disk.init != (init := entry_for(DISK_INITS, platform)):
raise ValueError(f"forms.disk.init: a {platform if platform in DISK_INITS else self.os.type} disk's init is "
f"{init}, not {disk.init}")
if disk is not None and disk.image is not None and disk.source is not None:
raise ValueError("forms.disk: a disk names an image or the source its base is built from, not both")
if platform == "linux/omarchy" and disk is not None and (disk.image is not None or disk.source is None):
raise ValueError("forms.disk: an Omarchy disk's base is built from Omarchy's own image on the machine that "
"composes it, so it names that image's source and no image")
if self.os.type == "windows" and (disk.image is not None or disk.source is not None):
raise ValueError("forms.disk: a Windows disk is installed from Microsoft's media on the machine that "
"composes it, so it names no image or source")
if (self.os.type == "linux" and disk is not None and self.forms.container is None and disk.image is None
and disk.source is None):
raise ValueError("forms.disk: with no container form to be made from, a Linux disk names its image or the "
"source its base is built from")
return self

@field_validator("forms", mode="before")
Expand Down Expand Up @@ -295,7 +322,9 @@ def put(cls, *, inspect: bool = True, **fields: Any) -> Self:
checks["vm_bundle"] = _unread(computer.arch, "a VM bundle is read by the host that boots it")
if disk is not None and disk.image is None:
checks["disk"] = _unread(computer.arch, "it's installed from Microsoft's media when composed"
if computer.os.type == "windows" else "it's made from the container form when composed")
if computer.os.type == "windows" else
"it's built from its source when composed, which checks its os-release"
if disk.source is not None else "it's made from the container form when composed")
elif disk is not None:
checks["disk"] = (_inspect(computer.disk_image(), computer.arch,
functools.partial(_read_disk, disk.min_disk_gb))
Expand Down
30 changes: 30 additions & 0 deletions src/agent_env/computers/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -191,5 +191,35 @@ Administrators reach; it launches the app in a Job object, which ends whatever t
`agentadmin`, so an app's install step for the session user can't run on Windows, and gate 1 refuses an app that
declares one there.

`artifacts/omarchy-4.5/` is Omarchy 4.5 (`amd64`), an Arch Linux desktop on Hyprland, as a disk alone: Hyprland needs a
GPU, which a container doesn't get. Its base is built from Omarchy's own stable VM image, which its `[forms.disk]` names
by `source`, a URL and a sha256, fetched once into this machine's cache and checked. It's booted once by the QEMU
launcher as a `linux-desktop` guest (a virtio GPU at the computer's resolution, 4 vCPUs and 8 GB), with root's ssh key
passed as a systemd credential, Omarchy signing its user `omarchy` in as it does at every boot, and made a base by
`disk/omarchy/recipe.sh`, run as root over ssh. The recipe refuses an image whose os-release isn't the artifact's
`omarchy` `4.5.0`; installs cua-driver's Hyprland plugin, pinned by URL and sha256 to the package Omarchy builds for its
Hyprland; adds `agentenv.lua` to Hyprland's config (the plugin loaded at start, a US keymap, the idle cursor hidden, the
display's mode); installs the seed unit; has SDDM log back in after a logout; sets Omarchy's toggles for an unattended
desktop (staying awake, no animations, no screensaver or suspend, notifications silenced); turns off crash toasts,
dictation and its keys, housekeeping timers that would run at boot, and the firewall, which lets in only ssh and
LocalSend while the launcher forwards only the computer's own ports; and locks `omarchy`'s password and leaves the
machine id empty. Trimmed, the image becomes the base's, with the key to root, and is pushed to the env's image store
under a tag of its recipe and source. Name it as `omarchy-4.5`, or by its id,
`@local/agentenv-framework/computers/omarchy-4.5`.

An Omarchy computer env is composed on the same machine as a thin disk too, with what's Omarchy's own in
`omarchy_disk.py`: each layer is installed over ssh as root by a bash script composing writes, as its
`[install."linux/omarchy"]` says (its files under `/opt/agentenv/drivers/<name>`, its downloads checked by sha256, its
venv on the system Python, its run scripts), and its services become systemd user units of the graphical session, which
start with the session, and again with it, through `with-seed`. The composed disk has no ssh: only a compose logs
in, and it boots the base. At every boot, before SDDM starts the session,
`agentenv-seed.service` reads the deploy's environment from the NoCloud seed with the Linux disk's own `seed-env` and
writes it for `with-seed`, root's and the session user's alone, the seed's trust files first; it sets the hostname and
the computer's `timezone` (UTC by default; a deploy is refused one that isn't an IANA zone, and one the disk doesn't
have is written as the refusal every service then names), names `host.docker.internal` at QEMU's address for the launcher, and writes the display's mode for Hyprland
from the computer's `resolution`. Gate 3 probes it at full. An Omarchy computer has no apps for now: gate 1 refuses one. When
Hyprland crashes, its watchdog brings it back in safe mode, without cua-driver's plugin, and cua-driver reports the
computer failed for good.

This bundle has no tasks of its own: other bundles pull its computers by alias, and `agent-env run computers` has
nothing to run.
1 change: 1 addition & 0 deletions src/agent_env/computers/aliases.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,4 @@
"ubuntu-24.04-headless" = ["ubuntu-24.04-headless"]
"macos-26" = ["macos-26"]
"windows-11" = ["windows-11"]
"omarchy-4.5" = ["omarchy-4.5"]
20 changes: 20 additions & 0 deletions src/agent_env/computers/artifacts/omarchy-4.5/artifact.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
type = "computer"
description = "Omarchy 4.5, an Arch Linux desktop on Hyprland, built from Omarchy's own stable VM image on the Linux machine with KVM that composes it; its user is signed in at boot"
arch = ["amd64"]
os = { type = "linux", distribution = "omarchy", version = "4.5.0", display = "wayland" }
session = { user = "omarchy" }

[forms.disk]
source = { url = "https://nightly.omarchy.org/stable/4.5.0/479/omarchy-4.5.0.qcow2", sha256 = "dcb401aabf1b01bf3c983a1b048bcd0ac7d66e4f5a755acd9452bf66e18cd5c4" }
init = "systemd"
input_channel = "nocloud"
firmware = ["efi"]
min_disk_gb = 40

[config.resolution]
default = "1920x1080"
phase = "deploy"

[config.timezone]
default = "UTC"
phase = "deploy"
Loading
Loading