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
10 changes: 7 additions & 3 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -70,10 +70,14 @@ updates:
groups:
infra-base-images:
patterns: ["*"]
# The base computer's egress proxy, a Go program its Dockerfile builds: its modules' fixes, uTLS's and
# golang.org/x/crypto's among them. A bump changes the base's sources, so the next release rebuilds and publishes it.
# The base computers' egress proxy, a Go program their Dockerfiles build: its modules' fixes, uTLS's and
# golang.org/x/crypto's among them. A bump changes the bases' sources, so the next release rebuilds and publishes them.
# The browser base's copy is the desktop's, byte for byte (a unit test checks it), so one grouped pull request bumps
# both.
- package-ecosystem: "gomod"
directory: "/src/agent_env/computers/artifacts/ubuntu-24.04/egress"
directories:
- "/src/agent_env/computers/artifacts/ubuntu-24.04/egress"
- "/src/agent_env/computers/artifacts/ubuntu-24.04-browser/egress"
schedule:
interval: "weekly"
open-pull-requests-limit: 5
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,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, settings as `AGENTENV_SETTING_<NAME>`; it starts as root, its container form's `start_as`, whose supervisord, `root.conf`, runs the clock follower as `agentenv-clock`, the egress proxy as `agentenv-egress` (`egress/`, a Go program its Dockerfile builds and tests, on real time, through which every session program goes out, so a live site loads at any universe date: it passes a site's TLS through when the universe is inside the site's certificate, else re-signs it with the computer's own CA, minted at boot and valid from 1950 to 9999, handshaking with the site as the client did, and refuses any destination that isn't global) and the session's supervisord as the session user, which runs every session program), 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. `artifacts/ubuntu-24.04/clock/` is the computer's clock, in the base's folder since an image builds only from its own: agent-env's build of libfaketime 0.9.12 (`libfaketime.patch` and the two `agentenv_clock_*.c` files it includes, GPL-2.0-only as libfaketime is, built by `build.sh` from upstream's sha256-pinned tarball, in a stage of the base's Dockerfile of its own) and the TLS shim, which `/etc/ld.so.preload` loads into every process and which fake only the session user's: clock reads and waits for a set clock time follow the page the follower (`clock-follower`) writes (`clockpage.py`), monotonic and relative waits staying real, with its default settings (`clock.conf`); `tst/clock` gates it. The follower long-polls the gateway's `/clock/watch` under the config core writes through the root channel when a multi env deploys the computer and after a reset (`env/envs/computer/utils/clock.py`), each time waiting on the computer's `sync_time` until it follows, a warning naming why when it doesn't (arming the clock refuses such a computer), and the driver serves `clock/v1` `sync_time` where the follower is (`agentenv_protocol.computer.clock`), not on a disk guest, whose follower core can't reach. |
| `computers/` | The `computers` bundle: the base computers agent-env ships as `computer` artifacts, `ubuntu-24.04` (XFCE on Xvfb, settings as `AGENTENV_SETTING_<NAME>`; it starts as root, its container form's `start_as`, whose supervisord, `root.conf`, runs the clock follower as `agentenv-clock`, the egress proxy as `agentenv-egress` (`egress/`, a Go program its Dockerfile builds and tests, on real time, through which every session program goes out, so a live site loads at any universe date: it passes a site's TLS through when the universe is inside the site's certificate, else re-signs it with the computer's own CA, minted at boot and valid from 1950 to 9999, handshaking with the site as the client did, and refuses any destination that isn't global) and the session's supervisord as the session user, which runs every session program; `root/` installs them at the build, `install.sh`, and starts them at boot, `init`; `ubuntu-24.04-browser`, the base of agent-env's website browsers, has copies of `clock/`, `egress/`, `root/` and `root.conf` that a unit test keeps identical), 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. `artifacts/ubuntu-24.04/clock/` is the computer's clock, in the base's folder since an image builds only from its own: agent-env's build of libfaketime 0.9.12 (`libfaketime.patch` and the two `agentenv_clock_*.c` files it includes, GPL-2.0-only as libfaketime is, built by `build.sh` from upstream's sha256-pinned tarball, in a stage of the base's Dockerfile of its own) and the TLS shim, which `/etc/ld.so.preload` loads into every process and which fake only the session user's: clock reads and waits for a set clock time follow the page the follower (`clock-follower`) writes (`clockpage.py`), monotonic and relative waits staying real, with its default settings (`clock.conf`); `tst/clock` gates it. The follower long-polls the gateway's `/clock/watch` under the config core writes through the root channel when a multi env deploys the computer and after a reset (`env/envs/computer/utils/clock.py`), each time waiting on the computer's `sync_time` until it follows, a warning naming why when it doesn't (arming the clock refuses such a computer), and the driver serves `clock/v1` `sync_time` where the follower is (`agentenv_protocol.computer.clock`), not on a disk guest, whose follower core can't reach. |
| `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`, the page driver aliased `page`, a browser computer's, whose screen is the browser's active tab and which serves Playwright MCP's `browser_*` tools beside `computer_*` from a Playwright MCP it runs attached to the browser over a CDP address the relay issues it (`browser_evaluate` and `browser_run_code_unsafe` hidden by default; each call an entry in the browser's log, begun and ended with `browser/v1` `calls/begin` and `calls/end`, that its CDP commands name as `for`; `scripts/upgrade_playwright_mcp.py` pins its version), 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
54 changes: 43 additions & 11 deletions src/agent_env/computers/artifacts/ubuntu-24.04-browser/Dockerfile
Original file line number Diff line number Diff line change
@@ -1,29 +1,61 @@
# The ubuntu-24.04-browser base computer: Ubuntu 24.04 with no desktop (XDG_SESSION_TYPE=none), for one website
# browser and a page driver whose screen is the browser's page. The browser runs headful on an X server of its own,
# Xvfb on :99, which no agent sees, records or drives, so sites see a browser with a window rather than a headless one.
# supervisord runs every program as the session user, and the browser goes out only through the site proxy on
# 127.0.0.1:3128, which writes its network log to /var/log/agentenv/network.jsonl.
# Files a page's file chooser may be given go in ~/Uploads. Composing a driver or an app onto it adds its services as
# programs in /etc/supervisor/conf.d. The trust files agentenv adds are in /etc/agentenv from boot: ca.pem, empty until
# a deploy adds a CA, and ca-bundle.pem, the public roots and those CAs.
# It starts as root: root's supervisord (root.conf) runs the clock follower and the egress proxy, each as its own user,
# and the session's supervisord (supervisord.conf) as the session user, which runs every session program. The browser
# goes out only through the site proxy on 127.0.0.1:3128, which writes its network log to
# /var/log/agentenv/network.jsonl. Files a page's file chooser may be given go in ~/Uploads. Composing a driver or an app
# onto it adds its services as programs in /etc/supervisor/conf.d. The trust files agentenv adds are in /etc/agentenv
# from boot: ca.pem, the CAs agentenv adds (the egress proxy's from boot, a deploy's for its sites), and ca-bundle.pem,
# the public roots and those CAs.
#
# The universe clock (clock/, a copy of ubuntu-24.04's, which a unit test keeps identical): agent-env's libfaketime and
# its TLS shim, built in a stage of their own so no compiler is left in the image, are preloaded into every process and
# fake only the session user's, from the clock page the follower writes, which the session user can read but neither
# write nor replace.
#
# The egress proxy (egress/, a copy of ubuntu-24.04's, kept identical the same way), on real time where
# AGENTENV_EGRESS_PROXY names, 127.0.0.1:3130: the site proxies hand it every connection to a public address, so a live
# site loads at any universe date. Built and tested in a stage of its own, so no Go toolchain is left in the image. Its
# agentenv-egress.sh and chromium-policy.json are the desktop's, for session programs that go out through it directly,
# and unused here.
#
# The root start (root/, with root.conf, copies of ubuntu-24.04's kept identical the same way): what installs both and
# starts them as root before the session.
FROM public.ecr.aws/docker/library/golang:1.26.11-bookworm@sha256:dc40a13b61304647ed7e5d581d246b86413dfc29d63c6d018310feb93cd98fc0 AS egress
COPY egress/ /egress/
RUN cd /egress && go vet ./... && go test -count=1 ./... \
&& CGO_ENABLED=0 GOFLAGS=-mod=readonly go build -trimpath -ldflags=-s -o /out/egress .

