easi.run

What is it?

Agents that use the web need a browser. Most teams rent one by the hour from a cloud service, or glue together aheadless Chrome and a VNC server. easi.run is a third way: one command starts it on your own Linux server, andfrom then on every agent gets an isolated Google Chrome, fresh or with your saved logins, and you get a live windowinto each one.

When the agent gets stuck at something only a person can do, you take control from the session's bar. The agentwaits. You type the password, approve the 2FA prompt, or solve the puzzle. You give control back, and the agent carrieson.

Why people use it

• 💸 No per-hour bills. It runs on your server, so you pay for the server and nothing else.
• 🙋 A person can step in. One click to take over, and the agent waits until you hand it back.
• 🔑 Stay logged in. A persistent session brings back your logins, site data (caches aside), history andpreferences each time you resume it, on any site that keeps you logged in when Chrome closes, encrypted with a key only your passwordunlocks (how).
• 🔒 What you type stays yours. What's in a password field never reaches your agent. Once you take over,screenshots stop, and the exact text you type or paste, four characters or more, reaches it as [redacted](how).
• 🧱 Every browser in its own sandbox. Its own containers, no network of its own, and no way into your privatenetwork (security model).
• 🕵️ A real Chrome that sites treat as a real Chrome. Google Chrome itself, clean on BrowserScan, sannysoft andrebrowser's bot detector (what sites see).
• 📁 Files, sound and clipboard just work. Drag a file onto the page, pick one with the page's own uploadbutton, get downloads straight into your Downloads folder, hear the page, and copy and paste both ways.
• 🎥 Record a session on the server in high quality, with your camera and microphone if you like.
• 🤖 Plugs into your agent. A built-in MCP server for Claude Code, Codex and anyMCP client: on your server or over SSH with no token, or over HTTPS with one token per agent. The same tools over aplain REST API. The installer adds it to Claude Code for you when Claude Code is there and has no other servernamed easi.
• 📂 Your agent's own downloads and uploads. It saves what the page downloads and uploads files of its own, likean image it made. By default it asks you before each file, and uploading stays off until you turn it on(how).
• 🌍 Your own proxy per session, checked before use, with the browser's time zone and languages suggested fromwhere it exits.
• ⚡ Our own streaming engine, not VNC. A compositor written in Rust draws Chrome and streams it: still content aslossless tiles, motion as AV1, over UDP where your network allows. Crisp text, smooth video, and a fraction of thebandwidth of a VNC stream (numbers below).

How it compares

✅ has it · – doesn't, partly, not in their docs, or not applicable. The full comparisoncovers 19 alternatives, with the sources and notes (October 2026).

Quick start

Requirements

Each browser session runs with its own limits: 2 CPUs and 2 GiB for Chrome by default, plus a display, proxy and agentbeside it (1152 MiB together), so it takes up to 3.2 GiB of memory. The installer runs as many sessions at once asyour server's memory holds, from 1 to 16, and its summary says how many; each starts when you or an agent asks forone. To change these, put BROWSER_CPUS, BROWSER_MEMORY_MIB or ADMIN_MAX_SESSIONS in ~/easi.run/.env, then runbash install.sh again (Configuration).

1. Install

Ask your coding agent (Claude Code, Codex, or another) on your server:

Read https://easi.run/install.md and install easi.run on this server.

Or run it yourself:

curl -fsSLO https://easi.run/install.sh && less install.sh && bash install.sh

It checks the server, puts the firewall rule in place that keeps pages off your server's own services, sets theserver's TCP for viewers far away (fq and BBR, when the kernel has BBR), starts easi.run, and adds it to Claude Codewhen Claude Code is installed. It needs no sudo: the firewall rule and the TCP settings are made as root through ashort-lived privileged container of Debian's image, pulled by its digest, whose nsenter runs your server's owniptables, systemctl and sysctl. Its summary tells you what it did, and where you create the admin's password.Nothing is compiled on your server: the installer pulls the images easi.run's CI built and published, each checkedagainst the digest the installer names, and adds Google Chrome to the browser image fromGoogle's signed repository (Google's terms let no one else ship Chrome). The first run downloads about 550 MB andtakes one to two minutes on 2 cores with a fast connection.

2. Open the admin

• On the server: https://localhost:9443.

• From your computer: use the command you already use to log in to the server, adding-N -L 9443:127.0.0.1:9443, and keep it running; then open https://localhost:9443. For example:

  ssh -N -L 9443:127.0.0.1:9443 you@your-server
  

  The installer's summary prints this line, filled in with your login when it can tell it.

• VS Code or Cursor over Remote-SSH forward the port for you: open the link from their terminal, or add port 9443in their Ports view; either way, the local port must be 9443 too.

The certificate is your server's own, so the browser warns you about it: the installer keeps a copy in~/.config/easi-run/tls-cert.pem, and the admin logs its fingerprint (docker compose logs admin | grep fingerprint,in ~/easi.run) for you to compare.

3. Create your password

Open https://localhost:9443 (from your computer, through the SSH tunnel of step 2) right after the install: until apassword is set, the admin's first screen asks for one. Choose it, 12 characters or more; you are logged in at once.

• The admin keeps only its Argon2id hash. Wrong passwords and wrong second-step codes count together: the fifthstarts a 2-second wait before the next attempt, each further one doubles it, up to 256 seconds, and a completedsign-in starts the count over.

Next, the admin offers a second step at sign-in. It is optional, and we suggest it: with it on, your password aloneopens nothing.