FROM public.ecr.aws/docker/library/ubuntu:24.04@sha256:24737cef17f4e22b1977df7d9a05e77c4e28b7da5b8911f8d8ccda136bf3573c AS clock
RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
build-essential patch curl ca-certificates
COPY clock/ /clock/
RUN sh /clock/build.sh /out

FROM public.ecr.aws/docker/library/ubuntu:24.04@sha256:24737cef17f4e22b1977df7d9a05e77c4e28b7da5b8911f8d8ccda136bf3573c
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
supervisor tini python3 python3-venv fonts-dejavu-core tzdata ca-certificates procps xvfb \
supervisor tini python3 python3-venv fonts-dejavu-core tzdata ca-certificates libnss3-tools procps xvfb \
&& rm -rf /var/lib/apt/lists/* \
&& userdel --remove ubuntu \
&& useradd --create-home --uid 1000 --shell /bin/bash user \
&& runuser -u user -- mkdir -p /home/user/Desktop /home/user/Documents /home/user/Downloads /home/user/Uploads \
&& mkdir -p /etc/supervisor/conf.d /var/log/agentenv /run/agentenv \
&& mkdir -p /etc/agentenv && touch /etc/agentenv/ca.pem \
&& cp /etc/ssl/certs/ca-certificates.crt /etc/agentenv/ca-bundle.pem \
&& chown user:user /var/log/agentenv /run/agentenv
COPY --from=clock /out/libfaketimeMT.so.1 /out/libtls_realtime.so /usr/local/lib/agentenv-clock/
COPY clock/clockpage.py clock/clock-follower /usr/local/lib/agentenv-clock/
COPY clock/clock.conf /etc/agentenv/clock.conf
COPY --from=egress /out/egress /usr/local/lib/agentenv-egress/egress
COPY root/ /usr/local/lib/agentenv-root/
RUN sh /usr/local/lib/agentenv-root/install.sh user
COPY root.conf /etc/supervisor/root.conf
COPY supervisord.conf /etc/supervisor/supervisord.conf
COPY start-computer /usr/local/bin/start-computer
COPY site-proxy.py /usr/local/bin/agentenv-site-proxy
USER user
USER root
WORKDIR /home/user
ENV LANG=C.UTF-8 XDG_SESSION_TYPE=none DISPLAY=:99 AGENTENV_SITE_PROXY=http://127.0.0.1:3128 \
AGENTENV_NETWORK_LOG=/var/log/agentenv/network.jsonl
AGENTENV_NETWORK_LOG=/var/log/agentenv/network.jsonl AGENTENV_EGRESS_PROXY=http://127.0.0.1:3130
ENTRYPOINT ["/usr/bin/tini", "--"]
CMD ["/usr/local/bin/start-computer"]
CMD ["/usr/local/bin/start-computer", "init"]
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
type = "computer"
description = "Ubuntu 24.04 with no desktop, for one website browser, headful on an X server only it uses, and a page driver whose screen is its page; run by supervisord as the session user"
description = "Ubuntu 24.04 with no desktop, for one website browser, headful on an X server only it uses, and a page driver whose screen is its page; run by supervisord as the session user, on the universe clock"
arch = ["amd64", "arm64"]
os = { type = "linux", distribution = "ubuntu", version = "24.04", display = "none" }
session = { user = "user" }
Expand All @@ -8,6 +8,7 @@ session = { user = "user" }
image = { dockerfile = "Dockerfile" }
init = "supervisord"
input_channel = "env"
start_as = "root"

[config.timezone]
default = "UTC"
Expand Down
Loading
Loading