• An authenticator app, in every browser: scan the QR code with any app that shows 6-digit codes, then type thecode it shows. Each code signs in once.
• A passkey, where your browser offers one: it signs you in on its own, with your fingerprint, face or device PIN.Chrome offers none on a site whose certificate it does not trust, such as the server's own over the tunnel; the pagethen says so, and the app works there.
• Then save the ten recovery codes it shows once: if you lose your phone or passkey, sign in with your passwordand one of them; each works once.

Turn either on, off or replace it later under Security. Lost your phone or passkey and your recovery codes? Rundocker exec easi-run-admin-1 admin reset-second-step on the server, and the password alone signs you in again.

From then on, log in, start a session, and take control from its bar whenever you want.

Update

curl -fsSLO https://easi.run/install.sh && bash install.sh --update

It moves easi.run to the release the newest installer names, and removes the images of the one before; sessionsrunning at the time may end.

Remove

bash ~/easi.run/install.sh --uninstall

After you confirm, it removes easi.run's containers, volumes and images, its firewall rule and the docker.servicedrop-in that puts it in place, and its TCP settings, putting back the values they replaced (unless another easi.runinstallation on the server still needs them),its own files in ~/.config/easi-run (the directory too, when nothing else is in it), and Claude Code's easi serverwhen it is this installation's.It keeps the checkout, ~/easi.run, Docker's build cache, and the Debian image its root steps ran in, and says how toremove them.

Reach the admin from anywhere

Without an SSH tunnel, you can put one of these in front of the admin, each with your own account. Exposing the adminbeyond the server is your choice. Either way, set ADMIN_ORIGIN to the address you will open(Operations has the steps):

• Tailscale: sudo tailscale serve --bg https+insecure://localhost:9443 serves it athttps://<machine>.<tailnet>.ts.net, to your tailnet only; the admin stays on the server's 127.0.0.1.
• Cloudflare Tunnel with Cloudflare Access: cloudflared carries it to a name on your domain, and Access checkswho you are before any request reaches the admin's login page.

What protects it then: who may reach the address at all (your tailnet's devices, or your Access policy), then theadmin's sign-in: your password and, when you turned it on, the second step, or a passkey.

Connect your agent

Every session your agent starts comes with a watch_url: open it to watch live and take over.

Agent on the same server

When the installer's summary says MCP is ready, easi.run is in Claude Code: start a new Claude Code session and askit to browse. For Codex, or any MCP client that runs a command:

codex mcp add easi -- docker exec -i easi-run-admin-1 admin mcp

Agent on your computer, server elsewhere

The same command, carried by SSH (log in with your SSH key): no token, port or certificate to set up.

claude mcp add --scope user easi -- ssh -T you@your-server docker exec -i easi-run-admin-1 admin mcp
codex mcp add easi -- ssh -T you@your-server docker exec -i easi-run-admin-1 admin mcp

Use the login you already use for the server in place of you@your-server. Keep the SSH tunnel from step 2 open towatch the sessions in your browser.

Agents that speak HTTP

Create a token under Agent tokens on the admin page, and use MCP at /mcp or the same tools under /api/agent/(Agents guide).

Your logins for the agent

Start a Persistent session, log in to your sites in it, and stop it: it keeps, encrypted, the logins a site keepswhen Chrome closes, and brings them back when it is resumed. Allow the agent's token (or the local MCP clients) on that saved session; the agent then finds it withlist_saved_sessions and resumes it with start_session's resume.

Performance

Against KasmVNC on the same host and CPU budget, medians of the headless runs (2026-10-21, over the WebSocket):

Every metric, the method and the raw results are in the benchmark.

How it works

flowchart LR
    person(["Your browser"])
    internet(("Internet"))
    subgraph session["One session per browser"]
        agent["agent<br/>Cua Driver"]
        browser["browser<br/>Google Chrome"]
        display["display<br/>Rust compositor"]
        proxy["proxy"]
    end
    admin["admin<br/>HTTPS, and UDP for the media"]
    controller["controller"]
    docker[("Docker")]
    browser -- Wayland --> display
    agent -- input --> display
    browser -- Unix socket --> proxy --> internet
    display -- tiles, video, sound --> admin
    admin <-- HTTPS and WebSocket, WebTransport over UDP --> person
    admin --> controller --> docker

A small compositor written in Rust (display) draws Chrome's windows into its own memory. Still content travels aslossless tiles; motion stays lossless while that is cheap, and otherwise streams as AV1 video that sharpens topixel-perfect once motion stops; the page's sound travels as Opus, over one HTTPS port, and over UDP(WebTransport) where your network lets it through, which keeps the stream smooth on lossy networks. Only the viewerwho holds control can type and click.

• Security model: every boundary, and the test that proves it
• Architecture: the repository's layout, and where each piece of code lives, following a frameand a key press
• Design and topology: the reasoning, the containers, their limits

Contributing

Issues and pull requests are welcome. CONTRIBUTING.md covers building, testing and review, andscripts/dev/run.sh scripts/check.sh runs the checks a change needs in the same image CI uses. Please report securityproblems privately, as SECURITY.md describes.

License

easi.run is free software under the GNU Affero General Public License, version 3 only. Run it, change it,and share it; if you offer a modified version to people over a network, offer them its source too. Every dependencykeeps its own license, listed in docs/licenses.md. The published images encode video only asAV1, which is royalty-free; an H.264 encoder is an opt-in build feature (--build-arg DISPLAY_FEATURES=h264). Theyare published as ghcr.io/julianosig/easi.run-<role>, each tagged and labelled with the commit of this repository itwas built from, which is its source; the browser image carries no Google Chrome, which each installation adds itself.Each carries, in /usr/share/doc/easi.run, this license, where its source is, and the license and notice texts of whatit ships.