Updated image template

A volume was only writable by root. Formatting a fresh volume leaves its
top-level directory owned by root, so anything running as the capsule's
normal user — including file uploads and downloads — was refused, and the
only way to write to your own volume was to reach for sudo.

A volume is now opened up to everyone in the capsule the moment it is first
formatted, the same way /tmp works: anyone can create files in it, and no
one can delete someone else's.

Only ever applied to a volume being formatted for the first time. Re-attaching
a volume you already have leaves its permissions exactly as you set them, so
this never overrides a choice you made. Volumes formatted before this change
stay as they are.

.env.example

@@ -1,3 +1,7 @@
+# Shared (applies to both control plane and host agent)
+WRENN_DIR=/var/lib/wrenn
+LOG_LEVEL=info
+
 # Database
 DATABASE_URL=postgres://wrenn:wrenn@localhost:5432/wrenn?sslmode=disable
 
@@ -9,10 +13,25 @@ WRENN_CP_LISTEN_ADDR=:9725
 
 # Host Agent
 WRENN_HOST_LISTEN_ADDR=:50051
-WRENN_DIR=/var/lib/wrenn
 WRENN_HOST_INTERFACE=eth0
 WRENN_CP_URL=http://localhost:9725
 WRENN_DEFAULT_ROOTFS_SIZE=5Gi
+WRENN_CH_BIN=/usr/local/bin/cloud-hypervisor
+# Public domain sandboxes are served under; injected into envd so `envd ports`
+# can build {port}-{sandbox_id}.{domain} URLs.
+WRENN_PROXY_DOMAIN=wrenn.dev
+
+# Inactivity activity sampler (all optional; shown values are the defaults).
+# The host polls each running sandbox's guest liveness and refreshes its
+# inactivity TTL when it is doing real work, so a long-running but
+# non-interactive job (build, download) is not auto-paused. A sandbox counts
+# as busy when guest CPU ≥ threshold, or net/disk throughput ≥ the floor.
+# Busy requires the threshold to hold for 2 consecutive samples (debounced),
+# so isolated idle-noise spikes do not keep a sandbox alive.
+WRENN_ACTIVITY_SAMPLE_INTERVAL=5s
+WRENN_CPU_BUSY_THRESHOLD=5.0
+WRENN_NET_FLOOR_BPS=16384
+WRENN_DISK_FLOOR_BPS=32768
 
 # Auth
 JWT_SECRET=
@@ -28,9 +47,26 @@ WRENN_CA_KEY=
 # Channels (notification destinations)
 # AES-256-GCM key for encrypting channel secrets. Generate with: openssl rand -hex 32
 WRENN_ENCRYPTION_KEY=
+# Allow notification channels to target private/loopback/link-local addresses.
+# Off by default to prevent SSRF; set to true only on self-hosted deployments
+# that deliver to internal endpoints.
+WRENN_CHANNELS_ALLOW_PRIVATE=false
+
+# External storage volumes
+# Largest size a single volume may be created with. Accepts G/Gi/M/Mi suffixes
+# (same form as WRENN_DEFAULT_ROOTFS_SIZE). Volumes are sparse files, so this
+# bounds worst-case growth rather than upfront allocation.
+WRENN_MAX_VOLUME_SIZE=20Gi
 
 # OAuth
 OAUTH_GITHUB_CLIENT_ID=
 OAUTH_GITHUB_CLIENT_SECRET=
 OAUTH_REDIRECT_URL=https://app.wrenn.dev
 CP_PUBLIC_URL=https://app.wrenn.dev
+
+# SMTP — transactional email (optional; omit SMTP_HOST to disable)
+SMTP_HOST=
+SMTP_PORT=587
+SMTP_USERNAME=
+SMTP_PASSWORD=
+SMTP_FROM_EMAIL=noreply@wrenn.dev

.gitignore

@@ -33,12 +33,15 @@ go.work.sum
 
 ## AI
 .claude/
-e2b/
 .impeccable.md
 .gstack
+.mcp.json
 
 ## Builds
-builds/
+/builds/
+
+## Rust
+envd-rs/target/
 
 ## Frontend
 frontend/node_modules/
@@ -49,3 +52,9 @@ frontend/build/
 internal/dashboard/static/*
 !internal/dashboard/static/.gitkeep.dual-graph/
 .dual-graph/
+# Added by code-review-graph
+.code-review-graph/
+.mcp.json
+
+# tokensave
+.tokensave/

.woodpecker/pipeline.yml

@@ -0,0 +1,63 @@
+when:
+  - event: [push, manual]
+    branch: main
+
+steps:
+  build-go:
+    image: python:3.13
+    environment:
+      WRENN_API_KEY:
+        from_secret: wrenn_api_key
+    commands:
+      - pip install wrenn httpx
+      - export GO_VERSION=$$(grep '^go ' go.mod | cut -d' ' -f2)
+      - python .woodpecker/scripts/build_go.py
+    depends_on: []
+
+  build-rust:
+    image: python:3.13
+    environment:
+      WRENN_API_KEY:
+        from_secret: wrenn_api_key
+    commands:
+      - pip install wrenn
+      - export RUST_VERSION=$$(grep '^rust-version ' envd-rs/Cargo.toml | cut -d'"' -f2)
+      - python .woodpecker/scripts/build_rust.py
+    depends_on: []
+
+  tag-release:
+    image: python:3.13
+    environment:
+      GITEA_TOKEN:
+        from_secret: gitea_token
+    commands:
+      - VERSION=$$(cat VERSION_CP)
+      - git config user.name "R3dRum92"
+      - git config user.email "tksadik@omukk.dev"
+      - git tag "v$${VERSION}"
+      - git push "https://tksadik92:$${GITEA_TOKEN}@git.omukk.dev/wrenn/wrenn.git" "v$${VERSION}"
+    depends_on: [build-go, build-rust]
+
+  release-notes:
+    image: python:3.13
+    environment:
+      WRENN_API_KEY:
+        from_secret: wrenn_api_key
+      GITEA_TOKEN:
+        from_secret: gitea_token
+      ZHIPU_API_KEY:
+        from_secret: zhipu_api_key
+    commands:
+      - pip install wrenn
+      - python .woodpecker/scripts/release_notes.py
+    depends_on: [tag-release]
+
+  publish-github:
+    image: python:3.13
+    environment:
+      GITHUB_TOKEN:
+        from_secret: github_token
+    commands:
+      - pip install httpx
+      - python .woodpecker/scripts/publish_github.py
+    depends_on: [release-notes]

.woodpecker/scripts/build_go.py

@@ -0,0 +1,112 @@
+import os
+import sys
+
+from wrenn import Capsule, StreamExitEvent, StreamStderrEvent, StreamStdoutEvent
+from wrenn._git import GitCommandError
+
+GO_VERSION = os.getenv("GO_VERSION", "1.25.8")
+REPO_URL = "https://git.omukk.dev/wrenn/wrenn.git"
+REPO_DIR = "/home/wrenn-user/wrenn"
+BUILDS_DIR = os.path.join(os.path.dirname(__file__), "..", "..", "builds")
+
+
+def read_remote_version(capsule: Capsule, filename: str) -> str:
+    content = capsule.files.read_bytes(f"{REPO_DIR}/{filename}")
+    return content.decode("utf-8").strip()
+
+
+def run(capsule: Capsule, cmd: str, timeout: int = 30) -> int:
+    result = capsule.commands.run(cmd, timeout=timeout)
+    if result.exit_code != 0:
+        print(f"FAIL [{cmd.split()[0]}]: exit={result.exit_code}", file=sys.stderr)
+        if result.stderr:
+            print(result.stderr.strip(), file=sys.stderr)
+        return result.exit_code
+    print(f"OK   [{cmd.split()[0]}]")
+    return 0
+
+
+def clone_repo(capsule: Capsule) -> bool:
+    try:
+        capsule.git.clone(REPO_URL, REPO_DIR)
+        print("OK   [git clone]")
+        return True
+    except GitCommandError as e:
+        print(f"FAIL [git clone]: {e}", file=sys.stderr)
+        return False
+
+
+def build_go(capsule: Capsule) -> bool:
+    command = "CGO_ENABLED=1 make build-cp build-agent"
+    handle = capsule.commands.run(
+        command,
+        background=True,
+        cwd=REPO_DIR,
+        envs={
+            "PATH": "/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+        },
+    )
+    print(f"{command} started (pid={handle.pid}), streaming output...")
+
+    exit_code = 0
+    for event in capsule.commands.connect(handle.pid):
+        if isinstance(event, StreamStdoutEvent):
+            print(event.data, end="")
+        elif isinstance(event, StreamStderrEvent):
+            print(event.data, end="", file=sys.stderr)
+        elif isinstance(event, StreamExitEvent):
+            exit_code = event.exit_code
+
+    if exit_code != 0:
+        print(f"FAIL [go build]: exit={exit_code}", file=sys.stderr)
+        return False
+    print("OK   [go build]")
+    return True
+
+
+def download_artifacts(capsule: Capsule) -> bool:
+    remote_dir = f"{REPO_DIR}/builds"
+    entries = capsule.files.list(remote_dir, depth=1)
+    files = [e for e in entries if e.type != "directory"]
+
+    if not files:
+        print("FAIL [download]: no files found in builds/", file=sys.stderr)
+        return False
+
+    local_dir = os.path.normpath(BUILDS_DIR)
+    os.makedirs(local_dir, exist_ok=True)
+    versions = {
+        "wrenn-cp": read_remote_version(capsule, "VERSION_CP"),
+        "wrenn-agent": read_remote_version(capsule, "VERSION_AGENT"),
+    }
+
+    for entry in files:
+        name = entry.name or "unknown"
+        remote_path = f"{remote_dir}/{name}"
+        local_name = f"{name}-{versions[name]}" if name in versions else name
+        local_path = os.path.join(local_dir, local_name)
+        print(f"Downloading {name} as {local_name} ({entry.size or '?'} bytes)...")
+
+        with open(local_path, "wb") as f:
+            for chunk in capsule.files.download_stream(remote_path):
+                f.write(chunk)
+
+        print(f"OK   [download {local_name}]")
+
+    return True
+
+
+def main() -> None:
+    with Capsule(template="golang", wait=True) as capsule:
+        print(f"Capsule: {capsule.capsule_id}")
+        if not clone_repo(capsule):
+            sys.exit(1)
+        if not build_go(capsule):
+            sys.exit(1)
+        if not download_artifacts(capsule):
+            sys.exit(1)
+        print("Done.")
+
+
+if __name__ == "__main__":
+    main()

.woodpecker/scripts/build_rust.py

@@ -0,0 +1,105 @@
+import os
+import sys
+
+from wrenn import Capsule, StreamExitEvent, StreamStderrEvent, StreamStdoutEvent
+from wrenn._git import GitCommandError
+
+RUST_VERSION = os.getenv("RUST_VERSION", "1.95.0")
+REPO_URL = "https://git.omukk.dev/wrenn/wrenn.git"
+REPO_DIR = "/home/wrenn-user/wrenn"
+BUILDS_DIR = os.path.join(os.path.dirname(__file__), "..", "..", "builds")
+
+
+def read_envd_version(capsule: Capsule) -> str:
+    content = capsule.files.read_bytes(f"{REPO_DIR}/envd-rs/Cargo.toml")
+    for line in content.decode("utf-8").splitlines():
+        stripped = line.strip()
+        if stripped.startswith("version ="):
+            return stripped.split("=", 1)[1].strip().strip('"')
+    print("FAIL [version]: envd-rs/Cargo.toml has no package version", file=sys.stderr)
+    sys.exit(1)
+
+
+def run(capsule: Capsule, cmd: str, timeout: int = 30, envs={}) -> int:
+    result = capsule.commands.run(cmd, timeout=timeout, envs=envs)
+    if result.exit_code != 0:
+        print(f"FAIL [{cmd.split()[0]}]: exit={result.exit_code}", file=sys.stderr)
+        if result.stderr:
+            print(result.stderr.strip(), file=sys.stderr)
+        return result.exit_code
+    print(f"OK   [{cmd.split()[0]}]")
+    return 0
+
+
+def clone_repo(capsule: Capsule) -> bool:
+    try:
+        capsule.git.clone(REPO_URL, REPO_DIR)
+        print("OK   [git clone]")
+        return True
+    except GitCommandError as e:
+        print(f"FAIL [git clone]: {e}", file=sys.stderr)
+        return False
+
+
+def build_rust(capsule: Capsule) -> bool:
+    if run(capsule, f"mkdir -p {REPO_DIR}/builds") != 0:
+        return False
+
+    handle = capsule.commands.run(
+        "make build-envd",
+        background=True,
+        cwd=REPO_DIR,
+        envs={
+            "PATH": "/home/wrenn-user/.cargo/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+        },
+    )
+    print(f"rust build started (pid={handle.pid}), streaming output...")
+
+    exit_code = 0
+    for event in capsule.commands.connect(handle.pid):
+        if isinstance(event, StreamStdoutEvent):
+            print(event.data, end="")
+        elif isinstance(event, StreamStderrEvent):
+            print(event.data, end="", file=sys.stderr)
+        elif isinstance(event, StreamExitEvent):
+            exit_code = event.exit_code
+
+    if exit_code != 0:
+        print(f"FAIL [rust build]: exit={exit_code}", file=sys.stderr)
+        return False
+
+    print("OK   [rust build]")
+    return True
+
+
+def download_artifacts(capsule: Capsule) -> bool:
+    version = read_envd_version(capsule)
+    remote_path = f"{REPO_DIR}/builds/envd"
+    local_dir = os.path.normpath(BUILDS_DIR)
+    local_name = f"envd-{version}"
+    local_path = os.path.join(local_dir, local_name)
+    os.makedirs(local_dir, exist_ok=True)
+
+    print(f"Downloading envd as {local_name}...")
+    with open(local_path, "wb") as f:
+        for chunk in capsule.files.download_stream(remote_path):
+            f.write(chunk)
+
+    print(f"OK   [download {local_name}]")
+    return True
+
+
+def main() -> None:
+    with Capsule(template="rust-1.95", wait=True) as capsule:
+        print(f"Capsule: {capsule.capsule_id}")
+        if not clone_repo(capsule):
+            sys.exit(1)
+        if not build_rust(capsule):
+            sys.exit(1)
+        if not download_artifacts(capsule):
+            sys.exit(1)
+        print("Done.")
+
+
+if __name__ == "__main__":
+    main()

.woodpecker/scripts/publish_github.py

@@ -0,0 +1,104 @@
+import os
+import sys
+from pathlib import Path
+
+import httpx
+
+GITHUB_REPO = "wrennhq/wrenn"
+GITHUB_API = "https://api.github.com"
+GITHUB_UPLOADS = "https://uploads.github.com"
+BUILDS_DIR = "builds"
+VERSION_FILE = "VERSION_CP"
+NOTES_FILE = os.path.join(".woodpecker", "release_notes.md")
+
+
+def main() -> None:
+    token = os.environ["GITHUB_TOKEN"]
+
+    with open(VERSION_FILE) as f:
+        version = f.read().strip()
+    tag = f"v{version}"
+
+    release_notes = ""
+    if os.path.exists(NOTES_FILE):
+        with open(NOTES_FILE) as f:
+            release_notes = f.read()
+
+    headers = {
+        "Authorization": f"token {token}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+
+    client = httpx.Client(headers=headers, timeout=60)
+
+    print(f"Creating GitHub release for {tag}...")
+    resp = client.post(
+        f"{GITHUB_API}/repos/{GITHUB_REPO}/releases",
+        json={
+            "tag_name": tag,
+            "name": tag,
+            "body": release_notes,
+            "draft": False,
+            "prerelease": False,
+        },
+    )
+    if resp.status_code == 422:
+        print(f"WARN [create release]: release for {tag} already exists, skipping")
+        data = resp.json()
+        errors = data.get("errors", [])
+        if errors:
+            existing_url = errors[0].get("documentation_url", "")
+            print(f"  See: {existing_url}")
+        client.close()
+        return
+    if resp.status_code != 201:
+        print(f"FAIL [create release]: {resp.status_code} {resp.text}", file=sys.stderr)
+        client.close()
+        sys.exit(1)
+
+    release_data = resp.json()
+    release_id = release_data["id"]
+    release_url = release_data.get("html_url", "")
+    print(f"OK   [create release] id={release_id}")
+
+    builds_path = Path(BUILDS_DIR)
+    if not builds_path.exists():
+        print(f"No {BUILDS_DIR}/ directory found, skipping asset upload")
+        client.close()
+        print(f"Release published: {release_url}")
+        return
+
+    upload_headers = {
+        **headers,
+        "Content-Type": "application/octet-stream",
+    }
+
+    for artifact in sorted(builds_path.iterdir()):
+        if artifact.is_dir():
+            continue
+        print(f"Uploading {artifact.name}...")
+
+        with open(artifact, "rb") as f:
+            data = f.read()
+
+        resp = client.post(
+            f"{GITHUB_UPLOADS}/repos/{GITHUB_REPO}/releases/{release_id}/assets",
+            params={"name": artifact.name},
+            headers=upload_headers,
+            content=data,
+        )
+        if resp.status_code != 201:
+            print(
+                f"WARN [upload {artifact.name}]: {resp.status_code} {resp.text}",
+                file=sys.stderr,
+            )
+        else:
+            print(f"OK   [upload {artifact.name}]")
+
+    client.close()
+    print(f"Release published: {release_url}")
+
+
+if __name__ == "__main__":
+    main()

.woodpecker/scripts/release_notes.py

@@ -0,0 +1,237 @@
+import base64
+import os
+import sys
+
+from wrenn import Capsule
+
+REPO_URL = "https://git.omukk.dev/wrenn/wrenn.git"
+REPO_DIR = "wrenn-releases"
+CAPSULE_OUTPUT = "/tmp/release_notes.md"
+LOCAL_OUTPUT = os.path.join(os.path.dirname(__file__), "..", "release_notes.md")
+
+DEFAULT_MODEL = "opencode/big-pickle"
+
+RELEASE_NOTES_EXAMPLE = """
+## What's new
+Sandbox HTTP proxying, terminal reliability, and auth robustness improvements.
+
+### Proxy
+- Fixed redirect loops for apps served inside sandboxes (Python HTTP server, Jupyter, etc.)
+- Proxy traffic no longer interferes with terminal and exec connections
+- Services that take a moment to start up inside a sandbox are now retried instead of immediately failing
+
+### Terminal (PTY)
+- Terminal input is no longer blocked by slow network conditions — fast typing no longer causes timeouts or disconnects
+- Input bursts are coalesced into fewer round trips — lower latency under fast typing
+
+### Authentication
+- WebSocket connections now authenticate correctly for both SDK clients (header-based) and browser clients (message-based)
+
+### Bug Fixes
+- Fixed crash in envd when a process exits without a PTY
+- Fixed goroutine leak on sandbox pause
+
+### Others
+- Version bump
+""".strip()
+
+
+def run(capsule: Capsule, cmd: str, cwd: str | None = None, timeout: int = 30) -> int:
+    result = capsule.commands.run(cmd, cwd=cwd, timeout=timeout)
+    if result.exit_code != 0:
+        print(f"FAIL [{cmd.split()[0]}]: exit={result.exit_code}", file=sys.stderr)
+        if result.stderr:
+            print(result.stderr.strip(), file=sys.stderr)
+        return result.exit_code
+    print(f"OK   [{cmd.split()[0]}]")
+    return 0
+
+
+def generate_release_notes(
+    capsule: Capsule,
+    output_path: str,
+    model: str,
+) -> None:
+    prompt = f"""
+    You are inside a cloned git repository at:
+
+    {REPO_DIR}
+
+    Generate release notes for the latest tagged version of this software project.
+
+    Before writing anything, inspect the repository yourself using git commands.
+
+    You MUST determine:
+        1. The latest version tag.
+        2. The previous version tag, if one exists.
+        3. The commits between the previous tag and the latest tag.
+        4. The files and areas changed between those tags.
+
+    Use commands like:
+
+    git tag --sort=-version:refname
+
+    Compare the newest tag against the previous tag:
+
+    git log PREVIOUS_TAG..LATEST_TAG --pretty=format:'%s (%h)'
+    git diff PREVIOUS_TAG..LATEST_TAG --stat
+    git diff PREVIOUS_TAG..LATEST_TAG --name-only
+
+    If there is only one tag, inspect the latest tag with:
+
+    Do not rely on any pre-injected commit list or diff summary.
+    You must inspect the git history yourself.
+
+    Write the release notes in plain, friendly language that any developer can understand
+    without deep knowledge of the codebase.
+
+    Avoid jargon like "goroutine", "PTY", "envd", or internal function names.
+    Describe what the change means for the user instead.
+
+    Group related changes under headings that reflect what actually changed.
+    Only include sections that are relevant to the actual changes.
+    Do not include CI/CD-only changes.
+
+    Start with:
+
+    ## What's New
+
+    The very next line must be a single short summary sentence.
+
+    Keep each bullet point to one clear sentence.
+
+    Here is an example of the style to aim for — not a template to copy:
+
+    {RELEASE_NOTES_EXAMPLE}
+
+    Output only the final markdown.
+    No intro.
+    No explanation.
+    No conversational filler.
+    No acknowledgments.
+    No "I checked the logs" text.
+    No thoughts.
+    """.strip()
+
+    prompt_b64 = base64.b64encode(prompt.encode("utf-8")).decode("utf-8")
+
+    write_prompt_cmd = f"echo '{prompt_b64}' | base64 -d > /tmp/oc_prompt.txt"
+
+    result = capsule.commands.run(
+        write_prompt_cmd,
+        cwd=REPO_DIR,
+        timeout=10,
+    )
+    if result.exit_code != 0:
+        print(f"FAIL [write prompt]: {result.stderr}", file=sys.stderr)
+        sys.exit(1)
+
+    def run_opencode_with_model(target_model: str) -> int:
+        env = ""
+        if "zhipu" in target_model.lower():
+            env = f"ZHIPU_API_KEY={os.environ.get('ZHIPU_API_KEY', '')}"
+
+        raw_output_path = "/tmp/opencode_raw.txt"
+        cmd = (
+            f"{env} "
+            f"~/.opencode/bin/opencode run "
+            f'"Read the attached file and generate the release notes. Output ONLY markdown." '
+            f"--model {target_model} "
+            f"--file /tmp/oc_prompt.txt "
+            f"> {raw_output_path}"
+        )
+
+        cmd_result = capsule.commands.run(cmd, cwd=REPO_DIR, timeout=300)
+        if cmd_result.exit_code != 0:
+            print(
+                f"FAIL [opencode via {target_model}]: exit={cmd_result.exit_code}",
+                file=sys.stderr,
+            )
+            print(f"STDOUT:\n{cmd_result.stdout}", file=sys.stderr)
+            print(f"STDERR:\n{cmd_result.stderr}", file=sys.stderr)
+
+        clean_cmd = (
+            f"awk 'found || /^## What.s [Nn]ew/ {{ found=1; print }}' "
+            f"{raw_output_path} > {output_path}"
+        )
+
+        clean_result = capsule.commands.run(clean_cmd, cwd=REPO_DIR, timeout=10)
+        if clean_result.exit_code != 0:
+            print(f"FAIL [clean output]: {clean_result.stderr}", file=sys.stderr)
+            return clean_result.exit_code
+
+        check_result = capsule.commands.run(
+            f"grep -q '^## What.s New' {output_path}",
+            cwd=REPO_DIR,
+            timeout=10,
+        )
+        if check_result.exit_code != 0:
+            print(
+                "FAIL: Could not find release notes heading in opencode output",
+                file=sys.stderr,
+            )
+            print(cmd_result.stdout, file=sys.stderr)
+            print(cmd_result.stderr, file=sys.stderr)
+            return 1
+
+        return cmd_result.exit_code
+
+    exit_status = run_opencode_with_model(model)
+
+    if exit_status != 0:
+        fallback_model = "opencode/big-pickle"
+        if model != fallback_model:
+            print(
+                f"\n[!] Model {model} failed. Falling back to {fallback_model}...",
+                file=sys.stderr,
+            )
+            exit_status = run_opencode_with_model(fallback_model)
+            if exit_status != 0:
+                print("FAIL: Fallback model also failed. Exiting.", file=sys.stderr)
+                sys.exit(1)
+        else:
+            sys.exit(1)
+
+    result = capsule.commands.run(f"cat {output_path}")
+    print(result.stdout)
+    if result.stderr:
+        print(result.stderr)
+
+    print(f"OK   [opencode] release notes written to {output_path}")
+
+
+def download_release_notes(capsule: Capsule) -> None:
+    local_path = os.path.normpath(LOCAL_OUTPUT)
+    os.makedirs(os.path.dirname(local_path), exist_ok=True)
+
+    print("Downloading release notes from capsule...")
+    content = capsule.files.read_bytes(CAPSULE_OUTPUT)
+    with open(local_path, "wb") as f:
+        f.write(content)
+
+    print(f"OK   [download] release notes → {local_path}")
+    print(content.decode("utf-8", errors="replace"))
+
+
+def main() -> None:
+    model = os.environ.get("OPENCODE_MODEL", DEFAULT_MODEL)
+
+    with Capsule(template="opencode", wait=True) as capsule:
+        print(f"Capsule: {capsule.capsule_id}")
+
+        capsule.git.clone(
+            REPO_URL,
+            REPO_DIR,
+        )
+        print("OK   [git clone]")
+
+        # Note: This simply creates the directory string safely
+        output_path = os.path.normpath(CAPSULE_OUTPUT)
+
+        generate_release_notes(capsule, output_path, model)
+
+        download_release_notes(capsule)
+
+
+if __name__ == "__main__":
+    main()

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Wrenn Sandbox is a microVM-based code execution platform. Users create isolated sandboxes (Firecracker microVMs), run code inside them, and get output back via SDKs. Think E2B but with persistent sandboxes, pool-based pricing, and a single-binary deployment story.
+Wrenn is the runtime where AI engineers live — an open-source platform for running AI coding agents. Each project gets a persistent, isolated workspace (Cloud Hypervisor microVM) where agents edit code, run tests, debug, and ship continuously, with humans supervising via SDKs and chat surfaces. Fast boot, persistent state, available hosted or fully self-hosted with a single agent binary on each host you own. (The underlying primitive is still an isolated microVM — "sandbox" in the API/backend, "capsule" in the dashboard.)
 
 ## Build & Development Commands
 
@@ -12,10 +12,10 @@ All commands go through the Makefile. Never use raw `go build` or `go run`.
 
 ```bash
 make build              # Build all binaries → builds/
-make build-cp           # Control plane only (builds frontend first)
+make build-cp           # Control plane only
 make build-agent        # Host agent only
-make build-envd         # envd static binary (verified statically linked)
-make build-frontend     # SvelteKit dashboard → internal/dashboard/static/
+make build-envd         # envd static binary (Rust, musl, verified statically linked)
+make build-frontend     # SvelteKit dashboard → frontend/build/ (served by Caddy)
 
 make dev                # Full local dev: infra + migrate + control plane
 make dev-infra          # Start PostgreSQL + Prometheus + Grafana (Docker)
@@ -23,13 +23,13 @@ make dev-down           # Stop dev infra
 make dev-cp             # Control plane with hot reload (if air installed)
 make dev-frontend       # Vite dev server with HMR (port 5173)
 make dev-agent          # Host agent (sudo required)
-make dev-envd           # envd in TCP debug mode
+make dev-envd           # envd in debug mode (port 49983)
 
 make check              # fmt + vet + lint + test (CI order)
 make test               # Unit tests: go test -race -v ./internal/...
-make test-integration   # Integration tests (require host agent + Firecracker)
-make fmt                # gofmt both modules
-make vet                # go vet both modules
+make test-integration   # Integration tests (require host agent + Cloud Hypervisor)
+make fmt                # gofmt and rust fmt
+make vet                # go vet
 make lint               # golangci-lint
 
 make migrate-up         # Apply pending migrations
@@ -38,8 +38,8 @@ make migrate-create name=xxx  # Scaffold new goose migration (never create manua
 make migrate-reset      # Drop + re-apply all
 
 make generate           # Proto (buf) + sqlc codegen
-make proto              # buf generate for all proto dirs
-make tidy               # go mod tidy both modules
+make proto              # buf generate for proto dirs
+make tidy               # go mod tidy
 ```
 
 Run a single test: `go test -race -v -run TestName ./internal/path/...`
@@ -50,63 +50,90 @@ Run a single test: `go test -race -v -run TestName ./internal/path/...`
 User SDK → HTTPS/WS → Control Plane → Connect RPC → Host Agent → HTTP/Connect RPC over TAP → envd (inside VM)
 ```
 
-**Three binaries, two Go modules:**
+**Three binaries:**
 
-| Binary | Module | Entry point | Runs as |
-|--------|--------|-------------|---------|
-| wrenn-cp | `git.omukk.dev/wrenn/wrenn` | `cmd/control-plane/main.go` | Unprivileged |
-| wrenn-agent | `git.omukk.dev/wrenn/wrenn` | `cmd/host-agent/main.go` | Root (NET_ADMIN + /dev/kvm) |
-| envd | `git.omukk.dev/wrenn/wrenn/envd` (standalone `envd/go.mod`) | `envd/main.go` | PID 1 inside guest VM |
+| Binary | Language | Entry point | Runs as |
+|--------|----------|-------------|---------|
+| wrenn-cp | Go (`git.omukk.dev/wrenn/wrenn`) | `cmd/control-plane/main.go` | Unprivileged |
+| wrenn-agent | Go (`git.omukk.dev/wrenn/wrenn`) | `cmd/host-agent/main.go` | `wrenn` user with capabilities (SYS_ADMIN, NET_ADMIN, NET_RAW, SYS_PTRACE, KILL, DAC_OVERRIDE, MKNOD) via setcap; also accepts root |
+| envd | Rust (`envd-rs/`) | `envd-rs/src/main.rs` | PID 1 inside guest VM |
 
-envd is a **completely independent Go module**. It is never imported by the main module. The only connection is the protobuf contract. It compiles to a static binary baked into rootfs images.
+envd is a standalone Rust binary (Tokio + Axum + connectrpc-rs). It is completely independent from the Go module — the only connection is the protobuf contract. It compiles to a statically linked musl binary baked into rootfs images.
 
-**Key architectural invariant:** The host agent is **stateful** (in-memory `boxes` map is the source of truth for running VMs). The control plane is **stateless** (all persistent state in PostgreSQL). The reconciler (`internal/api/reconciler.go`) bridges the gap — it periodically compares DB records against the host agent's live state and marks orphaned sandboxes as "stopped".
+**Key architectural invariant:** The host agent is **stateful** (in-memory `boxes` map is the source of truth for running VMs). The control plane is **stateless** (all persistent state in PostgreSQL). The host monitor (`internal/api/host_monitor.go`) bridges the gap — it periodically compares DB records against the host agent's live state and marks orphaned sandboxes as "stopped".
 
 ### Control Plane
 
-**Packages:** `internal/api/`, `internal/dashboard/`, `internal/auth/`, `internal/scheduler/`, `internal/lifecycle/`, `internal/config/`, `internal/db/`
+**Internal packages:** `internal/api/`, `internal/email/`
 
-Startup (`cmd/control-plane/main.go`) wires: config (env vars) → pgxpool → `db.Queries` (sqlc-generated) → Connect RPC client to host agent → `api.Server`. Everything flows through constructor injection.
+**Public packages (importable by cloud repo):** `pkg/config/`, `pkg/db/`, `pkg/auth/`, `pkg/auth/oauth/`, `pkg/auth/session/`, `pkg/auth/session/middleware/`, `pkg/scheduler/`, `pkg/lifecycle/`, `pkg/channels/`, `pkg/audit/`, `pkg/service/`, `pkg/events/`, `pkg/id/`, `pkg/validate/`, `pkg/netutil/`
 
-- **API Server** (`internal/api/server.go`): chi router with middleware. Creates handler structs (`sandboxHandler`, `execHandler`, `filesHandler`, etc.) injected with `db.Queries` and the host agent Connect RPC client. Routes under `/v1/capsules/*`.
-- **Reconciler** (`internal/api/reconciler.go`): background goroutine (every 30s) that compares DB records against `agent.ListSandboxes()` RPC. Marks orphaned DB entries as "stopped".
-- **Dashboard** (SvelteKit + Tailwind + Bits UI, statically built and embedded via `go:embed`, served as catch-all at root)
-- **Database**: PostgreSQL via pgx/v5. Queries generated by sqlc from `db/queries/sandboxes.sql`. Migrations in `db/migrations/` (goose, plain SQL).
-- **Config** (`internal/config/config.go`): purely environment variables (`DATABASE_URL`, `CP_LISTEN_ADDR`, `CP_HOST_AGENT_ADDR`), no YAML/file config.
+**Extension framework:** `pkg/cpextension/` (shared `Extension` interface + `ServerContext` + hook interfaces), `pkg/cpserver/` (exported `Run()` entrypoint with functional options for cloud `main.go`)
+
+The cloud repo imports this module as a Go dependency and calls `cpserver.Run(cpserver.WithExtensions(myExt))`. An extension always implements:
+- `RegisterRoutes(r chi.Router, sctx ServerContext)` — adds HTTP routes.
+- `BackgroundWorkers(sctx ServerContext) []func(context.Context)` — starts long-running goroutines.
+
+It can optionally implement any of these hook interfaces (the OSS server type-asserts at startup):
+- `MiddlewareProvider` — `Middlewares(sctx) []func(http.Handler) http.Handler`, applied before OSS routes so cloud middleware can wrap them (e.g. billing gates).
+- `AuthHook` — `OnSignup` (synchronous, error aborts the request with 500 `signup_hook_failed`), `OnLogin`, `OnAccountSoftDelete`, `OnAccountHardDelete` (the last three log + ignore errors). OnSignup fires after team provisioning in both email-activate and OAuth-new-signup paths.
+- `SandboxEventHook` — `OnSandboxEvent(ctx, SandboxEvent)`, invoked from the unified Redis stream consumer for capsule create/pause/resume/destroy success events. Hook errors leave the message un-acked so it will be redelivered; hooks must be idempotent.
+
+`ServerContext` carries the initialized OSS dependencies: `Queries`, `PgPool`, `Redis`, `HostPool`, `Scheduler`, `CA`, `Audit`, `Mailer`, `OAuthRegistry`, `Channels`, `ChannelPub`, `JWTSecret`, `Sessions`, `Config`. To expose a new OSS service to extensions, add it to `ServerContext` in `pkg/cpextension/extension.go` and populate it in `pkg/cpserver/run.go`.
+
+**Auth helpers for extensions** (`pkg/auth/session/middleware/`, re-exported via `cpextension`): `RequireSession(sctx)`, `RequireSessionOrAPIKey(sctx)`, `RequireAdmin(sctx)`, `RequireCSRF()`, `IssueSession(w, r, sctx, userID, teamID)`, `ClearSessionCookies(w, r)`. Cookie/header names are exported as `SessionCookieName`, `CSRFCookieName`, `CSRFHeaderName`. OSS handlers (`internal/api/middleware_session.go`) are thin shims over this package — single source of truth.
+
+**pkg/ vs internal/ decision rule:** A package belongs in `pkg/` only if an external module needs to import it directly — the cloud repo, or standalone consumers of the sandbox runtime (e.g. the `wr` CLI, which embeds the host agent's orchestration packages to run sandboxes without a control plane). Everything else stays in `internal/`. New OSS services (e.g. email, notifications) go in `internal/` — the cloud repo accesses them through `ServerContext`, not by importing the package. Do not put a service in `pkg/` just because the cloud repo uses it.
+
+Startup (`cmd/control-plane/main.go`) is a thin wrapper: `cpserver.Run(cpserver.WithVersion(...))`. All 20 initialization steps live in `pkg/cpserver/run.go`: config → pgxpool → `db.Queries` → Redis → mTLS CA → host client pool → scheduler → OAuth → channels → audit logger → `api.New()` → background workers → HTTP server. Everything flows through constructor injection.
+
+- **API Server** (`internal/api/server.go`): chi router with middleware. Creates handler structs (`sandboxHandler`, `execHandler`, `filesHandler`, etc.) injected with `db.Queries` and the host agent Connect RPC client. Routes under `/v1/capsules/*`. Accepts `[]cpextension.Extension` — each extension's `RegisterRoutes()` is called after all core routes are registered.
+- **Host monitor** (`internal/api/host_monitor.go`): safety-net reconciliation goroutine (every 5min, wired in `pkg/cpserver/run.go` via `NewHostMonitor`). Primary state sync is push-based (host agent callbacks + CP background goroutines); the monitor is the fallback for missed events, host-death detection, and transient-status resolution. For each online host it calls `ListSandboxes()` and reconciles orphaned DB entries.
+- **Dashboard** (SvelteKit + Tailwind + Bits UI, built to static files in `frontend/build/`, served by Caddy as a reverse proxy)
+- **Database**: PostgreSQL via pgx/v5. Queries generated by sqlc from `db/queries/*.sql` → `pkg/db/`. Migrations in `db/migrations/` (goose, plain SQL). `db/migrations/embed.go` exposes `migrations.FS` so the cloud repo can run OSS migrations via `go:embed`.
+- **Config** (`pkg/config/config.go`): purely environment variables (`DATABASE_URL`, `CP_LISTEN_ADDR`, `CP_HOST_AGENT_ADDR`), no YAML/file config.
 
 ### Host Agent
 
-**Packages:** `internal/hostagent/`, `internal/sandbox/`, `internal/vm/`, `internal/network/`, `internal/devicemapper/`, `internal/envdclient/`, `internal/snapshot/`
+**Packages:** `internal/hostagent/` (CP-facing: RPC server, registration, heartbeat, mTLS, proxy), plus the public sandbox runtime importable by external consumers such as the `wr` CLI: `pkg/sandbox/`, `pkg/vm/`, `pkg/network/`, `pkg/devicemapper/`, `pkg/envdclient/`, `pkg/layout/`, `pkg/models/`. `internal/snapshot/` stays internal (only used by `pkg/sandbox`, which may import it intra-module).
 
-Startup (`cmd/host-agent/main.go`) wires: root check → enable IP forwarding → clean up stale dm devices → `sandbox.Manager` (containing `vm.Manager` + `network.SlotAllocator` + `devicemapper.LoopRegistry`) → `hostagent.Server` (Connect RPC handler) → HTTP server.
+**Standalone/library use:** `pkg/sandbox` exposes the full startup ritual (`CheckPrivileges`, `EnsureIPForward`, `Setup(SetupOptions)`) so a CLI can wire a `sandbox.Manager` without the RPC server. A library consumer that re-attaches to sandboxes created by earlier processes must set `SetupOptions.SkipCleanup` — the default stale-cleanup kills every cloud-hypervisor process on the host. Running sandboxes persist re-attach state to `{wrennDir}/sandboxes/{id}/sandbox.json`; `Manager.RestoreRunningSandboxes()` (call before `RestorePausedSandboxes()`) re-attaches live VMs across processes. Network slots are claimed cross-process-safely via O_EXCL files in `{wrennDir}/slots/`.
+
+**Production deployment:** `make setup-host` (→ `scripts/setup-host.sh`) prepares the host: creates the `wrenn` system user, sets Linux capabilities (setcap) on wrenn-agent and all child binaries (iptables, losetup, dmsetup, etc.), installs an apt hook to restore capabilities after package updates, configures udev rules for `/dev/net/tun`, and loads required kernel modules. No sudo grants — all privilege is via capabilities. `make install` then copies the binaries to `/usr/local/bin` and installs the systemd units from `deploy/systemd/`.
+
+Startup (`cmd/host-agent/main.go`) wires: root/capabilities check → enable IP forwarding → clean up stale dm devices → `sandbox.Manager` (containing `vm.Manager` + `network.SlotAllocator` + `devicemapper.LoopRegistry`) → `hostagent.Server` (Connect RPC handler) → HTTP server.
 
 - **RPC Server** (`internal/hostagent/server.go`): implements `hostagentv1connect.HostAgentServiceHandler`. Thin wrapper — every method delegates to `sandbox.Manager`. Maps Connect error codes on return.
-- **Sandbox Manager** (`internal/sandbox/manager.go`): the core orchestration layer. Maintains in-memory state in `boxes map[string]*sandboxState` (protected by `sync.RWMutex`). Each `sandboxState` holds a `models.Sandbox`, a `*network.Slot`, and an `*envdclient.Client`. Runs a TTL reaper (every 10s) that auto-destroys timed-out sandboxes.
-- **VM Manager** (`internal/vm/manager.go`, `fc.go`, `config.go`): manages Firecracker processes. Uses raw HTTP API over Unix socket (`/tmp/fc-{sandboxID}.sock`), not the firecracker-go-sdk Machine type. Launches Firecracker via `unshare -m` + `ip netns exec`. Configures VM via PUT to `/boot-source`, `/drives/rootfs`, `/network-interfaces/eth0`, `/machine-config`, then starts with PUT `/actions`.
-- **Network** (`internal/network/setup.go`, `allocator.go`): per-sandbox network namespace with veth pair + TAP device. See Networking section below.
-- **Device Mapper** (`internal/devicemapper/devicemapper.go`): CoW rootfs via device-mapper snapshots. Shared read-only loop devices per base template (refcounted `LoopRegistry`), per-sandbox sparse CoW files, dm-snapshot create/restore/remove/flatten operations.
-- **envd Client** (`internal/envdclient/client.go`, `health.go`): dual interface to the guest agent. Connect RPC for streaming process exec (`process.Start()` bidirectional stream). Plain HTTP for file operations (POST/GET `/files?path=...&username=root`). Health check polls `GET /health` every 100ms until ready (30s timeout).
+- **Sandbox Manager** (`pkg/sandbox/manager.go`): the core orchestration layer. Maintains in-memory state in `boxes map[string]*sandboxState` (protected by `sync.RWMutex`). Each `sandboxState` holds a `models.Sandbox`, a `*network.Slot`, and an `*envdclient.Client`. Runs a TTL reaper (every 10s) that auto-destroys timed-out sandboxes.
+- **VM Manager** (`pkg/vm/manager.go`, `ch.go`, `config.go`): manages Cloud Hypervisor processes. Uses raw HTTP API over Unix socket (`/tmp/ch-{sandboxID}.sock`). Launches Cloud Hypervisor via `unshare -m` + `ip netns exec` with `--api-socket path=...`. Configures and boots VM via `PUT /vm.create` + `PUT /vm.boot`. Snapshot restore uses `--restore source_url=file://...`. `Reattach()` adopts a still-live CH process started by an earlier process (exit detection via kill-0 polling).
+- **Network** (`pkg/network/setup.go`, `allocator.go`): per-sandbox network namespace with veth pair + TAP device. Slot indices claimed cross-process via O_EXCL files. See Networking section below.
+- **Device Mapper** (`pkg/devicemapper/devicemapper.go`): CoW rootfs via device-mapper snapshots. Shared read-only loop devices per base template (refcounted `LoopRegistry`), per-sandbox sparse CoW files, dm-snapshot create/restore/remove/flatten/reattach operations.
+- **envd Client** (`pkg/envdclient/client.go`, `health.go`): dual interface to the guest agent. Connect RPC for streaming process exec (`process.Start()` bidirectional stream). Plain HTTP for file operations (POST/GET `/files?path=...&username=root`). Health check polls `GET /health` every 100ms until ready (30s timeout).
 
 ### envd (Guest Agent)
 
-**Module:** `envd/` with its own `go.mod` (`git.omukk.dev/wrenn/wrenn/envd`)
+**Directory:** `envd-rs/` — standalone Rust crate
 
-Runs as PID 1 inside the microVM via `wrenn-init.sh` (mounts procfs/sysfs/dev, sets hostname, writes resolv.conf, then execs envd). Extracted from E2B (Apache 2.0), with shared packages internalized into `envd/internal/shared/`. Listens on TCP `0.0.0.0:49983`.
+Runs as PID 1 inside the microVM via `wrenn-init.sh` (mounts procfs/sysfs/dev, sets hostname, writes resolv.conf, then execs envd via tini). Built with `cargo build --release --target x86_64-unknown-linux-musl`. Listens on TCP `0.0.0.0:49983`.
 
-- **ProcessService**: start processes, stream stdout/stderr, signal handling, PTY support
-- **FilesystemService**: stat/list/mkdir/move/remove/watch files
-- **Health**: GET `/health`
+- **Stack**: Tokio (async runtime) + Axum (HTTP) + connectrpc-rs (Connect protocol RPC)
+- **ProcessService** (Connect RPC): start/connect/list/signal processes, stream stdout/stderr, PTY support
+- **FilesystemService** (Connect RPC): stat/list/mkdir/move/remove/watch files
+- **HTTP endpoints**: GET `/health`, GET `/metrics`, POST `/init`, POST `/snapshot/prepare`, GET/POST `/files`
+- **Proto codegen**: `connectrpc-build` compiles `proto/envd/*.proto` at `cargo build` time via `build.rs` — no committed stubs
+- **Build**: `make build-envd` → static musl binary in `builds/envd`
+- **Dev**: `make dev-envd` → `cargo run -- --port 49983`
 
 ### Dashboard (Frontend)
 
 **Directory:** `frontend/` — standalone SvelteKit app (Svelte 5, runes mode)
 
 - **Stack**: SvelteKit + `adapter-static` + Tailwind CSS v4 + Bits UI (headless accessible components)
-- **Package manager**: pnpm
+- **Package manager**: Bun
 - **Routing**: SvelteKit file-based routing under `frontend/src/routes/`
 - **Routing layout**: `/login` and `/signup` at root, authenticated pages under `/dashboard/*` (e.g. `/dashboard/capsules`, `/dashboard/keys`)
-- **Build output**: `frontend/build/` → copied to `internal/dashboard/static/` → embedded via `go:embed` into the control plane binary
-- **Serving**: `internal/dashboard/dashboard.go` registers a `NotFound` catch-all SPA handler with fallback to `index.html`. API routes (`/v1/*`, `/openapi.yaml`, `/docs`) are registered first and take priority
+- **Build output**: `frontend/build/` — static files served by Caddy
+- **Serving**: Caddy reverse-proxies API requests to the control plane and serves the SvelteKit SPA directly. The control plane does not serve frontend assets.
 - **Dev workflow**: `make dev-frontend` runs Vite dev server on port 5173 with HMR. API calls proxy to `http://localhost:8000`
 - **Fonts**: Manrope (UI), Instrument Serif (headings), JetBrains Mono (code), Alice (brand wordmark) — all self-hosted via `@fontsource`
 - **Dark mode**: class-based (`.dark` on `<html>`) with system preference detection + localStorage persistence
@@ -131,7 +158,7 @@ veth-{idx}  ←──── veth pair ────→  eth0
 - **Outbound NAT**: guest (169.254.0.21) → SNAT to vpeerIP inside namespace → MASQUERADE on host to default interface
 - **Inbound NAT**: host traffic to 10.11.0.{idx} → DNAT to 169.254.0.21 inside namespace
 - IP forwarding enabled inside each namespace
-- All details in `internal/network/setup.go`
+- All details in `pkg/network/setup.go`
 
 ### Sandbox State Machine
 ```
@@ -150,7 +177,7 @@ HIBERNATED → RUNNING (cold snapshot resume, slower)
 **Sandbox creation** (`POST /v1/capsules`):
 1. API handler generates sandbox ID, inserts into DB as "pending"
 2. RPC `CreateSandbox` → host agent → `sandbox.Manager.Create()`
-3. Manager: resolve base rootfs → acquire shared loop device → create dm-snapshot (sparse CoW file) → allocate network slot → `CreateNetwork()` (netns + veth + tap + NAT) → `vm.Create()` (start Firecracker with `/dev/mapper/wrenn-{id}`, configure via HTTP API, boot) → `envdclient.WaitUntilReady()` (poll /health) → store in-memory state
+3. Manager: resolve base rootfs → acquire shared loop device → create dm-snapshot (sparse CoW file) → allocate network slot → `CreateNetwork()` (netns + veth + tap + NAT) → `vm.Create()` (start Cloud Hypervisor with `/dev/mapper/wrenn-{id}`, configure via `PUT /vm.create` + `PUT /vm.boot`) → `envdclient.WaitUntilReady()` (poll /health) → store in-memory state
 4. API handler updates DB to "running" with host_ip
 
 **Command execution** (`POST /v1/capsules/{id}/exec`):
@@ -169,129 +196,77 @@ HIBERNATED → RUNNING (cold snapshot resume, slower)
 
 ## REST API
 
-Routes defined in `internal/api/server.go`, handlers in `internal/api/handlers_*.go`. OpenAPI spec embedded via `//go:embed` and served at `/openapi.yaml` (Swagger UI at `/docs`). JSON request/response. API key auth via `X-API-Key` header. Error responses: `{"error": {"code": "...", "message": "..."}}`.
+Routes defined in `internal/api/server.go`, handlers in `internal/api/handlers_*.go`. OpenAPI spec embedded via `//go:embed` and served at `/openapi.yaml` (Swagger UI at `/docs`). JSON request/response. Error responses: `{"error": {"code": "...", "message": "..."}}`.
+
+### Authentication
+
+Two paths, no JWTs for user auth:
+
+- **SDK / server-to-server**: `X-API-Key: wrn_<32hex>` header. Keys are created via the dashboard or `POST /v1/api-keys`, SHA-256-hashed at rest, scoped to a single team. `requireSessionOrAPIKey` middleware accepts this on every capsule lifecycle route.
+- **Browser (dashboard)**: opaque cookie session. `POST /v1/auth/login` (or activate / oauth-callback) sets two cookies — `wrenn_sid` (HttpOnly+Secure+SameSite=Strict) and `wrenn_csrf` (readable by JS, SameSite=Strict). All non-GET requests must echo the CSRF token in an `X-CSRF-Token` header (double-submit). Sessions live in Postgres `sessions` plus a Redis cache (`wrenn:session:{sid}`) — see `pkg/auth/session/`.
+
+Session semantics:
+- **Idle**: 6h. Each request bumps the Redis TTL. Postgres `last_seen_at` is updated on a debounce.
+- **Absolute**: 24h from `created_at` (`expires_at`). Never extended.
+- **Rotation**: `POST /v1/auth/switch-team` issues a fresh SID and re-sets both cookies; old SID revoked.
+- **Revocation**: password change, password add, and password reset all call `RevokeAllForUser`. Self-service is at `GET /v1/me/sessions`, `DELETE /v1/me/sessions/{id}`, `POST /v1/auth/logout`, `POST /v1/auth/logout-all`.
+- **`is_admin` freshness**: the session blob caches it for display, but `requireAdmin` always re-reads Postgres so revoked admins lose access at the next admin request.
+
+Host JWTs (long-lived, signed by `JWT_SECRET`) are unchanged — that is the wrenn-cp ↔ wrenn-agent trust channel and has nothing to do with user auth.
+
+SSE / WebSocket auth: browsers send the `wrenn_sid` cookie automatically on `EventSource` and WS upgrades (same-origin via Caddy); SDKs set `X-API-Key`. No ticket exchange is involved.
 
 ## Code Generation
 
 ### Proto (Connect RPC)
 
-Proto source of truth is `proto/envd/*.proto` and `proto/hostagent/*.proto`. Run `make proto` to regenerate. Three `buf.gen.yaml` files control output:
+Proto source of truth is `proto/envd/*.proto` and `proto/hostagent/*.proto`. Run `make proto` to regenerate Go stubs. Two `buf.gen.yaml` files control Go output:
 
 | buf.gen.yaml location | Generates to | Used by |
 |---|---|---|
 | `proto/envd/buf.gen.yaml` | `proto/envd/gen/` | Main module (host agent's envd client) |
 | `proto/hostagent/buf.gen.yaml` | `proto/hostagent/gen/` | Main module (control plane ↔ host agent) |
-| `envd/spec/buf.gen.yaml` | `envd/internal/services/spec/` | envd module (guest agent server) |
 
-The envd `buf.gen.yaml` reads from `../../proto/envd/` (same source protos) but generates into envd's own module. This means the same `.proto` files produce two independent sets of Go stubs — one for each Go module.
+The Rust envd (`envd-rs/`) generates its own protobuf stubs at `cargo build` time via `connectrpc-build` in `envd-rs/build.rs`, reading from the same `proto/envd/*.proto` sources. No committed Rust stubs — they live in `OUT_DIR`.
 
-To add a new RPC method: edit the `.proto` file → `make proto` → implement the handler on both sides.
+To add a new RPC method: edit the `.proto` file → `make proto` (Go stubs) → rebuild envd-rs (Rust stubs generated automatically) → implement the handler on both sides.
 
 ### sqlc
 
-Config: `sqlc.yaml` (project root). Reads queries from `db/queries/*.sql`, reads schema from `db/migrations/`, outputs to `internal/db/`.
+Config: `sqlc.yaml` (project root). Reads queries from `db/queries/*.sql`, reads schema from `db/migrations/`, outputs to `pkg/db/`.
 
 To add a new query: add it to the appropriate `.sql` file in `db/queries/` → `make generate` → use the new method on `*db.Queries`.
 
 ## Key Technical Decisions
 
 - **Connect RPC** (not gRPC) for all RPC communication between components
-- **Buf + protoc-gen-connect-go** for code generation (not protoc-gen-go-grpc)
-- **Raw Firecracker HTTP API** via Unix socket (not firecracker-go-sdk Machine type)
+- **Buf + protoc-gen-connect-go** for Go code generation; **connectrpc-build** for Rust code generation in envd
+- **Raw Cloud Hypervisor HTTP API** via Unix socket (`PUT /vm.create` + `PUT /vm.boot`)
 - **TAP networking** (not vsock) for host-to-envd communication
-- **Device-mapper snapshots** for rootfs CoW — shared read-only loop device per base template, per-sandbox sparse CoW file, Firecracker gets `/dev/mapper/wrenn-{id}`
+- **Device-mapper snapshots** for rootfs CoW — shared read-only loop device per base template, per-sandbox sparse CoW file, Cloud Hypervisor gets `/dev/mapper/wrenn-{id}`
 - **PostgreSQL** via pgx/v5 + sqlc (type-safe query generation). Goose for migrations (plain SQL, up/down)
-- **Dashboard**: SvelteKit (Svelte 5, adapter-static) + Tailwind CSS v4 + Bits UI. Built to static files, embedded into the Go binary via `go:embed`, served as catch-all at root
+- **Dashboard**: SvelteKit (Svelte 5, adapter-static) + Tailwind CSS v4 + Bits UI. Built to static files in `frontend/build/`, served by Caddy (not embedded in the Go binary)
 - **Lago** for billing (external service, not in this codebase)
 
 ## Coding Conventions
 
 - **Go style**: `gofmt`, `go vet`, `context.Context` everywhere, errors wrapped with `fmt.Errorf("action: %w", err)`, `slog` for logging, no global state
-- **Naming**: Sandbox IDs `sb-` + 8 hex, API keys `wrn_` + 32 chars, Host IDs `host-` + 8 hex
-- **Dependencies**: Use `go get` to add deps, never hand-edit go.mod. For envd deps: `cd envd && go get ...` (separate module)
+- **Naming**: IDs are a type prefix + a 25-char base36-encoded UUID (`pkg/id`) — sandboxes `cl-`, users `usr-`, teams `team-`, hosts `host-`, etc. API keys are `wrn_` + 32 hex
+- **Dependencies**: Use `go get` to add Go deps, never hand-edit go.mod. For envd-rs deps: edit `envd-rs/Cargo.toml`
 - **Generated code**: Always commit generated code (proto stubs, sqlc). Never add generated code to .gitignore
 - **Migrations**: Always use `make migrate-create name=xxx`, never create migration files manually
 - **Testing**: Table-driven tests for handlers and state machine transitions
 
-### Two-module gotcha
-
-The main module (`go.mod`) and envd (`envd/go.mod`) are fully independent. `make tidy`, `make fmt`, `make vet` already operate on both. But when adding dependencies manually, remember to target the correct module (`cd envd && go get ...` for envd deps). `make proto` also generates stubs for both modules from the same proto sources.
-
 ## Rootfs & Guest Init
 
 - **wrenn-init** (`images/wrenn-init.sh`): the PID 1 init script baked into every rootfs. Mounts virtual filesystems, sets hostname, writes `/etc/resolv.conf`, then execs envd.
-- **Updating the rootfs** after changing envd or wrenn-init: `bash scripts/update-debug-rootfs.sh [rootfs_path]`. This builds envd via `make build-envd`, mounts the rootfs image, copies in the new binaries, and unmounts. Defaults to `/var/lib/wrenn/images/minimal.ext4`.
-- Rootfs images are minimal debootstrap — no systemd, no coreutils beyond busybox. Use `/bin/sh -c` for shell builtins inside the guest.
+- **System base templates**: four built-in distro images — `minimal-ubuntu` (id 0, default), `minimal-alpine` (1), `minimal-arch` (2), `minimal-fedora` (3) — built via `images/build-{ubuntu,alpine,arch,fedora}.sh` (or `make images`). All platform-owned, protected from deletion (reserved IDs 0–1024). Same static envd + tini run on all four. Each has a `wrenn-user` with passwordless sudo.
+- **Updating the rootfs** after changing envd or wrenn-init: `bash scripts/update-minimal-rootfs.sh`. Builds envd via `make build-envd` (Rust → static musl binary), then re-injects envd + wrenn-init + tini into all four system base images.
+- Rootfs images are built from distro containers — no systemd (init is overridden to `wrenn-init`). Use `/bin/sh -c` for shell builtins inside the guest.
 
 ## Fixed Paths (on host machine)
 
 - Kernel: `/var/lib/wrenn/kernels/vmlinux`
-- Base rootfs images: `/var/lib/wrenn/images/{template}.ext4`
+- Base rootfs images: `/var/lib/wrenn/images/teams/{base36(teamID)}/{base36(templateID)}/rootfs.ext4` (system templates use the platform team, base36 all-zeros)
 - Sandbox clones: `/var/lib/wrenn/sandboxes/`
-- Firecracker: `/usr/local/bin/firecracker` (e2b's fork of firecracker)
-
-## Design Context
-
-### Users
-Developers across the full spectrum — solo engineers building side projects, startup teams integrating sandboxed execution into products, and platform/infra engineers at larger organizations. The interface must feel at home for all three: approachable enough not to intimidate a hacker, precise enough to earn the trust of a production ops team. Never condescend, never oversimplify. Trust the user to understand what they're looking at.
-
-### Brand Personality
-**Precise. Warm. Uncompromising.**
-
-Wrenn is an engineer's favorite tool — built with visible care, not assembled from defaults. It runs real infrastructure (Firecracker microVMs), so the UI should reflect that seriousness without becoming cold or corporate. The warmth comes from the typography and color palette; the precision comes from hierarchy, density, and data fidelity.
-
-Emotional goal: **in control.** Users leave a session with full confidence in what's running, what happened, and what comes next. Nothing is hidden, nothing is ambiguous.
-
-### Aesthetic Direction
-**Dark-first, industrial-warm, data-forward.**
-
-The near-black-green background palette (`#0a0c0b` through `#2a302d`) reads as "black with intention" — not pitch black (cold) and not charcoal (dated). The sage green accent (`#5e8c58`) is muted and organic, a meaningful departure from the startup-green neon that saturates the developer tool space.
-
-**Anti-references:**
-- **Supabase**: avoid the friendly, approachable startup-green energy — too generic, too eager to please
-- **AWS / GCP consoles**: avoid utility-first density without craft — functional but joyless, visually dated
-
-**References that capture the right spirit:**
-- The precision of a well-calibrated instrument
-- Editorial typography from technical publications
-- The quiet confidence of tools that don't need to explain themselves
-
-### Type System
-Four fonts with strict roles — this is the design system's strongest personality trait and must be respected:
-
-| Font | Role | When to use |
-|------|------|-------------|
-| **Manrope** (variable, sans) | UI workhorse | All body copy, nav, labels, buttons, form text |
-| **Instrument Serif** | Display / editorial | Page titles (h1), dialog headings, metric values, hero moments |
-| **JetBrains Mono** (variable) | Data / code | IDs, timestamps, key prefixes, file paths, terminal output, metrics |
-| **Alice** | Brand wordmark | "Wrenn" in sidebar and login only — nowhere else |
-
-Instrument Serif at scale creates the signature editorial moments. Mono provides the precision signal for technical data. Never swap these roles.
-
-### Color System
-```
-Backgrounds: bg-0 (#0a0c0b) through bg-5 (#2a302d) — 6 steps
-Text:        bright > primary > secondary > tertiary > muted — 5 levels
-Accent:      accent (#5e8c58) / accent-mid / accent-bright / glow / glow-mid
-Status:      amber (#d4a73c) / red (#cf8172) / blue (#5a9fd4)
-```
-
-Use accent sparingly. It should feel earned — reserved for live/active state indicators, primary CTAs, focus rings, and active nav. When accent appears, it should register.
-
-### Upcoming Surfaces (design must accommodate)
-- **Terminal / shell output**: streaming exec output, TTY sessions. Needs strong mono treatment, high contrast for long sessions.
-- **File browser**: filesystem tree inside capsule. Density matters — breadcrumbs, file icons, permission bits.
-- **SDK / docs embedding**: code samples, quickstart flows inline in dashboard. Code blocks must feel premium, not afterthought.
-- **Billing / usage charts**: pool consumption, cost curves, usage over time. Instrument Serif at large scale for metrics; chart containers should feel like instruments, not dashboards.
-
-### Design Principles
-
-1. **Precision over friendliness.** Every element earns its place. Wrenn doesn't need to tell you it's developer-friendly — that should be self-evident from the quality of the information architecture.
-
-2. **Density with breathing room.** Data-forward doesn't mean cramped. Strategic whitespace creates calm hierarchy within dense contexts. Sections breathe; rows don't waste space.
-
-3. **Industrial warmth.** The serif + mono + warm-black combination prevents sterility. This is a forge, not a gallery. The warmth is in the details, not the primary colors.
-
-4. **Legible at speed.** Users scan dashboards in seconds. Strong typographic contrast (serif h1, mono IDs, sans body), consistent patterns, and predictable placement let users orientate instantly without reading everything.
-
-5. **Craft signals trust.** For infrastructure that runs production code, the quality of the UI is a proxy for the quality of the product. Pixel-level decisions matter. Polish is not decoration — it's a trust signal.
+- Cloud Hypervisor: `/usr/local/bin/cloud-hypervisor`

Makefile

@@ -2,8 +2,10 @@
 #  Variables
 # ═══════════════════════════════════════════════════
 DATABASE_URL   ?= postgres://wrenn:wrenn@localhost:5432/wrenn?sslmode=disable
-GOBIN          := $(shell pwd)/builds
-ENVD_DIR       := envd
+BIN_DIR        := $(shell pwd)/builds
+COMMIT         := $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+VERSION_CP     := $(shell cat VERSION_CP 2>/dev/null | tr -d '[:space:]' || echo "0.0.0-dev")
+VERSION_AGENT  := $(shell cat VERSION_AGENT 2>/dev/null | tr -d '[:space:]' || echo "0.0.0-dev")
 LDFLAGS        := -s -w
 
 # ═══════════════════════════════════════════════════
@@ -14,19 +16,23 @@ LDFLAGS        := -s -w
 build: build-cp build-agent build-envd
 
 build-frontend:
-	cd frontend && pnpm install --frozen-lockfile && pnpm build
+	cd frontend && bun install --frozen-lockfile && bun run build
 
 build-cp:
-	go build -v -ldflags="$(LDFLAGS)" -o $(GOBIN)/wrenn-cp ./cmd/control-plane
+	go build -v -ldflags="$(LDFLAGS) -X main.version=$(VERSION_CP) -X main.commit=$(COMMIT)" -o $(BIN_DIR)/wrenn-cp ./cmd/control-plane
 
 build-agent:
-	go build -v -ldflags="$(LDFLAGS)" -o $(GOBIN)/wrenn-agent ./cmd/host-agent
+	go build -v -ldflags="$(LDFLAGS) -X main.version=$(VERSION_AGENT) -X main.commit=$(COMMIT)" -o $(BIN_DIR)/wrenn-agent ./cmd/host-agent
 
 build-envd:
-	cd $(ENVD_DIR) && CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
-		go build -ldflags="$(LDFLAGS)" -o $(GOBIN)/envd .
-	@file $(GOBIN)/envd | grep -q "statically linked" || \
-		(echo "ERROR: envd is not statically linked!" && exit 1)
+	cd envd-rs && ENVD_COMMIT=$(COMMIT) cargo build --release --target x86_64-unknown-linux-musl
+	@cp envd-rs/target/x86_64-unknown-linux-musl/release/envd $(BIN_DIR)/envd
+	@readelf -h $(BIN_DIR)/envd | grep -q 'Type:.*DYN' && \
+	 readelf -d $(BIN_DIR)/envd | grep -q 'FLAGS_1.*PIE' && \
+	 ! readelf -d $(BIN_DIR)/envd | grep -q '(NEEDED)' && \
+	 { ! readelf -lW $(BIN_DIR)/envd | grep -q 'Requesting program interpreter' || \
+	   readelf -lW $(BIN_DIR)/envd | grep -Fq '[Requesting program interpreter: /lib/ld-musl-x86_64.so.1]'; } || \
+		(echo "ERROR: envd must be PIE, have no DT_NEEDED shared libs, and either have no interpreter or use /lib/ld-musl-x86_64.so.1" && exit 1)
 
 # ═══════════════════════════════════════════════════
 #  Development
@@ -53,11 +59,10 @@ dev-agent:
 	sudo go run ./cmd/host-agent
 
 dev-frontend:
-	cd frontend && pnpm dev --port 5173 --host 0.0.0.0
+	cd frontend && bun run dev --port 5173 --host 0.0.0.0
 
 dev-envd:
-	cd $(ENVD_DIR) && go run . --debug --listen-tcp :3002
-
+	cd envd-rs && cargo run -- --port 49983
 
 # ═══════════════════════════════════════════════════
 #  Database (goose)
@@ -90,7 +95,6 @@ generate: proto sqlc
 proto:
 	cd proto/envd && buf generate
 	cd proto/hostagent && buf generate
-	cd $(ENVD_DIR)/spec && buf generate
 
 sqlc:
 	sqlc generate
@@ -102,17 +106,17 @@ sqlc:
 
 fmt:
 	gofmt -w .
-	cd $(ENVD_DIR) && gofmt -w .
+	cargo fmt --manifest-path envd-rs/Cargo.toml
 
 lint:
 	golangci-lint run ./...
 
 vet:
 	go vet ./...
-	cd $(ENVD_DIR) && go vet ./...
 
 test:
-	go test -race -v ./internal/...
+	go test -race -v ./internal/... ./pkg/...
+	cd envd-rs && cargo test
 
 test-integration:
 	go test -race -v -tags=integration ./tests/integration/...
@@ -121,7 +125,6 @@ test-all: test test-integration
 
 tidy:
 	go mod tidy
-	cd $(ENVD_DIR) && go mod tidy
 
 ## Run all quality checks in CI order
 check: fmt vet lint test
@@ -129,32 +132,24 @@ check: fmt vet lint test
 # ═══════════════════════════════════════════════════
 #  Rootfs Images
 # ═══════════════════════════════════════════════════
-.PHONY: images image-minimal image-python image-node
+.PHONY: images rootfs-ubuntu rootfs-alpine rootfs-arch rootfs-fedora
 
-images: build-envd image-minimal image-python image-node
+# Build all four system base rootfs images (ubuntu/alpine/arch/fedora). Each
+# spawns a distro container, installs the required packages + wrenn-user, then
+# exports to images/teams/<platform>/<id>/rootfs.ext4. Requires docker + sudo.
+images: rootfs-ubuntu rootfs-alpine rootfs-arch rootfs-fedora
 
-image-minimal:
-	sudo bash images/templates/minimal/build.sh
+rootfs-ubuntu:
+	bash images/build-ubuntu.sh
 
-image-python:
-	sudo bash images/templates/python312/build.sh
+rootfs-alpine:
+	bash images/build-alpine.sh
 
-image-node:
-	sudo bash images/templates/node20/build.sh
+rootfs-arch:
+	bash images/build-arch.sh
 
-# ═══════════════════════════════════════════════════
-#  Deployment
-# ═══════════════════════════════════════════════════
-.PHONY: setup-host install
-
-setup-host:
-	sudo bash scripts/setup-host.sh
-
-install: build
-	sudo cp $(GOBIN)/wrenn-cp /usr/local/bin/
-	sudo cp $(GOBIN)/wrenn-agent /usr/local/bin/
-	sudo cp deploy/systemd/*.service /etc/systemd/system/
-	sudo systemctl daemon-reload
+rootfs-fedora:
+	bash images/build-fedora.sh
 
 # ═══════════════════════════════════════════════════
 #  Clean
@@ -163,7 +158,7 @@ install: build
 
 clean:
 	rm -rf builds/
-	cd $(ENVD_DIR) && rm -f envd
+	cd envd-rs && cargo clean
 
 # ═══════════════════════════════════════════════════
 #  Help
@@ -179,11 +174,11 @@ help:
 	@echo "  make dev-cp         Control plane (hot reload if air installed)"
 	@echo "  make dev-frontend   Vite dev server with HMR (port 5173)"
 	@echo "  make dev-agent      Host agent (sudo required)"
-	@echo "  make dev-envd       envd in TCP debug mode"
+	@echo "  make dev-envd       envd in debug mode (port 49983)"
 	@echo ""
 	@echo "  make build          Build all binaries → builds/"
 	@echo "  make build-frontend Build SvelteKit dashboard → frontend/build/"
-	@echo "  make build-envd     Build envd static binary"
+	@echo "  make build-envd     Build envd static binary (Rust, musl)"
 	@echo ""
 	@echo "  make migrate-up     Apply migrations"
 	@echo "  make migrate-create name=xxx  New migration"

NOTICE

@@ -1,19 +0,0 @@
-Wrenn Sandbox
-Copyright (c) 2026 M/S Omukk, Bangladesh
-
-This project includes software derived from the following project:
-
-Project: e2b infra
-Repository: https://github.com/e2b-dev/infra
-
-The following files and directories in this repository contain code derived from the above project:
-
-- envd/
-- proto/envd/*.proto
-- internal/snapshot/
-- internal/uffd/
-
-Modifications to this code were made by M/S Omukk.
-
-Copyright (c) 2023 FoundryLabs, Inc.
-Modifications Copyright (c) 2026 M/S Omukk, Bangladesh

PRODUCT.md

@@ -0,0 +1,132 @@
+## Design Context
+
+### Users
+Developers across the full spectrum — solo engineers building side projects, startup teams integrating sandboxed execution into products, and platform/infra engineers at larger organizations running production workloads on Cloud Hypervisor microVMs. They arrive with context: they know what a process is, what a rootfs is, what a TTY means. The interface must feel at home for all three: approachable enough not to intimidate a hacker, precise enough to earn the trust of a production ops team. Never condescend, never oversimplify. Trust the user to understand what they're looking at.
+
+**Primary job to be done:** Understand what's running, act on it confidently, and get back to code.
+
+### Brand Personality
+**Precise. Warm. Uncompromising.**
+
+Wrenn is an engineer's favorite tool — built with visible care, not assembled from defaults. It runs real infrastructure (Cloud Hypervisor microVMs), so the UI should reflect that seriousness without becoming cold or corporate. The warmth comes from the typography and color palette; the precision comes from hierarchy, density, and data fidelity.
+
+Emotional goal: **in control.** Users leave a session with full confidence in what's running, what happened, and what comes next. Nothing is hidden, nothing is ambiguous.
+
+### Aesthetic Direction
+**Dark-only (permanently), industrial-warm, data-forward.**
+
+No light mode planned. All design decisions should optimize for dark. The near-black-green background palette (`#0a0c0b` through `#2a302d`) reads as "black with intention" — not pitch black (cold) and not charcoal (dated). The sage green accent (`#5e8c58`) is muted and organic, a meaningful departure from the startup-green neon that saturates the developer tool space.
+
+**Anti-references:**
+- **Supabase**: avoid the friendly, approachable startup-green energy — too generic, too eager to please
+- **AWS / GCP consoles**: avoid utility-first density without craft — functional but joyless, visually dated
+
+**References that capture the right spirit:**
+- The precision of a well-calibrated instrument
+- Editorial typography from technical publications
+- The quiet confidence of tools that don't need to explain themselves
+
+### Type System
+Four fonts with strict roles — this is the design system's strongest personality trait and must be respected:
+
+| Font | CSS Class | Role | When to use |
+|------|-----------|------|-------------|
+| **Manrope** (variable, sans) | `font-sans` | UI workhorse | All body copy, nav, labels, buttons, form text |
+| **Instrument Serif** | `font-serif` | Display / editorial | Page titles (h1), dialog headings, metric values, hero moments |
+| **JetBrains Mono** (variable) | `font-mono` | Data / code | IDs, timestamps, key prefixes, file paths, terminal output, metrics |
+| **Alice** | brand wordmark only | Brand wordmark | "Wrenn" in sidebar and login only — nowhere else |
+
+Instrument Serif at scale creates the signature editorial moments. Mono provides the precision signal for technical data. Never swap these roles.
+
+**Tracking overrides (app.css):**
+- `.font-serif` — `letter-spacing: 0.015em` (positive tracking; Instrument Serif reads less condensed at display sizes)
+- `.font-mono` — `font-variant-numeric: tabular-nums` (numbers align in tables and metric displays)
+
+**Type scale (root: 87.5% = 14px base):**
+| Token | Value | Use |
+|---|---|---|
+| `--text-display` | 2.571rem (~36px) | Auth section headings |
+| `--text-page` | 2rem (~28px) | Page h1 titles |
+| `--text-heading` | 1.429rem (~20px) | Dialog headings, empty states |
+| `--text-body` | 1rem (~14px) | Primary body, buttons, inputs |
+| `--text-ui` | 0.929rem (~13px) | Nav labels, table cells |
+| `--text-meta` | 0.857rem (~12px) | Key prefixes, minor info |
+| `--text-label` | 0.786rem (~11px) | Uppercase section labels |
+| `--text-badge` | 0.714rem (~10px) | Live badges, tiny indicators |
+
+### Color System
+
+All values are CSS custom properties in `frontend/src/app.css`.
+
+**Backgrounds (6-step near-black-green scale):**
+| Token | Value | Use |
+|---|---|---|
+| `--color-bg-0` | `#0a0c0b` | Page base, sidebar deepest layer |
+| `--color-bg-1` | `#0f1211` | Sidebar surface |
+| `--color-bg-2` | `#141817` | Card backgrounds |
+| `--color-bg-3` | `#1a1e1c` | Table headers, elevated surfaces |
+| `--color-bg-4` | `#212624` | Hover states, inputs |
+| `--color-bg-5` | `#2a302d` | Highlighted items, selected rows |
+
+**Text (5-level hierarchy):**
+| Token | Value | Use |
+|---|---|---|
+| `--color-text-bright` | `#eae7e2` | H1s, dialog headings |
+| `--color-text-primary` | `#d0cdc6` | Body copy, primary labels |
+| `--color-text-secondary` | `#9b9790` | Secondary labels, descriptions |
+| `--color-text-tertiary` | `#6b6862` | Hints, placeholders |
+| `--color-text-muted` | `#454340` | Dividers as text, ultra-subtle |
+
+**Accent (sage green — use sparingly, must feel earned):**
+| Token | Value | Use |
+|---|---|---|
+| `--color-accent` | `#5e8c58` | Primary CTA, live indicators, focus rings, active nav |
+| `--color-accent-mid` | `#89a785` | Hover accent text |
+| `--color-accent-bright` | `#a4c89f` | Accent on dark backgrounds |
+| `--color-accent-glow` | `rgba(94,140,88,0.07)` | Subtle tinted backgrounds |
+| `--color-accent-glow-mid` | `rgba(94,140,88,0.14)` | Hover tint on accent items |
+
+**Status semantics:**
+| Token | Value | Use |
+|---|---|---|
+| `--color-amber` | `#d4a73c` | Warning, paused state |
+| `--color-red` | `#cf8172` | Error, destructive actions |
+| `--color-blue` | `#5a9fd4` | Info, neutral system states |
+
+**Borders:** `--color-border` (`#1f2321`) default; `--color-border-mid` (`#2a2f2c`) for inputs/hover.
+
+### Component Patterns
+
+**Buttons:**
+- Primary: solid sage green (`--color-accent`), hover brightness boost + micro-lift (`-translate-y-px`)
+- Secondary: bordered (`--color-border-mid`), text transitions to accent on hover
+- Danger: red text + subtle red background on hover
+- All: `transition-all duration-150`
+
+**Inputs:**
+- Border `--color-border`, background `--color-bg-2`; focus transitions border and icon to accent
+- Group focus pattern: `group` wrapper + `group-focus-within:text-[var(--color-accent)]` on icon
+
+**Tables / data lists:**
+- Grid layout; header `bg-3` + uppercase `--text-label`; row hover `hover:bg-[var(--color-bg-3)]`
+- Status stripe: left border color matches sandbox state
+
+**Status indicators:** Running = animated ping + sage green dot; Paused = amber dot; Stopped = muted gray. Color is never the sole differentiator.
+
+**Modals & dialogs:** Border + shadow only — no accent gradient bars/strips. `fadeUp` 0.35s entrance.
+
+**Empty states:** Large icon with glow, Instrument Serif heading, secondary body text, CTA below, `iconFloat` 4s animation.
+
+**Animations (always respect `prefers-reduced-motion`):** `fadeUp` (entrance), `status-ping` (live indicator), `iconFloat` (empty states), `spin-once` (refresh), staggered `animation-delay` on lists.
+
+### Design Principles
+
+1. **Precision over friendliness.** Every element earns its place. Wrenn doesn't need to tell you it's developer-friendly — that should be self-evident from the quality of the information architecture.
+
+2. **Density with breathing room.** Data-forward doesn't mean cramped. Strategic whitespace creates calm hierarchy within dense contexts. Sections breathe; rows don't waste space.
+
+3. **Industrial warmth.** The serif + mono + warm-black combination prevents sterility. This is a forge, not a gallery. The warmth is in the details, not the primary colors.
+
+4. **Legible at speed.** Users scan dashboards in seconds. Strong typographic contrast (serif h1, mono IDs, sans body), consistent patterns, and predictable placement let users orientate instantly without reading everything.
+
+5. **Craft signals trust.** For infrastructure that runs production code, the quality of the UI is a proxy for the quality of the product. Pixel-level decisions matter. Polish is not decoration — it's a trust signal.

README.md

@@ -1,17 +1,20 @@
 # Wrenn
 
-Secure infrastructure for AI
+Runtime where AI engineers live
 
-## Deployment
+Wrenn is an open-source platform for running AI coding agents. Each project gets a persistent, isolated microVM workspace — booted in seconds, stateful across sessions — where agents edit code, run tests, debug, and ship continuously while humans supervise via SDKs and chat surfaces. Available hosted or fully self-hosted: run the control plane anywhere, deploy a single agent binary on each compute host you own.
 
-### Prerequisites
+## Prerequisites
 
 - Linux host with `/dev/kvm` access (bare metal or nested virt)
-- Firecracker binary at `/usr/local/bin/firecracker`
+- Cloud Hypervisor binary at `/usr/local/bin/cloud-hypervisor`
 - PostgreSQL
 - Go 1.25+
+- Rust 1.88+ with `x86_64-unknown-linux-musl` target (`rustup target add x86_64-unknown-linux-musl`)
+- Bun (for frontend)
+- Docker (for dev infra and rootfs builds)
 
-### Build
+## Build
 
 ```bash
 make build    # outputs to builds/
@@ -19,30 +22,92 @@ make build    # outputs to builds/
 
 Produces three binaries: `wrenn-cp` (control plane), `wrenn-agent` (host agent), `envd` (guest agent).
 
-### Host setup
+## Host setup
 
-The host agent machine needs:
+The host agent needs a kernel, the system base rootfs images, and working directories on the host machine.
 
-```bash
-# Kernel for guest VMs
-mkdir -p /var/lib/wrenn/kernels
-# Place a vmlinux kernel at /var/lib/wrenn/kernels/vmlinux
+### Directory structure
 
-# Rootfs images
-mkdir -p /var/lib/wrenn/images
-# Build or place .ext4 rootfs images (e.g., minimal.ext4)
-
-# Sandbox working directory
-mkdir -p /var/lib/wrenn/sandboxes
-
-# Snapshots directory
-mkdir -p /var/lib/wrenn/snapshots
-
-# Enable IP forwarding
-sysctl -w net.ipv4.ip_forward=1
+```
+/var/lib/wrenn/
+├── kernels/
+│   └── vmlinux              # uncompressed Linux kernel (not bzImage)
+├── images/
+│   └── teams/
+│       └── 0000000000000000000000000/   # platform team (base36 all-zeros)
+│           ├── 0000000000000000000000000/rootfs.ext4   # minimal-ubuntu (id 0)
+│           ├── 0000000000000000000000001/rootfs.ext4   # minimal-alpine (id 1)
+│           ├── 0000000000000000000000002/rootfs.ext4   # minimal-arch   (id 2)
+│           └── 0000000000000000000000003/rootfs.ext4   # minimal-fedora (id 3)
+├── sandboxes/               # per-sandbox CoW files (created at runtime)
+└── snapshots/               # pause/hibernate snapshot files (created at runtime)
 ```
 
-### Configure
+Create the base directories (the per-template image dirs are created by the build scripts):
+
+```bash
+sudo mkdir -p /var/lib/wrenn/{kernels,images,sandboxes,snapshots}
+```
+
+### Kernel
+
+Place an uncompressed `vmlinux` kernel at `/var/lib/wrenn/kernels/vmlinux`. Versioned kernels (`vmlinux-{semver}`) are also supported — the agent picks the latest by semver.
+
+### System base rootfs images
+
+There are four built-in **system base templates** — one per distro — that all other
+templates snapshot from via device-mapper. They are platform-owned (visible to every
+team) and protected from deletion (reserved template IDs 0–1024):
+
+| Template | Distro | ID |
+|----------|--------|----|
+| `minimal-ubuntu` | `ubuntu:26.04` | 0 |
+| `minimal-alpine` | `alpine:3.22` | 1 |
+| `minimal-arch` | `archlinux:base` | 2 |
+| `minimal-fedora` | `fedora:45` | 3 |
+
+`minimal-ubuntu` is the default template for new sandboxes and builds. The same
+statically-linked `envd` + `tini` run on all four regardless of the distro's libc
+(glibc on Ubuntu/Arch/Fedora, musl on Alpine).
+
+Each image contains these packages plus a `wrenn-user` account with passwordless `sudo`:
+
+| Package | Why |
+|---------|-----|
+| `socat` | Bidirectional relay for port forwarding |
+| `chrony` | Time sync from KVM PTP clock (`/dev/ptp0`) |
+| `iproute2` (`iproute` on Fedora) | `ip` for guest network setup in `wrenn-init` |
+| `tini` | PID 1 zombie reaper |
+| `sudo` | User privilege management inside the guest |
+| `wget` | HTTP fetching |
+| `curl` | HTTP client |
+| `ca-certificates` | TLS certificate verification |
+| `git` | Version control |
+
+**To build all four images** (each spawns a distro container, installs the packages +
+`wrenn-user`, builds `envd`, injects `wrenn-init` + `tini`, and exports to the
+team-scoped path). Requires Docker + sudo:
+
+```bash
+make images
+```
+
+Or build a single distro: `make rootfs-ubuntu` / `rootfs-alpine` / `rootfs-arch` / `rootfs-fedora`.
+
+**To update the images** after changing `envd` or `wrenn-init.sh` (rebuilds `envd` once,
+then re-injects `envd` + `wrenn-init` + `tini` into every system base image):
+
+```bash
+bash scripts/update-minimal-rootfs.sh
+```
+
+### IP forwarding
+
+```bash
+sudo sysctl -w net.ipv4.ip_forward=1
+```
+
+## Configure
 
 Copy `.env.example` to `.env` and edit:
 
@@ -59,71 +124,181 @@ WRENN_HOST_LISTEN_ADDR=:50051
 WRENN_DIR=/var/lib/wrenn
 ```
 
-### Run
-
-```bash
-# Apply database migrations
-make migrate-up
-
-# Start control plane
-./builds/wrenn-cp
-```
-
-Control plane listens on `WRENN_CP_LISTEN_ADDR` (default `:8000`).
-
-### Host registration
-
-Hosts must be registered with the control plane before they can serve sandboxes.
-
-1. **Create a host record** (via API or dashboard):
-   ```bash
-   # As an admin (JWT auth)
-   curl -X POST http://localhost:8000/v1/hosts \
-     -H "Authorization: Bearer $JWT_TOKEN" \
-     -H "Content-Type: application/json" \
-     -d '{"type": "regular"}'
-   ```
-   This returns a `registration_token` (valid for 1 hour).
-
-2. **Start the host agent** with the registration token and its externally-reachable address:
-   ```bash
-   sudo WRENN_CP_URL=http://cp-host:8000 \
-        ./builds/wrenn-agent \
-        --register <token-from-step-1> \
-        --address 10.0.1.5:50051
-   ```
-   On first startup the agent sends its specs (arch, CPU, memory, disk) to the control plane, receives a long-lived host JWT, and saves it to `$WRENN_DIR/host-token`.
-
-3. **Subsequent startups** don't need `--register` — the agent loads the saved JWT automatically:
-   ```bash
-   sudo WRENN_CP_URL=http://cp-host:8000 \
-        ./builds/wrenn-agent --address 10.0.1.5:50051
-   ```
-
-4. **If registration fails** (e.g., network error after token was consumed), regenerate a token:
-   ```bash
-   curl -X POST http://localhost:8000/v1/hosts/$HOST_ID/token \
-     -H "Authorization: Bearer $JWT_TOKEN"
-   ```
-   Then restart the agent with the new token.
-
-The agent sends heartbeats to the control plane every 30 seconds. Host agent listens on `WRENN_HOST_LISTEN_ADDR` (default `:50051`).
-
-### Rootfs images
-
-envd must be baked into every rootfs image. After building:
-
-```bash
-make build-envd
-bash scripts/update-debug-rootfs.sh /var/lib/wrenn/images/minimal.ext4
-```
-
 ## Development
 
 ```bash
 make dev          # Start PostgreSQL (Docker), run migrations, start control plane
 make dev-agent    # Start host agent (separate terminal, sudo)
+make dev-frontend # Vite dev server with HMR (port 5173)
 make check        # fmt + vet + lint + test
 ```
 
+### Host registration
+
+Hosts must be registered with the control plane before they can serve sandboxes.
+
+1. **Create a host record** in the dashboard (admin only — host management is not exposed over the SDK / API keys). Sign in at `/login`, open the admin hosts page, and click **Add host**. The dashboard returns a `registration_token` valid for 1 hour.
+
+2. **Start the host agent** with the registration token and its externally-reachable address:
+   ```bash
+   sudo WRENN_CP_URL=http://localhost:8000 \
+        ./builds/wrenn-agent \
+        --register <token-from-step-1> \
+        --address <host-ip>:50051
+   ```
+   On first startup the agent sends its specs (arch, CPU, memory, disk) to the control plane, receives a long-lived host JWT, and saves it to `$WRENN_DIR/host-token`.
+
+3. **Subsequent startups** don't need `--register` — the agent loads the saved JWT automatically:
+   ```bash
+   sudo ./builds/wrenn-agent --address <host-ip>:50051
+   ```
+
+4. **If registration fails** (e.g., network error after token was consumed), regenerate a token from the dashboard host detail page, then restart the agent with the new token.
+
+The agent sends heartbeats to the control plane every 30 seconds.
+
+## Notification channels
+
+Teams can subscribe to lifecycle events via webhook, Discord, Slack, Teams, Google Chat, Telegram, or Matrix. All providers consume the same event stream (durable Redis stream `wrenn:events`, consumer group `wrenn-channels-v1`, at-least-once delivery with two retries at 10s / 30s).
+
+### Subscribable event types
+
+| Event | Emitted on | Has outcome |
+|-------|-----------|-------------|
+| `capsule.create` | First boot of a sandbox | yes |
+| `capsule.pause` | Manual pause, TTL auto-pause, or reconciler-detected pause | yes |
+| `capsule.resume` | Unpause (any subsequent boot after `capsule.create`) | yes |
+| `capsule.destroy` | Stop / destroy, including system cleanup-on-error | yes |
+| `template.snapshot.create` | Snapshot taken from a running sandbox | yes |
+| `template.snapshot.delete` | Snapshot deletion (including cleanup-on-error) | yes |
+| `host.up` | Host agent comes online | no |
+| `host.down` | Host agent crashes or misses heartbeats | no |
+
+Subscribing to an event type delivers **both success and failure**. The `outcome` field on the payload (`success` or `error`) distinguishes them. `error` events carry an `error` string with the failure reason.
+
+The transient `capsule.state.changed` event (intermediate transitions like `starting`, `pausing`, `resuming`) is **not** subscribable — it is delivered to the dashboard via SSE only and never written to the durable stream.
+
+### Event payload
+
+All channels receive the same canonical JSON shape:
+
+```json
+{
+  "event": "capsule.pause",
+  "outcome": "success",
+  "timestamp": "2026-05-19T14:23:01Z",
+  "team_id": "tm_...",
+  "actor": {
+    "type": "user",
+    "id": "usr_...",
+    "name": "alice@example.com"
+  },
+  "resource": {
+    "id": "sb_a1b2c3d4",
+    "type": "sandbox"
+  },
+  "metadata": {
+    "reason": "ttl_expired"
+  },
+  "error": ""
+}
+```
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `event` | string | Event type (see table above) |
+| `outcome` | `"success"` \| `"error"` \| `""` | Omitted for host.up/host.down |
+| `timestamp` | RFC3339 UTC | When the event was published |
+| `team_id` | string | Owning team |
+| `actor.type` | `"user"` \| `"api_key"` \| `"system"` | System = TTL reaper, reconciler, cleanup-on-error |
+| `actor.id` | string | User ID, API key ID, or empty for system |
+| `actor.name` | string | Display name (email for user, label for api_key) |
+| `resource.id` | string | Sandbox ID, snapshot ID, or host ID |
+| `resource.type` | `"sandbox"` \| `"snapshot"` \| `"host"` | |
+| `metadata` | object\<string,string\> | Event-specific context (e.g., `reason`, `from`/`to`, `inferred`) |
+| `error` | string | Failure reason when `outcome == "error"` |
+
+`metadata` keys you may observe:
+
+- `reason` — `ttl_expired` (auto-pause), `orphaned` (reconciler cleanup), `cleanup_after_create_error`, `restored_after_host_recovery`, `host_state_sync`, `transient_timeout`, `transient_timeout_inferred`
+- `inferred` — `"true"` when the reconciler derived the event from host state, not a direct host callback
+
+### Webhook delivery
+
+Webhook channels receive a raw `POST` with the JSON payload as the body.
+
+Headers:
+
+| Header | Value |
+|--------|-------|
+| `Content-Type` | `application/json` |
+| `X-Wrenn-Delivery` | UUID, unique per delivery attempt |
+| `X-Wrenn-Timestamp` | RFC3339 UTC, used for signature verification |
+| `X-WRENN-SIGNATURE` | `sha256=<hex>` HMAC over `<timestamp>.<body>` using the channel's signing secret |
+
+The signing secret is shown **once** at channel creation. Verify signatures by computing `HMAC-SHA256(secret, timestamp + "." + body)` and comparing to the header (constant-time compare). Reject deliveries where `X-Wrenn-Timestamp` is outside your acceptable clock skew window. Redirects are not followed.
+
+Any non-2xx response triggers retry (10s, then 30s). After three total failures the event is dropped (logged on the control plane).
+
+### Other providers
+
+Discord, Slack, Teams, Google Chat, Telegram, and Matrix receive a formatted text message — the same fields, rendered as human-readable text — not the JSON payload. Use webhook if you need the structured event.
+
+## Extending the control plane
+
+The OSS control plane is designed to be embedded by a private cloud distribution without forking. Import this module, implement the `Extension` interface from `pkg/cpextension`, and pass it to `cpserver.Run`:
+
+```go
+import (
+    "git.omukk.dev/wrenn/wrenn/pkg/cpextension"
+    "git.omukk.dev/wrenn/wrenn/pkg/cpserver"
+)
+
+func main() {
+    cpserver.Run(
+        cpserver.WithVersion("cloud-1.0.0"),
+        cpserver.WithExtensions(&myExtension{}),
+    )
+}
+```
+
+Every extension implements two methods:
+
+```go
+RegisterRoutes(r chi.Router, sctx cpextension.ServerContext)
+BackgroundWorkers(sctx cpextension.ServerContext) []func(context.Context)
+```
+
+`ServerContext` exposes the initialized OSS services so extensions never re-implement them: `Queries`, `PgPool`, `Redis`, `HostPool`, `Scheduler`, `CA`, `Audit`, `Mailer`, `OAuthRegistry`, `Channels`, `ChannelPub`, `JWTSecret`, `Sessions`, `Config`.
+
+### Optional hook interfaces
+
+An extension can also implement any subset of these — the OSS server type-asserts at startup:
+
+| Interface | When it fires | Failure semantics |
+|---|---|---|
+| `MiddlewareProvider` | Wraps every OSS route before registration | n/a |
+| `AuthHook.OnSignup(ctx, userID, teamID, email)` | After team provisioning on email-activate or OAuth-new-signup | Error aborts signup with 500 `signup_hook_failed` (billing customer creation must succeed) |
+| `AuthHook.OnLogin(ctx, userID)` | After a successful login or OAuth callback | Error logged, login still succeeds |
+| `AuthHook.OnAccountSoftDelete(ctx, userID)` | After `DELETE /v1/me` commits | Error logged, request still succeeds |
+| `AuthHook.OnAccountHardDelete(ctx, userID)` | After the 15-day cleanup goroutine purges a soft-deleted account | Error logged, cleanup continues |
+| `SandboxEventHook.OnSandboxEvent(ctx, ev)` | Capsule create/pause/resume/destroy success, from the Redis stream consumer | Error leaves the message un-acked — hooks **must** be idempotent |
+| `LimitsProvider.EffectiveLimits(ctx, teamID)` | `POST /v1/capsules` consults before scheduling | Returns 402 (`concurrent_sandbox_limit` / `vcpu_limit` / `memory_limit`) when over |
+| `UsageProvider.CurrentUsage(ctx, teamID)` | Feeds `LimitsProvider` checks; falls back to OSS DB-backed default | Error → 402 `usage_unavailable` |
+
+### Auth middleware helpers
+
+For extensions that gate their own routes:
+
+```go
+r.With(cpextension.RequireSession(sctx)).Get("/billing", handler)
+r.With(cpextension.RequireSessionOrAPIKey(sctx)).Get("/usage", handler)
+r.With(cpextension.RequireSession(sctx), cpextension.RequireAdmin(sctx)).Get("/admin/exports", handler)
+
+// Issue a session from a custom flow (e.g. invite-accept):
+sess, err := cpextension.IssueSession(w, r, sctx, userID, teamID)
+```
+
+Cookie/header names are exported as `cpextension.SessionCookieName`, `CSRFCookieName`, `CSRFHeaderName`.
+
 See `CLAUDE.md` for full architecture documentation.

VERSION_AGENT

@@ -0,0 +1 @@
+0.5.0

VERSION_CP

@@ -0,0 +1 @@
+0.5.0

cmd/control-plane/main.go

@@ -1,191 +1,15 @@
 package main
 
-import (
-	"context"
-	"log/slog"
-	"net/http"
-	"os"
-	"os/signal"
-	"strings"
-	"syscall"
-	"time"
+import "git.omukk.dev/wrenn/wrenn/pkg/cpserver"
 
-	"github.com/jackc/pgx/v5/pgxpool"
-	"github.com/redis/go-redis/v9"
-
-	"git.omukk.dev/wrenn/wrenn/internal/api"
-	"git.omukk.dev/wrenn/wrenn/internal/audit"
-	"git.omukk.dev/wrenn/wrenn/internal/auth"
-	"git.omukk.dev/wrenn/wrenn/internal/auth/oauth"
-	"git.omukk.dev/wrenn/wrenn/internal/channels"
-	"git.omukk.dev/wrenn/wrenn/internal/config"
-	"git.omukk.dev/wrenn/wrenn/internal/db"
-	"git.omukk.dev/wrenn/wrenn/internal/lifecycle"
-	"git.omukk.dev/wrenn/wrenn/internal/scheduler"
+// Set via -ldflags at build time.
+var (
+	version = "dev"
+	commit  = "unknown"
 )
 
 func main() {
-	slog.SetDefault(slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
-		Level: slog.LevelDebug,
-	})))
-
-	cfg := config.Load()
-
-	if len(cfg.JWTSecret) < 32 {
-		slog.Error("JWT_SECRET must be at least 32 characters")
-		os.Exit(1)
-	}
-
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-
-	// Database connection pool.
-	pool, err := pgxpool.New(ctx, cfg.DatabaseURL)
-	if err != nil {
-		slog.Error("failed to connect to database", "error", err)
-		os.Exit(1)
-	}
-	defer pool.Close()
-
-	if err := pool.Ping(ctx); err != nil {
-		slog.Error("failed to ping database", "error", err)
-		os.Exit(1)
-	}
-	slog.Info("connected to database")
-
-	queries := db.New(pool)
-
-	// Redis client.
-	redisOpts, err := redis.ParseURL(cfg.RedisURL)
-	if err != nil {
-		slog.Error("failed to parse REDIS_URL", "error", err)
-		os.Exit(1)
-	}
-	rdb := redis.NewClient(redisOpts)
-	defer rdb.Close()
-
-	if err := rdb.Ping(ctx).Err(); err != nil {
-		slog.Error("failed to ping redis", "error", err)
-		os.Exit(1)
-	}
-	slog.Info("connected to redis")
-
-	// mTLS is mandatory — parse internal CA for CP↔agent communication.
-	if cfg.CACert == "" || cfg.CAKey == "" {
-		slog.Error("WRENN_CA_CERT and WRENN_CA_KEY are required — mTLS is mandatory for CP↔agent communication")
-		os.Exit(1)
-	}
-	ca, err := auth.ParseCA(cfg.CACert, cfg.CAKey)
-	if err != nil {
-		slog.Error("failed to parse mTLS CA from environment", "error", err)
-		os.Exit(1)
-	}
-	slog.Info("mTLS enabled: CA loaded")
-
-	// Host client pool — manages Connect RPC clients to host agents.
-	cpCertStore, err := auth.NewCPCertStore(ca)
-	if err != nil {
-		slog.Error("failed to issue CP client certificate", "error", err)
-		os.Exit(1)
-	}
-	// Renew the CP client certificate periodically so it never expires
-	// while the control plane is running (TTL = 24h, renewal = every 12h).
-	go func() {
-		ticker := time.NewTicker(auth.CPCertRenewInterval)
-		defer ticker.Stop()
-		for {
-			select {
-			case <-ctx.Done():
-				return
-			case <-ticker.C:
-				if err := cpCertStore.Refresh(); err != nil {
-					slog.Error("failed to renew CP client certificate", "error", err)
-				} else {
-					slog.Info("CP client certificate renewed")
-				}
-			}
-		}
-	}()
-	hostPool := lifecycle.NewHostClientPoolTLS(auth.CPClientTLSConfig(ca, cpCertStore))
-	slog.Info("host client pool: mTLS enabled")
-
-	// Scheduler — picks a host for each new sandbox (least-loaded, bottleneck-first).
-	hostScheduler := scheduler.NewLeastLoadedScheduler(queries)
-
-	// OAuth provider registry.
-	oauthRegistry := oauth.NewRegistry()
-	if cfg.OAuthGitHubClientID != "" && cfg.OAuthGitHubClientSecret != "" {
-		if cfg.CPPublicURL == "" {
-			slog.Error("CP_PUBLIC_URL must be set when OAuth providers are configured")
-			os.Exit(1)
-		}
-		callbackURL := strings.TrimRight(cfg.CPPublicURL, "/") + "/auth/oauth/github/callback"
-		ghProvider := oauth.NewGitHubProvider(cfg.OAuthGitHubClientID, cfg.OAuthGitHubClientSecret, callbackURL)
-		oauthRegistry.Register(ghProvider)
-		slog.Info("registered OAuth provider", "provider", "github")
-	}
-
-	// Channels: publisher, service, dispatcher.
-	if len(cfg.EncryptionKeyHex) != 64 {
-		slog.Error("WRENN_ENCRYPTION_KEY must be a hex-encoded 32-byte key (64 hex chars)")
-		os.Exit(1)
-	}
-	channelPub := channels.NewPublisher(rdb)
-	channelSvc := &channels.Service{DB: queries, EncKey: cfg.EncryptionKey}
-	channelDispatcher := channels.NewDispatcher(rdb, queries, cfg.EncryptionKey)
-
-	// Shared audit logger with event publishing.
-	al := audit.NewWithPublisher(queries, channelPub)
-
-	// API server.
-	srv := api.New(queries, hostPool, hostScheduler, pool, rdb, []byte(cfg.JWTSecret), oauthRegistry, cfg.OAuthRedirectURL, ca, al, channelSvc)
-
-	// Start template build workers (2 concurrent).
-	stopBuildWorkers := srv.BuildSvc.StartWorkers(ctx, 2)
-	defer stopBuildWorkers()
-
-	// Start channel event dispatcher.
-	channelDispatcher.Start(ctx)
-
-	// Start host monitor (passive + active reconciliation every 30s).
-	monitor := api.NewHostMonitor(queries, hostPool, al, 30*time.Second)
-	monitor.Start(ctx)
-
-	// Start metrics sampler (records per-team sandbox stats every 10s).
-	sampler := api.NewMetricsSampler(queries, 10*time.Second)
-	sampler.Start(ctx)
-
-	// Wrap the API handler with the sandbox proxy so that requests with
-	// {port}-{sandbox_id}.{domain} Host headers are routed to the sandbox's
-	// host agent. All other requests pass through to the normal API router.
-	proxyWrapper := api.NewSandboxProxyWrapper(srv.Handler(), queries, hostPool)
-
-	httpServer := &http.Server{
-		Addr:    cfg.ListenAddr,
-		Handler: proxyWrapper,
-	}
-
-	// Graceful shutdown on signal.
-	sigCh := make(chan os.Signal, 1)
-	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
-	go func() {
-		sig := <-sigCh
-		slog.Info("received signal, shutting down", "signal", sig)
-		cancel()
-
-		shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 30*time.Second)
-		defer shutdownCancel()
-
-		if err := httpServer.Shutdown(shutdownCtx); err != nil {
-			slog.Error("http server shutdown error", "error", err)
-		}
-	}()
-
-	slog.Info("control plane starting", "addr", cfg.ListenAddr)
-	if err := httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-		slog.Error("http server error", "error", err)
-		os.Exit(1)
-	}
-
-	slog.Info("control plane stopped")
+	cpserver.Run(
+		cpserver.WithVersion(version, commit),
+	)
 }

cmd/host-agent/main.go

@@ -9,20 +9,28 @@ import (
 	"os"
 	"os/signal"
 	"path/filepath"
+	"strconv"
 	"sync"
 	"syscall"
 	"time"
 
 	"github.com/joho/godotenv"
 
-	"git.omukk.dev/wrenn/wrenn/internal/auth"
-	"git.omukk.dev/wrenn/wrenn/internal/devicemapper"
 	"git.omukk.dev/wrenn/wrenn/internal/hostagent"
-	"git.omukk.dev/wrenn/wrenn/internal/network"
-	"git.omukk.dev/wrenn/wrenn/internal/sandbox"
+	"git.omukk.dev/wrenn/wrenn/internal/units"
+	"git.omukk.dev/wrenn/wrenn/pkg/auth"
+	"git.omukk.dev/wrenn/wrenn/pkg/logging"
+	"git.omukk.dev/wrenn/wrenn/pkg/network"
+	"git.omukk.dev/wrenn/wrenn/pkg/sandbox"
 	"git.omukk.dev/wrenn/wrenn/proto/hostagent/gen/hostagentv1connect"
 )
 
+// Set via -ldflags at build time.
+var (
+	version = "dev"
+	commit  = "unknown"
+)
+
 func main() {
 	// Best-effort load — missing .env file is fine.
 	_ = godotenv.Load()
@@ -31,26 +39,32 @@ func main() {
 	advertiseAddr := flag.String("address", "", "Externally-reachable address (ip:port) for this host agent")
 	flag.Parse()
 
-	slog.SetDefault(slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
-		Level: slog.LevelDebug,
-	})))
+	rootDir := envOrDefault("WRENN_DIR", "/var/lib/wrenn")
+	cleanupLog := logging.Setup(filepath.Join(rootDir, "logs"), "host-agent")
+	defer cleanupLog()
 
-	if os.Geteuid() != 0 {
-		slog.Error("host agent must run as root")
+	if err := sandbox.CheckPrivileges(); err != nil {
+		slog.Error("insufficient privileges", "error", err)
 		os.Exit(1)
 	}
 
-	// Enable IP forwarding (required for NAT).
-	if err := os.WriteFile("/proc/sys/net/ipv4/ip_forward", []byte("1"), 0644); err != nil {
-		slog.Warn("failed to enable ip_forward", "error", err)
+	// Enable IP forwarding (required for NAT). The write may fail if running
+	// as non-root without DAC_OVERRIDE on this path — that's OK if the systemd
+	// unit's ExecStartPre already set it.
+	if err := sandbox.EnsureIPForward(); err != nil {
+		slog.Error("ip_forward is not enabled — sandbox networking will be broken", "error", err)
+		os.Exit(1)
 	}
 
-	// Clean up stale resources from a previous crash.
-	devicemapper.CleanupStaleDevices()
-	network.CleanupStaleNamespaces()
+	// Install the egress guard: block capsule traffic to private ranges from
+	// leaving the public NIC (which would leak private-destined packets onto the
+	// upstream network and read as a port scan) and deny cross-capsule reach.
+	if err := network.EnsureEgressGuard(); err != nil {
+		slog.Error("failed to install network egress guard", "error", err)
+		os.Exit(1)
+	}
 
 	listenAddr := envOrDefault("WRENN_HOST_LISTEN_ADDR", ":50051")
-	rootDir := envOrDefault("WRENN_DIR", "/var/lib/wrenn")
 	cpURL := os.Getenv("WRENN_CP_URL")
 	credsFile := filepath.Join(rootDir, "host-credentials.json")
 
@@ -63,38 +77,12 @@ func main() {
 		os.Exit(1)
 	}
 
-	// Parse default rootfs size from env (e.g. "5G", "2Gi", "1000M").
-	defaultRootfsSizeMB := sandbox.DefaultDiskSizeMB
-	if sizeStr := os.Getenv("WRENN_DEFAULT_ROOTFS_SIZE"); sizeStr != "" {
-		parsed, err := sandbox.ParseSizeToMB(sizeStr)
-		if err != nil {
-			slog.Error("invalid WRENN_DEFAULT_ROOTFS_SIZE", "value", sizeStr, "error", err)
-			os.Exit(1)
-		}
-		defaultRootfsSizeMB = parsed
-		slog.Info("using custom rootfs size", "size_mb", defaultRootfsSizeMB)
-	}
-
-	// Expand base images to the configured disk size (sparse, no extra physical
-	// disk). This ensures dm-snapshot sandboxes see the full size from boot.
-	if err := sandbox.EnsureImageSizes(rootDir, defaultRootfsSizeMB); err != nil {
-		slog.Error("failed to expand base images", "error", err)
-		os.Exit(1)
-	}
-
-	cfg := sandbox.Config{
-		WrennDir:            rootDir,
-		DefaultRootfsSizeMB: defaultRootfsSizeMB,
-	}
-
-	mgr := sandbox.New(cfg)
-
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 
-	mgr.StartTTLReaper(ctx)
-
-	// Register with the control plane and start heartbeating.
+	// Register with the control plane before touching rootfs images. If the
+	// agent can't reach the CP there's no point inflating images (and crashing
+	// afterward would leave them in the expanded state).
 	creds, err := hostagent.Register(ctx, hostagent.RegistrationConfig{
 		CPURL:             cpURL,
 		RegistrationToken: *registrationToken,
@@ -108,8 +96,83 @@ func main() {
 
 	slog.Info("host registered", "host_id", creds.HostID)
 
+	// Parse default rootfs size from env (e.g. "5G", "2Gi", "1000M").
+	defaultRootfsSizeMB := sandbox.DefaultDiskSizeMB
+	if sizeStr := os.Getenv("WRENN_DEFAULT_ROOTFS_SIZE"); sizeStr != "" {
+		parsed, err := units.ParseSizeToMB(sizeStr)
+		if err != nil {
+			slog.Error("invalid WRENN_DEFAULT_ROOTFS_SIZE", "value", sizeStr, "error", err)
+			os.Exit(1)
+		}
+		defaultRootfsSizeMB = parsed
+		slog.Info("using custom rootfs size", "size_mb", defaultRootfsSizeMB)
+	}
+
+	// Run the startup ritual: stale-resource cleanup, base image expansion,
+	// kernel resolution, cloud-hypervisor detection, orphan pause-dir GC.
+	env, err := sandbox.Setup(sandbox.SetupOptions{
+		WrennDir:            rootDir,
+		CHBin:               envOrDefault("WRENN_CH_BIN", sandbox.DefaultCHBin),
+		DefaultRootfsSizeMB: defaultRootfsSizeMB,
+	})
+	if err != nil {
+		slog.Error("host setup failed", "error", err)
+		os.Exit(1)
+	}
+	slog.Info("resolved kernel", "version", env.KernelVersion, "path", env.KernelPath)
+	slog.Info("resolved cloud-hypervisor", "version", env.CHVersion, "path", env.CHBin)
+
+	cfg := sandbox.Config{
+		WrennDir:            rootDir,
+		DefaultRootfsSizeMB: defaultRootfsSizeMB,
+		KernelPath:          env.KernelPath,
+		KernelVersion:       env.KernelVersion,
+		VMMBin:              env.CHBin,
+		VMMVersion:          env.CHVersion,
+		AgentVersion:        version,
+		ProxyDomain:         envOrDefault("WRENN_PROXY_DOMAIN", "wrenn.dev"),
+
+		// Activity sampler tuning (all optional; zero → sandbox package default).
+		ActivitySampleInterval: envDuration("WRENN_ACTIVITY_SAMPLE_INTERVAL"),
+		CPUBusyPct:             envFloat32("WRENN_CPU_BUSY_THRESHOLD"),
+		NetFloorBps:            envUint64("WRENN_NET_FLOOR_BPS"),
+		DiskFloorBps:           envUint64("WRENN_DISK_FLOOR_BPS"),
+	}
+
+	mgr := sandbox.New(cfg)
+
+	// Set up lifecycle event callback sender so autonomous events
+	// (auto-pause, auto-destroy) are pushed to the CP proactively.
+	cb := hostagent.NewCallbackSender(cpURL, credsFile, creds.HostID)
+	mgr.SetEventSender(hostagent.NewEventSender(cb))
+
+	// Sweep stale running-state files first (Setup's stale cleanup killed
+	// every CH process, so nothing can actually be re-attached), then restore
+	// paused sandboxes from disk so ListSandboxes reports them as 'paused'
+	// immediately. Without the latter, the CP's HostMonitor would mark every
+	// paused-on-disk sandbox 'stopped' via the missing→stopped reconcile path
+	// on the first ListSandboxes after agent restart. Must run before the
+	// HTTP server starts serving (an early Create would race the slot
+	// reservation).
+	mgr.RestoreRunningSandboxes()
+	mgr.RestorePausedSandboxes()
+
+	mgr.StartTTLReaper(ctx)
+	mgr.StartActivitySampler(ctx)
+
 	// httpServer is declared here so the shutdown func can reference it.
-	httpServer := &http.Server{Addr: listenAddr}
+	// ReadTimeout/WriteTimeout are intentionally omitted — they would kill
+	// long-lived Connect RPC streams and WebSocket proxy connections.
+	httpServer := &http.Server{
+		Addr:              listenAddr,
+		ReadHeaderTimeout: 10 * time.Second,
+		IdleTimeout:       620 * time.Second, // > typical LB upstream timeout (600s)
+		// Disable HTTP/2: empty non-nil map prevents Go from registering
+		// the h2 ALPN token. Connect RPC works over HTTP/1.1; HTTP/2
+		// multiplexing causes HOL blocking when a slow sandbox RPC stalls
+		// the shared connection.
+		TLSNextProto: make(map[string]func(*http.Server, *tls.Conn, http.Handler)),
+	}
 
 	// mTLS is mandatory — refuse to start without a valid certificate.
 	var certStore hostagent.CertStore
@@ -138,9 +201,22 @@ func main() {
 		shutdownOnce.Do(func() {
 			slog.Info("shutting down", "reason", reason)
 			cancel()
-			shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 30*time.Second)
+			// Shutdown pauses every running sandbox in parallel (PauseAll uses
+			// a worker pool). Per-sandbox Pause can take 10–30s (memory loader
+			// wait + ch.snapshot of guest RAM). 5 minutes is enough headroom for
+			// a busy host while still bounded so a wedged sandbox can't keep the
+			// process alive indefinitely — a second signal force-exits anyway.
+			shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Minute)
 			defer shutdownCancel()
+			// Order matters: mgr.Shutdown FIRST so it runs to completion
+			// before httpServer.Shutdown unblocks main's Serve and lets the
+			// process exit. mgr.Shutdown internally flips a draining flag
+			// that rejects new Create/Resume RPCs with Unavailable so any
+			// in-flight HTTP handlers can't add sandboxes after PauseAll
+			// snapshotted state. User-initiated Pauses already running are
+			// awaited by PauseAll/Destroy's lifecycleMu serialization.
 			mgr.Shutdown(shutdownCtx)
+			sandbox.ShrinkSystemImages(rootDir)
 			if err := httpServer.Shutdown(shutdownCtx); err != nil {
 				slog.Error("http server shutdown error", "error", err)
 			}
@@ -153,6 +229,7 @@ func main() {
 	path, handler := hostagentv1connect.NewHostAgentServiceHandler(srv)
 
 	proxyHandler := hostagent.NewProxyHandler(mgr)
+	mgr.SetOnDestroy(proxyHandler.EvictProxy)
 
 	mux := http.NewServeMux()
 	mux.Handle(path, handler)
@@ -172,8 +249,9 @@ func main() {
 		func() {
 			doShutdown("host deleted from CP")
 		},
-		// onCredsRefreshed: hot-swap the TLS certificate after a JWT refresh.
+		// onCredsRefreshed: hot-swap the TLS certificate and update callback JWT.
 		func(tf *hostagent.TokenFile) {
+			cb.UpdateJWT(tf.JWT)
 			if tf.CertPEM == "" || tf.KeyPEM == "" {
 				return
 			}
@@ -185,15 +263,19 @@ func main() {
 		},
 	)
 
-	// Graceful shutdown on SIGINT/SIGTERM.
+	// Graceful shutdown on SIGINT/SIGTERM. A second signal force-exits
+	// so the operator can always kill the process if shutdown hangs.
 	sigCh := make(chan os.Signal, 1)
 	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
 	go func() {
 		sig := <-sigCh
-		doShutdown("signal: " + sig.String())
+		go doShutdown("signal: " + sig.String())
+		sig = <-sigCh
+		slog.Error("received second signal, force exiting", "signal", sig.String())
+		os.Exit(1)
 	}()
 
-	slog.Info("host agent starting", "addr", listenAddr, "host_id", creds.HostID)
+	slog.Info("host agent starting", "addr", listenAddr, "host_id", creds.HostID, "version", version, "commit", commit)
 	// TLSConfig is always set (mTLS is mandatory). Create the TLS listener
 	// manually because ListenAndServeTLS requires on-disk cert/key paths
 	// but we use GetCertificate callback for hot-swap support.
@@ -216,3 +298,46 @@ func envOrDefault(key, def string) string {
 	}
 	return def
 }
+
+// envDuration parses an optional duration env var (e.g. "5s"). Empty or
+// invalid → zero, letting the sandbox package apply its default.
+func envDuration(key string) time.Duration {
+	v := os.Getenv(key)
+	if v == "" {
+		return 0
+	}
+	d, err := time.ParseDuration(v)
+	if err != nil {
+		slog.Warn("invalid duration env var, using default", "key", key, "value", v)
+		return 0
+	}
+	return d
+}
+
+// envFloat32 parses an optional float env var. Empty or invalid → 0.
+func envFloat32(key string) float32 {
+	v := os.Getenv(key)
+	if v == "" {
+		return 0
+	}
+	f, err := strconv.ParseFloat(v, 32)
+	if err != nil {
+		slog.Warn("invalid float env var, using default", "key", key, "value", v)
+		return 0
+	}
+	return float32(f)
+}
+
+// envUint64 parses an optional unsigned-int env var. Empty or invalid → 0.
+func envUint64(key string) uint64 {
+	v := os.Getenv(key)
+	if v == "" {
+		return 0
+	}
+	n, err := strconv.ParseUint(v, 10, 64)
+	if err != nil {
+		slog.Warn("invalid uint env var, using default", "key", key, "value", v)
+		return 0
+	}
+	return n
+}

db/migrations/20260310094104_initial.sql

@@ -171,7 +171,7 @@ CREATE TABLE audit_logs (
     metadata      JSONB NOT NULL DEFAULT '{}',
     created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
-CREATE INDEX idx_audit_logs_team_time ON audit_logs(team_id, created_at DESC);
+CREATE INDEX idx_audit_logs_team_time ON audit_logs(team_id, created_at DESC, id DESC);
 CREATE INDEX idx_audit_logs_team_resource ON audit_logs(team_id, resource_type, created_at DESC);
 
 -- sandbox_metrics_snapshots

db/migrations/20260412213141_seed_platform_team.sql

@@ -5,8 +5,14 @@
 -- No user can become a member of this team — it exists solely to satisfy
 -- foreign key constraints and to act as a namespace for platform resources.
 INSERT INTO teams (id, name, slug)
-VALUES ('00000000-0000-0000-0000-000000000000', 'Platform', 'platform')
+VALUES ('00000000-0000-0000-0000-000000000000', 'Platform', 'wrenn')
 ON CONFLICT (id) DO NOTHING;
 
 -- +goose Down
+-- Delete dependent rows that reference the platform team via foreign keys.
+-- Order matters: children before parent.
+DELETE FROM sandboxes WHERE team_id = '00000000-0000-0000-0000-000000000000';
+DELETE FROM team_api_keys WHERE team_id = '00000000-0000-0000-0000-000000000000';
+DELETE FROM users_teams WHERE team_id = '00000000-0000-0000-0000-000000000000';
+DELETE FROM hosts WHERE team_id = '00000000-0000-0000-0000-000000000000';
 DELETE FROM teams WHERE id = '00000000-0000-0000-0000-000000000000';

db/migrations/20260415134310_add_metadata.sql

@@ -0,0 +1,9 @@
+-- +goose Up
+ALTER TABLE sandboxes ADD COLUMN metadata JSONB NOT NULL DEFAULT '{}';
+ALTER TABLE templates ADD COLUMN metadata JSONB NOT NULL DEFAULT '{}';
+ALTER TABLE template_builds ADD COLUMN metadata JSONB NOT NULL DEFAULT '{}';
+
+-- +goose Down
+ALTER TABLE sandboxes DROP COLUMN metadata;
+ALTER TABLE templates DROP COLUMN metadata;
+ALTER TABLE template_builds DROP COLUMN metadata;

db/migrations/20260415215033_replace_is_active_with_status.sql

@@ -0,0 +1,15 @@
+-- +goose Up
+ALTER TABLE users ADD COLUMN status TEXT NOT NULL DEFAULT 'active';
+
+-- Backfill from existing columns.
+UPDATE users SET status = 'deleted'  WHERE deleted_at IS NOT NULL;
+UPDATE users SET status = 'disabled' WHERE is_active = false AND deleted_at IS NULL;
+
+ALTER TABLE users DROP COLUMN is_active;
+
+-- +goose Down
+ALTER TABLE users ADD COLUMN is_active BOOLEAN NOT NULL DEFAULT TRUE;
+
+UPDATE users SET is_active = false WHERE status IN ('inactive', 'disabled', 'deleted');
+
+ALTER TABLE users DROP COLUMN status;

db/migrations/20260415221116_cascade_user_delete.sql

@@ -0,0 +1,72 @@
+-- +goose Up
+
+-- users_teams: remove membership when user is deleted
+ALTER TABLE users_teams DROP CONSTRAINT users_teams_user_id_fkey;
+ALTER TABLE users_teams ADD CONSTRAINT users_teams_user_id_fkey
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE;
+
+-- oauth_providers: remove auth links when user is deleted
+ALTER TABLE oauth_providers DROP CONSTRAINT oauth_providers_user_id_fkey;
+ALTER TABLE oauth_providers ADD CONSTRAINT oauth_providers_user_id_fkey
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE;
+
+-- admin_permissions: remove permissions when user is deleted
+ALTER TABLE admin_permissions DROP CONSTRAINT admin_permissions_user_id_fkey;
+ALTER TABLE admin_permissions ADD CONSTRAINT admin_permissions_user_id_fkey
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE;
+
+-- team_api_keys.created_by: make nullable, SET NULL on user delete
+ALTER TABLE team_api_keys ALTER COLUMN created_by DROP NOT NULL;
+ALTER TABLE team_api_keys DROP CONSTRAINT team_api_keys_created_by_fkey;
+ALTER TABLE team_api_keys ADD CONSTRAINT team_api_keys_created_by_fkey
+    FOREIGN KEY (created_by) REFERENCES users(id) ON DELETE SET NULL;
+
+-- hosts.created_by: make nullable, SET NULL on user delete
+ALTER TABLE hosts ALTER COLUMN created_by DROP NOT NULL;
+ALTER TABLE hosts DROP CONSTRAINT hosts_created_by_fkey;
+ALTER TABLE hosts ADD CONSTRAINT hosts_created_by_fkey
+    FOREIGN KEY (created_by) REFERENCES users(id) ON DELETE SET NULL;
+
+-- host_tokens.created_by: make nullable, SET NULL on user delete
+ALTER TABLE host_tokens ALTER COLUMN created_by DROP NOT NULL;
+ALTER TABLE host_tokens DROP CONSTRAINT host_tokens_created_by_fkey;
+ALTER TABLE host_tokens ADD CONSTRAINT host_tokens_created_by_fkey
+    FOREIGN KEY (created_by) REFERENCES users(id) ON DELETE SET NULL;
+
+-- +goose Down
+
+-- Revert host_tokens.created_by
+ALTER TABLE host_tokens DROP CONSTRAINT host_tokens_created_by_fkey;
+UPDATE host_tokens SET created_by = '00000000-0000-0000-0000-000000000000' WHERE created_by IS NULL;
+ALTER TABLE host_tokens ALTER COLUMN created_by SET NOT NULL;
+ALTER TABLE host_tokens ADD CONSTRAINT host_tokens_created_by_fkey
+    FOREIGN KEY (created_by) REFERENCES users(id);
+
+-- Revert hosts.created_by
+ALTER TABLE hosts DROP CONSTRAINT hosts_created_by_fkey;
+UPDATE hosts SET created_by = '00000000-0000-0000-0000-000000000000' WHERE created_by IS NULL;
+ALTER TABLE hosts ALTER COLUMN created_by SET NOT NULL;
+ALTER TABLE hosts ADD CONSTRAINT hosts_created_by_fkey
+    FOREIGN KEY (created_by) REFERENCES users(id);
+
+-- Revert team_api_keys.created_by
+ALTER TABLE team_api_keys DROP CONSTRAINT team_api_keys_created_by_fkey;
+UPDATE team_api_keys SET created_by = '00000000-0000-0000-0000-000000000000' WHERE created_by IS NULL;
+ALTER TABLE team_api_keys ALTER COLUMN created_by SET NOT NULL;
+ALTER TABLE team_api_keys ADD CONSTRAINT team_api_keys_created_by_fkey
+    FOREIGN KEY (created_by) REFERENCES users(id);
+
+-- Revert admin_permissions
+ALTER TABLE admin_permissions DROP CONSTRAINT admin_permissions_user_id_fkey;
+ALTER TABLE admin_permissions ADD CONSTRAINT admin_permissions_user_id_fkey
+    FOREIGN KEY (user_id) REFERENCES users(id);
+
+-- Revert oauth_providers
+ALTER TABLE oauth_providers DROP CONSTRAINT oauth_providers_user_id_fkey;
+ALTER TABLE oauth_providers ADD CONSTRAINT oauth_providers_user_id_fkey
+    FOREIGN KEY (user_id) REFERENCES users(id);
+
+-- Revert users_teams
+ALTER TABLE users_teams DROP CONSTRAINT users_teams_user_id_fkey;
+ALTER TABLE users_teams ADD CONSTRAINT users_teams_user_id_fkey
+    FOREIGN KEY (user_id) REFERENCES users(id);

db/migrations/20260418072009_daily_usage.sql

@@ -0,0 +1,11 @@
+-- +goose Up
+CREATE TABLE daily_usage (
+    team_id        UUID NOT NULL,
+    day            DATE NOT NULL,
+    cpu_minutes    NUMERIC(18, 4) NOT NULL DEFAULT 0,
+    ram_mb_minutes NUMERIC(18, 4) NOT NULL DEFAULT 0,
+    PRIMARY KEY (team_id, day)
+);
+
+-- +goose Down
+DROP TABLE daily_usage;

db/migrations/20260518200117_add_sessions.sql

@@ -0,0 +1,21 @@
+-- +goose Up
+-- +goose StatementBegin
+CREATE TABLE sessions (
+    id            TEXT PRIMARY KEY,
+    user_id       UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    team_id       UUID NOT NULL REFERENCES teams(id) ON DELETE CASCADE,
+    csrf_token    TEXT NOT NULL,
+    user_agent    TEXT NOT NULL DEFAULT '',
+    ip_address    TEXT NOT NULL DEFAULT '',
+    created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    last_seen_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    expires_at    TIMESTAMPTZ NOT NULL
+);
+CREATE INDEX sessions_user_id_idx ON sessions(user_id);
+CREATE INDEX sessions_expires_at_idx ON sessions(expires_at);
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+DROP TABLE IF EXISTS sessions;
+-- +goose StatementEnd

db/migrations/20260519231056_hash_session_ids.sql

@@ -0,0 +1,15 @@
+-- +goose Up
+-- +goose StatementBegin
+-- Session IDs are now stored as sha256(raw_sid) hex so a DB/Redis dump
+-- cannot be replayed as session cookies. Existing sessions hold raw SIDs
+-- in id; they are unrecoverable under the new scheme and must be wiped.
+-- Users will need to log in again after this migration.
+TRUNCATE TABLE sessions;
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+-- Down: nothing to do schematically. Hashed rows remain but will never
+-- match a raw cookie under the old code path; safest is to wipe again.
+TRUNCATE TABLE sessions;
+-- +goose StatementEnd

db/migrations/20260522154716_seed_system_base_templates.sql

@@ -0,0 +1,49 @@
+-- +goose Up
+
+-- Replace the old all-zeros "minimal" base template with the four system base
+-- templates (ubuntu/alpine/arch/fedora). All are platform-owned (team_id
+-- all-zeros) with reserved template IDs 0..3, default user wrenn-user.
+--
+-- Template IDs are well-known: the all-zeros UUID + low byte = {0,1,2,3}.
+-- On disk each lives at images/teams/{base36(0)}/{base36(id)}/rootfs.ext4.
+
+-- 0 → minimal-ubuntu (was "minimal").
+UPDATE templates
+SET name = 'minimal-ubuntu',
+    default_user = 'wrenn-user'
+WHERE id = '00000000-0000-0000-0000-000000000000';
+
+-- Seed the row if it did not already exist (fresh DBs).
+INSERT INTO templates (id, name, type, vcpus, memory_mb, size_bytes, team_id, default_user)
+VALUES ('00000000-0000-0000-0000-000000000000', 'minimal-ubuntu', 'base', 1, 512, 0,
+        '00000000-0000-0000-0000-000000000000', 'wrenn-user')
+ON CONFLICT (id) DO NOTHING;
+
+-- 1 → minimal-alpine, 2 → minimal-arch, 3 → minimal-fedora.
+INSERT INTO templates (id, name, type, vcpus, memory_mb, size_bytes, team_id, default_user)
+VALUES
+    ('00000000-0000-0000-0000-000000000001', 'minimal-alpine', 'base', 1, 512, 0,
+     '00000000-0000-0000-0000-000000000000', 'wrenn-user'),
+    ('00000000-0000-0000-0000-000000000002', 'minimal-arch', 'base', 1, 512, 0,
+     '00000000-0000-0000-0000-000000000000', 'wrenn-user'),
+    ('00000000-0000-0000-0000-000000000003', 'minimal-fedora', 'base', 1, 512, 0,
+     '00000000-0000-0000-0000-000000000000', 'wrenn-user')
+ON CONFLICT (id) DO NOTHING;
+
+-- Point the sandboxes.template column default at the new default base template.
+ALTER TABLE sandboxes ALTER COLUMN template SET DEFAULT 'minimal-ubuntu';
+
+-- +goose Down
+
+ALTER TABLE sandboxes ALTER COLUMN template SET DEFAULT 'minimal';
+
+DELETE FROM templates WHERE id IN (
+    '00000000-0000-0000-0000-000000000001',
+    '00000000-0000-0000-0000-000000000002',
+    '00000000-0000-0000-0000-000000000003'
+);
+
+UPDATE templates
+SET name = 'minimal',
+    default_user = 'root'
+WHERE id = '00000000-0000-0000-0000-000000000000';

db/migrations/20260706122825_bump_default_vcpus_memory.sql

@@ -0,0 +1,25 @@
+-- +goose Up
+
+-- Bump the default sandbox specs from 1 vCPU / 512 MB to 2 vCPUs / 2048 MB.
+-- Applies to any row inserted without explicit vcpus/memory_mb across the
+-- sandboxes, templates, and template_builds tables.
+
+ALTER TABLE sandboxes ALTER COLUMN vcpus SET DEFAULT 2;
+ALTER TABLE sandboxes ALTER COLUMN memory_mb SET DEFAULT 2048;
+
+ALTER TABLE templates ALTER COLUMN vcpus SET DEFAULT 2;
+ALTER TABLE templates ALTER COLUMN memory_mb SET DEFAULT 2048;
+
+ALTER TABLE template_builds ALTER COLUMN vcpus SET DEFAULT 2;
+ALTER TABLE template_builds ALTER COLUMN memory_mb SET DEFAULT 2048;
+
+-- +goose Down
+
+ALTER TABLE sandboxes ALTER COLUMN vcpus SET DEFAULT 1;
+ALTER TABLE sandboxes ALTER COLUMN memory_mb SET DEFAULT 512;
+
+ALTER TABLE templates ALTER COLUMN vcpus SET DEFAULT 1;
+ALTER TABLE templates ALTER COLUMN memory_mb SET DEFAULT 512;
+
+ALTER TABLE template_builds ALTER COLUMN vcpus SET DEFAULT 1;
+ALTER TABLE template_builds ALTER COLUMN memory_mb SET DEFAULT 512;

db/migrations/20260713100416_template_sharing.sql

@@ -0,0 +1,41 @@
+-- +goose Up
+
+-- Templates can be published so teams other than the owner can launch them.
+-- Owners reference foreign public templates as "<team-slug>/<name>".
+ALTER TABLE templates ADD COLUMN is_public BOOLEAN NOT NULL DEFAULT FALSE;
+
+-- Partial index for the templates list page, which unions a team's own
+-- templates with every public template across all teams.
+CREATE INDEX idx_templates_public ON templates(is_public) WHERE is_public;
+
+-- Records the last time a team changed its slug. Used to enforce the 60-day
+-- rename cooldown. NULL means the slug has never been changed (still the
+-- auto-generated one).
+ALTER TABLE teams ADD COLUMN slug_changed_at TIMESTAMPTZ;
+
+-- Tombstone table: when a team changes its slug, the old slug is parked here
+-- for 30 days so nobody else can immediately claim it and start serving
+-- different templates under a name others may still reference. No redirect —
+-- old "<slug>/<name>" references simply fail while the reservation is active
+-- and after it expires (until someone re-registers the slug).
+CREATE TABLE reserved_slugs (
+    slug        TEXT PRIMARY KEY,
+    team_id     UUID NOT NULL,
+    reserved_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    expires_at  TIMESTAMPTZ NOT NULL
+);
+CREATE INDEX idx_reserved_slugs_expires ON reserved_slugs(expires_at);
+
+-- Rebrand the platform team's slug to 'wrenn'. Fresh installs already seed
+-- 'wrenn'; this migrates databases seeded with the old 'platform' slug. Guarded
+-- on the current value so a re-slugged team is never clobbered.
+UPDATE teams SET slug = 'wrenn'
+WHERE id = '00000000-0000-0000-0000-000000000000' AND slug = 'platform';
+
+-- +goose Down
+UPDATE teams SET slug = 'platform'
+WHERE id = '00000000-0000-0000-0000-000000000000' AND slug = 'wrenn';
+DROP TABLE reserved_slugs;
+ALTER TABLE teams DROP COLUMN slug_changed_at;
+DROP INDEX IF EXISTS idx_templates_public;
+ALTER TABLE templates DROP COLUMN is_public;

db/migrations/20260725043541_add_volumes.sql

@@ -0,0 +1,28 @@
+-- +goose Up
+-- External storage volumes: team-scoped block-storage disks that are attached
+-- to a capsule at create time and mounted inside the guest. A volume is
+-- host-local (Cloud Hypervisor can only attach a path on the same host), so it
+-- is pinned to a host the first time it is attached and stays there. Volumes
+-- are never auto-deleted: destroying a capsule frees its volumes back to
+-- 'detached' (data preserved); removal is always an explicit delete.
+CREATE TABLE volumes (
+    id           UUID PRIMARY KEY,
+    team_id      UUID NOT NULL REFERENCES teams(id),
+    host_id      UUID REFERENCES hosts(id),        -- NULL until first attach; pins the volume thereafter
+    name         TEXT NOT NULL,
+    size_mb      INTEGER NOT NULL,
+    status       TEXT NOT NULL DEFAULT 'detached',  -- detached | attaching | attached | deleting
+    sandbox_id   UUID REFERENCES sandboxes(id),     -- set while attaching/attached, cleared on capsule destroy
+    mount_path   TEXT NOT NULL DEFAULT '',          -- guest mount path in use; '' means the default /mnt/<vol-id>
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    last_attached_at TIMESTAMPTZ,
+    last_updated TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE (team_id, name)
+);
+
+CREATE INDEX idx_volumes_team ON volumes(team_id);
+CREATE INDEX idx_volumes_host ON volumes(host_id);
+CREATE INDEX idx_volumes_sandbox ON volumes(sandbox_id) WHERE sandbox_id IS NOT NULL;
+
+-- +goose Down
+DROP TABLE IF EXISTS volumes;

db/migrations/20260725105719_volume_name_prefix.sql

@@ -0,0 +1,41 @@
+-- +goose Up
+-- Volume names are now always "vl-"-prefixed slugs: lowercase alphanumerics in
+-- dash-separated groups, at most 40 characters. The prefix makes a name
+-- self-describing and — since volume IDs use the distinct "vol-" prefix — lets
+-- one API path segment be resolved as either an ID or a name unambiguously.
+--
+-- Backfill the names written before the rule existed. They were validated with
+-- the looser SafeName allowlist, so coerce them into slug shape first
+-- (lowercase, non-slug characters to dashes, collapse and trim dashes) and only
+-- then prefix. A name that survives as empty falls back to the volume's ID,
+-- which is also the default a nameless volume now gets.
+UPDATE volumes
+SET name = LEFT(
+        'vl-' || COALESCE(
+            NULLIF(TRIM(BOTH '-' FROM REGEXP_REPLACE(LOWER(name), '[^a-z0-9]+', '-', 'g')), ''),
+            REPLACE(id::text, '-', '')
+        ),
+        40
+    )
+WHERE name !~ '^vl-[a-z0-9]+(-[a-z0-9]+)*$';
+
+-- The truncation and coercion above can collide two previously-distinct names
+-- within a team, which UNIQUE (team_id, name) would have rejected. Nothing here
+-- can fail silently, so re-assert the invariant: any row still not matching the
+-- rule aborts the migration rather than leaving invalid names behind.
+-- +goose StatementBegin
+DO $$
+BEGIN
+    IF EXISTS (SELECT 1 FROM volumes WHERE name !~ '^vl-[a-z0-9]+(-[a-z0-9]+)*$') THEN
+        RAISE EXCEPTION 'volume name backfill left rows that are not valid vl- slugs';
+    END IF;
+END
+$$;
+-- +goose StatementEnd
+
+-- +goose Down
+-- Strip the prefix back off. The original pre-coercion spelling is not
+-- recoverable, so this restores the shape, not the exact former value.
+UPDATE volumes
+SET name = REGEXP_REPLACE(name, '^vl-', '')
+WHERE name ~ '^vl-';

db/migrations/embed.go

@@ -0,0 +1,10 @@
+// Package migrations embeds the SQL migration files so that external modules
+// (such as the cloud edition) can access them programmatically.
+package migrations
+
+import "embed"
+
+// FS contains all SQL migration files.
+//
+//go:embed *.sql
+var FS embed.FS

db/queries/api_keys.sql

@@ -13,7 +13,7 @@ SELECT * FROM team_api_keys WHERE team_id = $1 ORDER BY created_at DESC;
 SELECT k.id, k.team_id, k.name, k.key_hash, k.key_prefix, k.created_by, k.created_at, k.last_used,
        u.email AS creator_email
 FROM team_api_keys k
-JOIN users u ON u.id = k.created_by
+LEFT JOIN users u ON u.id = k.created_by
 WHERE k.team_id = $1
 ORDER BY k.created_at DESC;
 
@@ -22,3 +22,12 @@ DELETE FROM team_api_keys WHERE id = $1 AND team_id = $2;
 
 -- name: UpdateAPIKeyLastUsed :exec
 UPDATE team_api_keys SET last_used = NOW() WHERE id = $1;
+
+-- name: DeleteAPIKeysByTeam :exec
+DELETE FROM team_api_keys WHERE team_id = $1;
+
+-- name: DeleteAPIKeysByCreator :exec
+DELETE FROM team_api_keys WHERE created_by = $1;
+
+-- name: DeleteAPIKeysByTeamAndCreator :exec
+DELETE FROM team_api_keys WHERE team_id = $1 AND created_by = $2;

db/queries/audit.sql

@@ -2,6 +2,15 @@
 INSERT INTO audit_logs (id, team_id, actor_type, actor_id, actor_name, resource_type, resource_id, action, scope, status, metadata)
 VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11);
 
+-- name: AnonymizeAuditLogsByUserID :exec
+UPDATE audit_logs
+SET actor_name = CASE WHEN actor_id = $1 THEN 'deleted-user' ELSE actor_name END,
+    actor_id   = CASE WHEN actor_id = $1 THEN NULL ELSE actor_id END,
+    resource_id = CASE WHEN resource_type = 'member' AND resource_id = $1 THEN NULL ELSE resource_id END,
+    metadata   = CASE WHEN resource_type = 'member' AND resource_id = $1 AND metadata ? 'email' THEN metadata - 'email' ELSE metadata END
+WHERE actor_id = $1
+   OR (resource_type = 'member' AND resource_id = $1);
+
 -- name: ListAuditLogs :many
 SELECT * FROM audit_logs
 WHERE team_id = $1

db/queries/channels.sql

@@ -22,6 +22,9 @@ RETURNING *;
 -- name: DeleteChannelByTeam :exec
 DELETE FROM channels WHERE id = $1 AND team_id = $2;
 
+-- name: DeleteAllChannelsByTeam :exec
+DELETE FROM channels WHERE team_id = $1;
+
 -- name: ListChannelsForEvent :many
 SELECT * FROM channels
 WHERE team_id = $1

db/queries/hosts.sql

@@ -13,7 +13,36 @@ SELECT * FROM hosts ORDER BY created_at DESC;
 SELECT * FROM hosts WHERE type = $1 ORDER BY created_at DESC;
 
 -- name: ListHostsByTeam :many
-SELECT * FROM hosts WHERE team_id = $1 AND type = 'byoc' ORDER BY created_at DESC;
+-- Returns hosts by team with per-host sandbox resource consumption aggregated.
+-- Follows the same aggregation pattern as ListHostsAdmin and GetHostsWithLoad.
+SELECT
+    h.id,
+    h.type,
+    h.team_id,
+    h.provider,
+    h.availability_zone,
+    h.arch,
+    h.cpu_cores,
+    h.memory_mb,
+    h.disk_gb,
+    h.address,
+    h.status,
+    h.last_heartbeat_at,
+    h.metadata,
+    h.created_by,
+    h.created_at,
+    h.updated_at,
+    COALESCE(SUM(s.vcpus)       FILTER (WHERE s.status IN ('running', 'starting', 'pending')), 0)::int AS running_vcpus,
+    COALESCE(SUM(s.memory_mb)   FILTER (WHERE s.status IN ('running', 'starting', 'pending')), 0)::int AS running_memory_mb,
+    COALESCE(SUM(s.disk_size_mb) FILTER (WHERE s.status IN ('running', 'starting', 'pending')), 0)::int AS running_disk_mb,
+    COALESCE(SUM(s.memory_mb)   FILTER (WHERE s.status = 'paused'), 0)::int AS paused_memory_mb,
+    COALESCE(SUM(s.disk_size_mb) FILTER (WHERE s.status = 'paused'), 0)::int AS paused_disk_mb
+FROM hosts h
+LEFT JOIN sandboxes s ON s.host_id = h.id
+    AND s.status IN ('running', 'paused', 'starting', 'pending')
+WHERE h.team_id = $1 AND h.type = 'byoc'
+GROUP BY h.id
+ORDER BY h.created_at DESC;
 
 -- name: ListHostsByStatus :many
 SELECT * FROM hosts WHERE status = $1 ORDER BY created_at DESC;
@@ -101,8 +130,6 @@ SELECT
     h.created_by,
     h.created_at,
     h.updated_at,
-    h.cert_fingerprint,
-    h.cert_expires_at,
     COALESCE(SUM(s.vcpus)       FILTER (WHERE s.status IN ('running', 'starting', 'pending')), 0)::int AS running_vcpus,
     COALESCE(SUM(s.memory_mb)   FILTER (WHERE s.status IN ('running', 'starting', 'pending')), 0)::int AS running_memory_mb,
     COALESCE(SUM(s.disk_size_mb) FILTER (WHERE s.status IN ('running', 'starting', 'pending')), 0)::int AS running_disk_mb,
@@ -125,5 +152,37 @@ SET last_heartbeat_at = NOW(),
     updated_at        = NOW()
 WHERE id = $1;
 
+-- name: ListHostsAdmin :many
+-- Returns all hosts with per-host sandbox resource consumption aggregated.
+-- Unlike GetHostsWithLoad, this returns ALL hosts (not just online) so admins
+-- can see resource usage across the entire fleet including offline/pending hosts.
+SELECT
+    h.id,
+    h.type,
+    h.team_id,
+    h.provider,
+    h.availability_zone,
+    h.arch,
+    h.cpu_cores,
+    h.memory_mb,
+    h.disk_gb,
+    h.address,
+    h.status,
+    h.last_heartbeat_at,
+    h.metadata,
+    h.created_by,
+    h.created_at,
+    h.updated_at,
+    COALESCE(SUM(s.vcpus)       FILTER (WHERE s.status IN ('running', 'starting', 'pending')), 0)::int AS running_vcpus,
+    COALESCE(SUM(s.memory_mb)   FILTER (WHERE s.status IN ('running', 'starting', 'pending')), 0)::int AS running_memory_mb,
+    COALESCE(SUM(s.disk_size_mb) FILTER (WHERE s.status IN ('running', 'starting', 'pending')), 0)::int AS running_disk_mb,
+    COALESCE(SUM(s.memory_mb)   FILTER (WHERE s.status = 'paused'), 0)::int AS paused_memory_mb,
+    COALESCE(SUM(s.disk_size_mb) FILTER (WHERE s.status = 'paused'), 0)::int AS paused_disk_mb
+FROM hosts h
+LEFT JOIN sandboxes s ON s.host_id = h.id
+    AND s.status IN ('running', 'paused', 'starting', 'pending')
+GROUP BY h.id
+ORDER BY h.created_at DESC;
+
 -- name: MarkHostUnreachable :exec
 UPDATE hosts SET status = 'unreachable', updated_at = NOW() WHERE id = $1;

db/queries/metrics.sql

@@ -42,6 +42,13 @@ ORDER BY ts ASC;
 DELETE FROM sandbox_metric_points
 WHERE sandbox_id = $1;
 
+-- name: GetLatestSandboxMetricPoint :one
+SELECT ts, cpu_pct, mem_bytes, disk_bytes
+FROM sandbox_metric_points
+WHERE sandbox_id = $1
+ORDER BY ts DESC
+LIMIT 1;
+
 -- name: DeleteSandboxMetricPointsByTier :exec
 DELETE FROM sandbox_metric_points
 WHERE sandbox_id = $1 AND tier = $2;
@@ -51,6 +58,13 @@ WHERE sandbox_id = $1 AND tier = $2;
 DELETE FROM sandbox_metric_points
 WHERE ts < EXTRACT(EPOCH FROM NOW() - INTERVAL '30 days')::BIGINT;
 
+-- name: DeleteMetricsSnapshotsByTeam :exec
+DELETE FROM sandbox_metrics_snapshots WHERE team_id = $1;
+
+-- name: DeleteMetricPointsByTeam :exec
+DELETE FROM sandbox_metric_points
+WHERE sandbox_id IN (SELECT id FROM sandboxes WHERE team_id = $1);
+
 -- name: SampleSandboxMetrics :many
 -- Aggregates per-team resource usage from the live sandboxes table.
 -- Groups by all teams that have any sandbox row (including stopped) so that
@@ -66,3 +80,35 @@ SELECT
      + COALESCE(SUM(CEIL(memory_mb::NUMERIC / 2)) FILTER (WHERE status = 'paused'), 0))::INTEGER                     AS memory_mb_reserved
 FROM sandboxes
 GROUP BY team_id;
+
+-- name: GetTeamsWithSnapshots :many
+SELECT DISTINCT team_id
+FROM sandbox_metrics_snapshots
+WHERE sampled_at > NOW() - INTERVAL '93 days';
+
+-- name: ComputeDailyUsageForDay :one
+SELECT
+    COALESCE(SUM(vcpus_reserved     * 10.0 / 60.0), 0)::NUMERIC(18,4) AS cpu_minutes,
+    COALESCE(SUM(memory_mb_reserved * 10.0 / 60.0), 0)::NUMERIC(18,4) AS ram_mb_minutes
+FROM sandbox_metrics_snapshots
+WHERE team_id    = $1
+  AND sampled_at >= $2
+  AND sampled_at <  $3;
+
+-- name: UpsertDailyUsage :exec
+INSERT INTO daily_usage (team_id, day, cpu_minutes, ram_mb_minutes)
+VALUES ($1, $2, $3, $4)
+ON CONFLICT (team_id, day) DO UPDATE
+    SET cpu_minutes    = EXCLUDED.cpu_minutes,
+        ram_mb_minutes = EXCLUDED.ram_mb_minutes;
+
+-- name: GetDailyUsage :many
+SELECT day, cpu_minutes, ram_mb_minutes
+FROM daily_usage
+WHERE team_id = $1
+  AND day >= $2
+  AND day <= $3
+ORDER BY day ASC;
+
+-- name: DeleteDailyUsageByTeam :exec
+DELETE FROM daily_usage WHERE team_id = $1;

db/queries/oauth.sql

@@ -5,3 +5,9 @@ VALUES ($1, $2, $3, $4);
 -- name: GetOAuthProvider :one
 SELECT * FROM oauth_providers
 WHERE provider = $1 AND provider_id = $2;
+
+-- name: GetOAuthProvidersByUserID :many
+SELECT * FROM oauth_providers WHERE user_id = $1;
+
+-- name: DeleteOAuthProvider :exec
+DELETE FROM oauth_providers WHERE user_id = $1 AND provider = $2;

db/queries/sandboxes.sql

@@ -1,6 +1,6 @@
 -- name: InsertSandbox :one
-INSERT INTO sandboxes (id, team_id, host_id, template, status, vcpus, memory_mb, timeout_sec, disk_size_mb, template_id, template_team_id)
-VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
+INSERT INTO sandboxes (id, team_id, host_id, template, status, vcpus, memory_mb, timeout_sec, disk_size_mb, template_id, template_team_id, metadata)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
 RETURNING *;
 
 -- name: GetSandbox :one
@@ -62,7 +62,7 @@ WHERE id = ANY($1::uuid[]);
 
 -- name: ListActiveSandboxesByTeam :many
 SELECT * FROM sandboxes
-WHERE team_id = $1 AND status IN ('running', 'paused', 'starting')
+WHERE team_id = $1 AND status IN ('running', 'paused', 'starting', 'hibernated')
 ORDER BY created_at DESC;
 
 -- name: MarkSandboxesMissingByHost :exec
@@ -72,12 +72,50 @@ ORDER BY created_at DESC;
 UPDATE sandboxes
 SET status       = 'missing',
     last_updated = NOW()
-WHERE host_id = $1 AND status IN ('running', 'starting', 'pending');
+WHERE host_id = $1 AND status IN ('running', 'starting', 'pending', 'pausing', 'resuming', 'stopping');
 
--- name: BulkRestoreRunning :exec
--- Called by the reconciler when a host comes back online and its sandboxes are
--- confirmed alive. Restores only sandboxes that are in 'missing' state.
+-- name: UpdateSandboxMetadata :exec
 UPDATE sandboxes
-SET status       = 'running',
+SET metadata = $2,
+    last_updated = NOW()
+WHERE id = $1;
+
+-- name: UpdateSandboxRunningIf :one
+-- Conditionally transition a sandbox to running only if the current status
+-- matches the expected value. Prevents races where a user destroys a sandbox
+-- while the create/resume goroutine is still in-flight.
+UPDATE sandboxes
+SET status = 'running',
+    host_ip = $3,
+    guest_ip = $4,
+    started_at = $5,
+    last_active_at = $5,
+    last_updated = NOW()
+WHERE id = $1 AND status = $2
+RETURNING *;
+
+-- name: UpdateSandboxStatusIf :one
+-- Atomically update status only when the current status matches the expected value.
+-- Prevents background goroutines from overwriting a status that has since changed
+-- (e.g. user destroyed a sandbox while Create was in-flight).
+UPDATE sandboxes
+SET status       = $3,
+    last_updated = NOW()
+WHERE id = $1 AND status = $2
+RETURNING *;
+
+-- name: BulkRestoreMissingToStatus :exec
+-- Called by the reconciler when a host comes back online and its sandboxes are
+-- confirmed alive. Restores only sandboxes currently in 'missing' state to the
+-- given target status (typically 'running' or 'paused' based on the live state
+-- reported by the host agent's ListSandboxes RPC).
+UPDATE sandboxes
+SET status       = $2,
     last_updated = NOW()
 WHERE id = ANY($1::uuid[]) AND status = 'missing';
+
+-- name: UpdateSandboxDiskSize :exec
+UPDATE sandboxes
+SET disk_size_mb = $2,
+    last_updated = NOW()
+WHERE id = $1;

db/queries/sessions.sql

@@ -0,0 +1,31 @@
+-- name: InsertSession :one
+INSERT INTO sessions (id, user_id, team_id, csrf_token, user_agent, ip_address, expires_at)
+VALUES ($1, $2, $3, $4, $5, $6, $7)
+RETURNING *;
+
+-- name: GetSession :one
+SELECT * FROM sessions WHERE id = $1;
+
+-- name: TouchSession :exec
+UPDATE sessions SET last_seen_at = NOW() WHERE id = $1;
+
+-- name: UpdateSessionTeam :exec
+UPDATE sessions SET team_id = $2 WHERE id = $1;
+
+-- name: DeleteSession :exec
+DELETE FROM sessions WHERE id = $1;
+
+-- name: DeleteSessionForUser :exec
+DELETE FROM sessions WHERE id = $1 AND user_id = $2;
+
+-- name: ListSessionsByUserID :many
+SELECT * FROM sessions WHERE user_id = $1 ORDER BY last_seen_at DESC;
+
+-- name: ListActiveSessionsByUserID :many
+SELECT * FROM sessions WHERE user_id = $1 AND expires_at > NOW() ORDER BY last_seen_at DESC;
+
+-- name: DeleteSessionsByUserID :many
+DELETE FROM sessions WHERE user_id = $1 RETURNING id;
+
+-- name: DeleteExpiredSessions :exec
+DELETE FROM sessions WHERE expires_at < NOW();

db/queries/teams.sql

@@ -34,6 +34,26 @@ UPDATE teams SET deleted_at = NOW() WHERE id = $1;
 -- name: GetTeamBySlug :one
 SELECT * FROM teams WHERE slug = $1 AND deleted_at IS NULL;
 
+-- name: UpdateTeamSlug :exec
+UPDATE teams SET slug = $2, slug_changed_at = NOW() WHERE id = $1 AND deleted_at IS NULL;
+
+-- name: InsertReservedSlug :exec
+-- Park an old slug for 30 days so nobody can immediately claim it after a rename.
+INSERT INTO reserved_slugs (slug, team_id, expires_at)
+VALUES ($1, $2, NOW() + INTERVAL '30 days')
+ON CONFLICT (slug) DO UPDATE
+    SET team_id = EXCLUDED.team_id, reserved_at = NOW(), expires_at = NOW() + INTERVAL '30 days';
+
+-- name: GetActiveReservedSlug :one
+-- Returns a non-expired reservation for the slug, if any.
+SELECT * FROM reserved_slugs WHERE slug = $1 AND expires_at > NOW();
+
+-- name: DeleteReservedSlug :exec
+DELETE FROM reserved_slugs WHERE slug = $1;
+
+-- name: DeleteExpiredReservedSlugs :exec
+DELETE FROM reserved_slugs WHERE expires_at <= NOW();
+
 -- name: GetTeamsForUser :many
 SELECT t.id, t.name, t.slug, t.is_byoc, t.created_at, t.deleted_at, ut.role
 FROM teams t
@@ -66,7 +86,9 @@ SELECT
     COALESCE(owner_u.name, '') AS owner_name,
     COALESCE(owner_u.email, '') AS owner_email,
     (SELECT COUNT(*) FROM sandboxes s WHERE s.team_id = t.id AND s.status IN ('running', 'paused', 'starting'))::int AS active_sandbox_count,
-    (SELECT COUNT(*) FROM channels c WHERE c.team_id = t.id)::int AS channel_count
+    (SELECT COUNT(*) FROM channels c WHERE c.team_id = t.id)::int AS channel_count,
+    COALESCE((SELECT SUM(s.vcpus) FROM sandboxes s WHERE s.team_id = t.id AND s.status IN ('running', 'paused', 'starting')), 0)::int AS running_vcpus,
+    COALESCE((SELECT SUM(s.memory_mb) FROM sandboxes s WHERE s.team_id = t.id AND s.status IN ('running', 'paused', 'starting')), 0)::int AS running_memory_mb
 FROM teams t
 LEFT JOIN users_teams owner_ut ON owner_ut.team_id = t.id AND owner_ut.role = 'owner'
 LEFT JOIN users owner_u ON owner_u.id = owner_ut.user_id
@@ -74,6 +96,26 @@ WHERE t.id != '00000000-0000-0000-0000-000000000000'
 ORDER BY t.deleted_at ASC NULLS FIRST, t.created_at DESC
 LIMIT $1 OFFSET $2;
 
+-- name: ListSoleOwnedTeams :many
+-- Returns teams where the user is the owner and no other members exist.
+SELECT t.id FROM teams t
+JOIN users_teams ut ON ut.team_id = t.id
+WHERE ut.user_id = $1
+  AND ut.role = 'owner'
+  AND t.deleted_at IS NULL
+  AND NOT EXISTS (
+      SELECT 1 FROM users_teams ut2
+      WHERE ut2.team_id = t.id AND ut2.user_id <> $1
+  );
+
+-- name: GetOwnedTeamIDs :many
+-- Returns team IDs where the given user has the 'owner' role.
+SELECT t.id FROM teams t
+JOIN users_teams ut ON ut.team_id = t.id
+WHERE ut.user_id = $1
+  AND ut.role = 'owner'
+  AND t.deleted_at IS NULL;
+
 -- name: CountTeamsAdmin :one
 SELECT COUNT(*)::int AS total
 FROM teams

db/queries/template_builds.sql

@@ -34,5 +34,5 @@ WHERE id = $1;
 
 -- name: UpdateBuildDefaults :exec
 UPDATE template_builds
-SET default_user = $2, default_env = $3
+SET default_user = $2, default_env = $3, metadata = $4
 WHERE id = $1;

db/queries/templates.sql

@@ -1,19 +1,71 @@
 -- name: InsertTemplate :one
-INSERT INTO templates (id, name, type, vcpus, memory_mb, size_bytes, team_id, default_user, default_env)
-VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+INSERT INTO templates (id, name, type, vcpus, memory_mb, size_bytes, team_id, default_user, default_env, metadata)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
 RETURNING *;
 
 -- name: GetTemplate :one
 SELECT * FROM templates WHERE id = $1;
 
 -- name: GetTemplateByTeam :one
--- Platform templates (team_id = 00000000-...) are visible to all teams.
-SELECT * FROM templates WHERE name = $1 AND (team_id = $2 OR team_id = '00000000-0000-0000-0000-000000000000');
+-- Platform templates (team_id = 00000000-...) are visible to all teams. When a
+-- team owns a template whose name also matches a platform template, prefer the
+-- team's own row so mutation guards act on the caller's template, not the
+-- shared platform one.
+SELECT * FROM templates
+WHERE name = $1 AND (team_id = $2 OR team_id = '00000000-0000-0000-0000-000000000000')
+ORDER BY (team_id = $2) DESC
+LIMIT 1;
 
 -- name: GetTemplateByName :one
 -- Look up a template by team_id and name (exact team match, no global fallback).
 SELECT * FROM templates WHERE team_id = $1 AND name = $2;
 
+-- name: ResolveTemplateForTeam :one
+-- Unqualified reference resolution: prefer the requesting team's own template,
+-- then fall back to a platform template of the same name.
+SELECT * FROM templates
+WHERE name = $1 AND (team_id = $2 OR team_id = '00000000-0000-0000-0000-000000000000')
+ORDER BY (team_id = $2) DESC
+LIMIT 1;
+
+-- name: GetVisibleTemplateByTeamName :one
+-- Slug-qualified reference resolution: the template must belong to the named
+-- owning team ($1) and be visible to the requester ($3) — public, owned by the
+-- requester, or a platform template.
+SELECT * FROM templates
+WHERE team_id = $1 AND name = $2
+  AND (is_public = TRUE OR team_id = $3 OR team_id = '00000000-0000-0000-0000-000000000000');
+
+-- name: SetTemplateVisibility :one
+-- Publish or unpublish a template the team owns. Returns the updated row (or no
+-- rows if the team does not own a template of that name).
+UPDATE templates SET is_public = $3
+WHERE team_id = $1 AND name = $2
+RETURNING *;
+
+-- name: ListVisibleTemplates :many
+-- Templates the team may launch: its own, platform, and every public template.
+-- $2 = type filter ('' = any), $3 = search over name/slug ('' = no search).
+SELECT t.*, tm.slug AS team_slug
+FROM templates t
+JOIN teams tm ON tm.id = t.team_id
+WHERE (t.team_id = @team_id OR t.team_id = '00000000-0000-0000-0000-000000000000' OR t.is_public = TRUE)
+  AND (@type_filter::text = '' OR t.type = @type_filter::text)
+  AND (@search::text = '' OR t.name ILIKE '%' || @search::text || '%' OR tm.slug ILIKE '%' || @search::text || '%')
+ORDER BY
+  (t.team_id = @team_id) DESC,
+  (t.team_id = '00000000-0000-0000-0000-000000000000') DESC,
+  t.created_at DESC
+LIMIT @row_limit OFFSET @row_offset;
+
+-- name: CountVisibleTemplates :one
+SELECT COUNT(*)::int AS total
+FROM templates t
+JOIN teams tm ON tm.id = t.team_id
+WHERE (t.team_id = @team_id OR t.team_id = '00000000-0000-0000-0000-000000000000' OR t.is_public = TRUE)
+  AND (@type_filter::text = '' OR t.type = @type_filter::text)
+  AND (@search::text = '' OR t.name ILIKE '%' || @search::text || '%' OR tm.slug ILIKE '%' || @search::text || '%');
+
 -- name: GetPlatformTemplateByName :one
 -- Check if a global (platform) template exists with the given name.
 SELECT * FROM templates WHERE team_id = '00000000-0000-0000-0000-000000000000' AND name = $1;
@@ -42,6 +94,19 @@ DELETE FROM templates WHERE name = $1 AND team_id = $2;
 -- Bulk delete all templates owned by a team (for team soft-delete cleanup).
 DELETE FROM templates WHERE team_id = $1;
 
+-- name: UpdateTemplateSize :exec
+UPDATE templates SET size_bytes = $2 WHERE id = $1;
+
+-- name: RenameTemplate :one
+-- Rename a template by ID. Clears the published flag so stale
+-- "<team-slug>/<name>" references from other teams break loudly rather than
+-- silently resolving to a different template. Callers apply ownership and
+-- protection guards before calling. A name collision (team-scoped uniqueness or
+-- the global-template-name trigger) surfaces as a unique_violation.
+UPDATE templates SET name = @new_name, is_public = FALSE
+WHERE id = @id
+RETURNING *;
+
 -- name: ListTemplatesByTeamOnly :many
 -- List templates owned by a specific team (NOT including platform templates).
 SELECT * FROM templates WHERE team_id = $1 ORDER BY created_at DESC;

db/queries/users.sql

@@ -4,19 +4,30 @@ VALUES ($1, $2, $3, $4)
 RETURNING *;
 
 -- name: GetUserByEmail :one
-SELECT * FROM users WHERE email = $1;
+SELECT * FROM users WHERE email = $1 AND status != 'deleted';
 
 -- name: GetUserByID :one
-SELECT * FROM users WHERE id = $1;
+SELECT * FROM users WHERE id = $1 AND status != 'deleted';
 
 -- name: InsertUserOAuth :one
 INSERT INTO users (id, email, name)
 VALUES ($1, $2, $3)
 RETURNING *;
 
+-- name: InsertUserInactive :one
+INSERT INTO users (id, email, password_hash, name, status)
+VALUES ($1, $2, $3, $4, 'inactive')
+RETURNING *;
+
 -- name: SetUserAdmin :exec
 UPDATE users SET is_admin = $2, updated_at = NOW() WHERE id = $1;
 
+-- name: RevokeUserAdmin :execrows
+UPDATE users u SET is_admin = false, updated_at = NOW()
+WHERE u.id = $1
+  AND u.is_admin = true
+  AND (SELECT COUNT(*) FROM users WHERE is_admin = true AND status != 'deleted') > 1;
+
 -- name: GetAdminUsers :many
 SELECT * FROM users WHERE is_admin = TRUE ORDER BY created_at;
 
@@ -38,6 +49,9 @@ SELECT EXISTS(
 -- name: CountUsers :one
 SELECT COUNT(*) FROM users;
 
+-- name: CountActiveUsers :one
+SELECT COUNT(*) FROM users WHERE status = 'active';
+
 -- name: SearchUsersByEmailPrefix :many
 SELECT id, email FROM users WHERE email LIKE $1 || '%' ORDER BY email LIMIT 10;
 
@@ -50,19 +64,41 @@ SELECT
     u.email,
     u.name,
     u.is_admin,
-    u.is_active,
+    u.status,
     u.created_at,
     (SELECT COUNT(*) FROM users_teams ut WHERE ut.user_id = u.id)::int AS teams_joined,
     (SELECT COUNT(*) FROM users_teams ut WHERE ut.user_id = u.id AND ut.role = 'owner')::int AS teams_owned
 FROM users u
-WHERE u.deleted_at IS NULL
+WHERE u.status != 'deleted'
 ORDER BY u.created_at DESC
 LIMIT $1 OFFSET $2;
 
 -- name: CountUsersAdmin :one
 SELECT COUNT(*)::int AS total
 FROM users
-WHERE deleted_at IS NULL;
+WHERE status != 'deleted';
 
--- name: SetUserActive :exec
-UPDATE users SET is_active = $2, updated_at = NOW() WHERE id = $1;
+-- name: SetUserStatus :exec
+UPDATE users SET status = $2, updated_at = NOW() WHERE id = $1;
+
+-- name: UpdateUserPassword :exec
+UPDATE users SET password_hash = $2, updated_at = NOW() WHERE id = $1;
+
+-- name: SoftDeleteUser :exec
+UPDATE users SET deleted_at = NOW(), status = 'deleted', updated_at = NOW() WHERE id = $1;
+
+-- name: CountUserOwnedTeamsWithOtherMembers :one
+SELECT COUNT(DISTINCT ut.team_id)::int
+FROM users_teams ut
+WHERE ut.user_id = $1
+  AND ut.role = 'owner'
+  AND EXISTS (
+      SELECT 1 FROM users_teams ut2
+      WHERE ut2.team_id = ut.team_id AND ut2.user_id <> $1
+  );
+
+-- name: ListExpiredSoftDeletedUsers :many
+SELECT id, email FROM users WHERE deleted_at IS NOT NULL AND deleted_at < NOW() - INTERVAL '15 days';
+
+-- name: HardDeleteUser :exec
+DELETE FROM users WHERE id = $1;

db/queries/volumes.sql

@@ -0,0 +1,178 @@
+-- name: InsertVolume :one
+INSERT INTO volumes (id, team_id, name, size_mb, status)
+VALUES ($1, $2, $3, $4, 'detached')
+RETURNING *;
+
+-- name: GetVolume :one
+SELECT * FROM volumes WHERE id = $1;
+
+-- name: GetVolumeByTeam :one
+SELECT * FROM volumes WHERE id = $1 AND team_id = $2;
+
+-- name: GetVolumeByTeamAndName :one
+-- Resolve a volume by its user-facing name. Names are unique per team, so this
+-- is the name-based counterpart to GetVolumeByTeam and is what lets the API
+-- accept "vl-cache" wherever it accepts "vol-<id>".
+SELECT * FROM volumes WHERE team_id = $1 AND name = $2;
+
+-- name: ListVolumesByTeam :many
+SELECT * FROM volumes WHERE team_id = $1 ORDER BY created_at DESC;
+
+-- name: ListVolumesBySandbox :many
+SELECT * FROM volumes WHERE sandbox_id = $1 ORDER BY created_at DESC;
+
+-- name: CountVolumesByHost :one
+-- Guard used before a host can be removed: a host holding pinned volumes must
+-- not be deleted out from under them.
+SELECT COUNT(*) FROM volumes WHERE host_id = $1;
+
+-- name: ReserveVolumeForAttach :one
+-- Atomically claim a detached volume for a capsule about to boot. The CAS on
+-- status = 'detached' enforces single-attach: a second capsule create racing
+-- for the same volume finds no row and fails. sandbox_id is deliberately NOT
+-- set here — the sandbox row does not exist yet, so setting the FK would fail.
+-- It is set in MarkVolumeAttached once the capsule has booted.
+UPDATE volumes
+SET status       = 'attaching',
+    last_updated = NOW()
+WHERE id = $1 AND status = 'detached'
+RETURNING *;
+
+-- name: MarkVolumeAttached :one
+-- Promote a reserved volume to attached once the capsule has booted with it.
+-- Records the owning sandbox and pins the volume to the sandbox's host on
+-- first-ever attach (COALESCE keeps an existing pin for a re-attached volume).
+UPDATE volumes
+SET status           = 'attached',
+    host_id          = COALESCE(host_id, $2),
+    sandbox_id       = $3,
+    mount_path       = $4,
+    last_attached_at = NOW(),
+    last_updated     = NOW()
+WHERE id = $1 AND status = 'attaching'
+RETURNING *;
+
+-- name: LinkVolumeReservation :exec
+-- Stamp the owning sandbox onto a reservation as soon as the sandbox row
+-- exists (ReserveVolumeForAttach runs before the insert, so it cannot set the
+-- FK itself). This makes every in-flight reservation attributable to a capsule,
+-- which is what lets the host monitor decide — against live host state —
+-- whether a stuck 'attaching' row is safe to free.
+UPDATE volumes
+SET sandbox_id   = $2,
+    last_updated = NOW()
+WHERE id = $1 AND status = 'attaching';
+
+-- name: ReleaseVolumeReservation :exec
+-- Roll a reserved volume back to detached when the capsule create fails.
+-- host_id is left untouched (a failed create never pins a fresh volume, since
+-- MarkVolumeAttached is what sets the pin). Only call this once the host has
+-- confirmed the capsule is not running — a volume freed while a VM still has
+-- its backing file open can be re-attached elsewhere and corrupted.
+UPDATE volumes
+SET status       = 'detached',
+    sandbox_id   = NULL,
+    last_updated = NOW()
+WHERE id = $1 AND status = 'attaching';
+
+-- name: DetachVolumesBySandbox :exec
+-- Terminal sweep run when a capsule reaches a terminal state (destroyed,
+-- stopped, errored, or reaped): free every volume it held back to detached
+-- (data and host pin preserved) so it can be reused or deleted. Keyed on
+-- sandbox_id, which is stamped on at reservation time. Never deletes the
+-- volume — removal is always explicit.
+--
+-- 'attaching' is swept alongside 'attached' so a reservation whose promotion
+-- never landed (lost RPC response, DB blip) is freed here — on confirmed host
+-- state — rather than on a blind timer.
+UPDATE volumes
+SET status       = 'detached',
+    sandbox_id   = NULL,
+    mount_path   = '',
+    last_updated = NOW()
+WHERE sandbox_id = $1 AND status IN ('attached', 'attaching');
+
+-- name: DetachVolumesBySandboxIDs :exec
+-- Bulk variant of DetachVolumesBySandbox for the host monitor, which stops
+-- many sandboxes at once (e.g. after a host goes offline).
+UPDATE volumes
+SET status       = 'detached',
+    sandbox_id   = NULL,
+    mount_path   = '',
+    last_updated = NOW()
+WHERE sandbox_id = ANY($1::uuid[]) AND status IN ('attached', 'attaching');
+
+-- name: DetachVolumesByHost :exec
+-- Free and un-pin every volume on a host being force-deleted. The host (and its
+-- backing files) are going away, so the volumes are reset to a fresh detached,
+-- un-pinned state — the rows survive (never auto-deleted) and can be re-attached
+-- on a new host. Also required before DeleteHost so the host_id FK does not
+-- block deletion.
+UPDATE volumes
+SET status       = 'detached',
+    sandbox_id   = NULL,
+    host_id      = NULL,
+    mount_path   = '',
+    last_updated = NOW()
+WHERE host_id = $1;
+
+-- name: BeginVolumeDelete :one
+-- Atomically claim a volume for deletion. The CAS blocks a concurrent attach
+-- (which needs status='detached') so a volume can never be attached and deleted
+-- at the same time. 'deleting' is also accepted so a delete that crashed
+-- mid-flight can be retried rather than leaving the volume permanently stuck.
+-- Returns the row (for host_id) when claimed; no row means it is not deletable
+-- (attached/attaching, wrong team, or missing).
+UPDATE volumes
+SET status       = 'deleting',
+    last_updated = NOW()
+WHERE id = $1 AND team_id = $2 AND status IN ('detached', 'deleting')
+RETURNING *;
+
+-- name: AbortVolumeDelete :exec
+-- Revert a delete claim back to detached when the host-side file removal fails,
+-- so the volume stays usable rather than stuck in 'deleting'.
+UPDATE volumes
+SET status       = 'detached',
+    last_updated = NOW()
+WHERE id = $1 AND status = 'deleting';
+
+-- name: ReleaseStaleVolumeReservations :execrows
+-- Free volumes stuck in a transient state whose owning operation died before it
+-- could ever reach a host — the control plane crashed between reserving a
+-- volume and inserting the sandbox row, or mid-delete. Run periodically by the
+-- volume reaper.
+--
+-- Deliberately limited to unattributed rows (sandbox_id IS NULL). A reservation
+-- that already carries a sandbox_id may correspond to a capsule that really did
+-- boot with the volume mounted — and a timer cannot tell the difference. Those
+-- are freed only by the host-monitor sweep, which first confirms against the
+-- host that the capsule is gone. Freeing a live volume here would let a second
+-- capsule attach the same backing file and corrupt it.
+--
+-- The cutoff ($1 = now - grace) MUST exceed the capsule create timeout so a
+-- legitimately in-flight attach is never freed out from under a booting capsule.
+UPDATE volumes
+SET status       = 'detached',
+    mount_path   = '',
+    last_updated = NOW()
+WHERE status IN ('attaching', 'deleting')
+  AND sandbox_id IS NULL
+  AND last_updated < $1;
+
+-- name: DeleteVolumeRow :exec
+-- Drop the row only while the delete claim still holds. Without the status
+-- guard a delete that lost its claim mid-flight (reaped, or aborted and then
+-- re-attached by a racing capsule create) would erase the record of a volume
+-- that is once again in use.
+DELETE FROM volumes WHERE id = $1 AND team_id = $2 AND status = 'deleting';
+
+-- name: DeleteVolumesByTeam :exec
+-- Drop every volume record belonging to a team being deleted. This is the one
+-- place volumes are removed without an explicit per-volume delete: the team that
+-- owns them is going away, so there is no longer anyone who could reference,
+-- re-attach, or delete them. Unlike DeleteVolumeRow there is no status guard —
+-- the team's capsules have already been destroyed, so no volume can still be
+-- legitimately in use, and a row left behind would be unreachable forever (and
+-- would keep blocking deletion of the host it is pinned to).
+DELETE FROM volumes WHERE team_id = $1;

deploy/logrotate/wrenn

@@ -0,0 +1,19 @@
+/var/lib/wrenn/logs/control-plane.log
+/var/lib/wrenn/logs/host-agent.log
+{
+    daily
+    rotate 3
+    missingok
+    notifempty
+    dateext
+    dateformat -%Y-%m-%d
+    compress
+    delaycompress
+    sharedscripts
+    postrotate
+        # Signal the processes to reopen their log files.
+        # Use SIGHUP — both binaries handle it gracefully.
+        pkill -HUP -f wrenn-cp || true
+        pkill -HUP -f wrenn-agent || true
+    endscript
+}

envd-rs/.cargo/config.toml

@@ -0,0 +1,2 @@
+[target.x86_64-unknown-linux-musl]
+linker = "musl-gcc"

envd-rs/Cargo.toml

@@ -0,0 +1,82 @@
+[package]
+name = "envd"
+version = "0.7.0"
+edition = "2024"
+rust-version = "1.95"
+
+[dependencies]
+# Async runtime
+tokio = { version = "1", features = ["full"] }
+
+# HTTP framework
+axum = { version = "0.8", features = ["multipart"] }
+tower = { version = "0.5", features = ["util"] }
+tower-http = { version = "0.6", features = ["cors", "fs"] }
+tower-service = "0.3"
+
+# RPC (Connect protocol — serves Connect + gRPC + gRPC-Web on same port)
+connectrpc = { version = "0.3", features = ["axum"] }
+buffa-types = { path = "buffa-types-shim" }
+
+# CLI
+clap = { version = "4", features = ["derive"] }
+
+# Serialization
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
+# Logging
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["json", "env-filter"] }
+
+# System metrics
+sysinfo = "0.33"
+
+# Unix syscalls
+nix = { version = "0.30", features = ["fs", "process", "signal", "user", "term", "mount", "ioctl"] }
+
+# Concurrent map
+dashmap = "6"
+
+# Crypto
+sha2 = "0.10"
+hmac = "0.12"
+hex = "0.4"
+base64 = "0.22"
+
+# Secure memory
+zeroize = { version = "1", features = ["derive"] }
+
+# File watching
+notify = "7"
+
+# Directory walking
+walkdir = "2"
+
+# Time parsing (RFC3339 → epoch nanos for clock fix)
+chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
+
+# Misc
+libc = "0.2"
+bytes = "1"
+http = "1"
+http-body-util = "0.1"
+futures = "0.3"
+tokio-util = { version = "0.7", features = ["io"] }
+subtle = "2"
+http-body = "1.0.1"
+buffa = "0.3"
+async-stream = "0.3.6"
+
+[dev-dependencies]
+tempfile = "3"
+
+[build-dependencies]
+connectrpc-build = "0.3"
+
+[profile.release]
+strip = true
+lto = true
+opt-level = "z"
+codegen-units = 1
+panic = "abort"

envd-rs/README.md

@@ -0,0 +1,142 @@
+# envd (Rust)
+
+Wrenn guest agent daemon — runs as PID 1 inside Cloud Hypervisor microVMs. Provides process management, filesystem operations, file transfer, port forwarding, and VM lifecycle control over Connect RPC and HTTP.
+
+Rust rewrite of `envd/` (Go). Drop-in replacement — same wire protocol, same endpoints, same CLI flags.
+
+## Prerequisites
+
+- Rust 1.88+ (required by `connectrpc` 0.3.3)
+- `protoc` (protobuf compiler, for proto codegen at build time)
+- `musl-tools` (for static linking)
+
+```bash
+# Ubuntu/Debian
+sudo apt install musl-tools protobuf-compiler
+
+# Rust musl target
+rustup target add x86_64-unknown-linux-musl
+```
+
+## Building
+
+### Static binary (production — what goes into the rootfs)
+
+```bash
+cd envd-rs
+ENVD_COMMIT=$(git rev-parse --short HEAD) \
+  cargo build --release --target x86_64-unknown-linux-musl
+```
+
+Output: `target/x86_64-unknown-linux-musl/release/envd`
+
+Verify static linking:
+
+```bash
+file target/x86_64-unknown-linux-musl/release/envd
+# should say: "statically linked"
+
+ldd target/x86_64-unknown-linux-musl/release/envd
+# should say: "not a dynamic executable"
+```
+
+### Debug binary (dev machine, dynamically linked)
+
+```bash
+cd envd-rs
+cargo build
+```
+
+Run locally (outside a VM):
+
+```bash
+./target/debug/envd --port 49983
+```
+
+### Via Makefile (from repo root)
+
+```bash
+make build-envd        # static musl release build
+make build-envd-go     # Go version (for comparison)
+```
+
+## CLI Flags
+
+```
+--port <PORT>          Listen port [default: 49983]
+--version              Print version and exit
+--commit               Print git commit and exit
+--cmd <CMD>            Spawn a process at startup (e.g. --cmd "/bin/bash")
+--cgroup-root <PATH>   Cgroup v2 root [default: /sys/fs/cgroup]
+```
+
+## Endpoints
+
+### HTTP
+
+| Method | Path                | Description                          |
+|--------|---------------------|--------------------------------------|
+| GET    | `/health`           | Health check, triggers post-restore  |
+| GET    | `/metrics`          | System metrics (CPU, memory, disk)   |
+| GET    | `/envs`             | Current environment variables        |
+| POST   | `/init`             | Host agent init (token, env, mounts) |
+| POST   | `/snapshot/prepare` | Quiesce before Cloud Hypervisor snapshot |
+| GET    | `/files`            | Download file (streamed from disk)   |
+| PUT    | `/files`            | Upload file (raw body, streamed, atomic) |
+
+### Connect RPC (same port)
+
+| Service    | RPCs                                                                    |
+|------------|-------------------------------------------------------------------------|
+| Process    | List, Start, Connect, Update, StreamInput, SendInput, SendSignal, CloseStdin |
+| Filesystem | Stat, MakeDir, Move, ListDir, Remove, WatchDir, CreateWatcher, GetWatcherEvents, RemoveWatcher |
+
+## Architecture
+
+```
+42 files, ~4200 LOC Rust
+Binary: ~4 MB (stripped, LTO, musl static)
+
+src/
+├── main.rs              # Entry point, CLI, server setup
+├── state.rs             # Shared AppState
+├── config.rs            # Constants
+├── conntracker.rs       # TCP connection tracking for snapshot/restore
+├── execcontext.rs       # Default user/workdir/env
+├── logging.rs           # tracing-subscriber (JSON or pretty)
+├── util.rs              # AtomicMax
+├── auth/                # Token, signing, middleware
+├── crypto/              # SHA-256, SHA-512, HMAC
+├── host/                # System metrics
+├── http/                # Axum handlers (health, init, snapshot, files, encoding)
+├── permissions/         # Path resolution, user lookup, chown
+├── rpc/                 # Connect RPC services
+│   ├── pb.rs            # Generated proto types
+│   ├── process_*.rs     # Process service + handler (PTY, pipe, broadcast)
+│   ├── filesystem_*.rs  # Filesystem service (stat, list, watch, mkdir, move, remove)
+│   └── entry.rs         # EntryInfo builder
+├── port/                # Port subsystem
+│   ├── conn.rs          # /proc/net/tcp parser
+│   ├── scanner.rs       # Periodic TCP port scanner
+│   ├── forwarder.rs     # socat-based port forwarding
+│   └── subsystem.rs     # Lifecycle (start/stop/restart)
+└── cgroups/             # Cgroup v2 manager (pty/user/socat groups)
+```
+
+## Updating the rootfs
+
+After building the static binary, copy it into the rootfs:
+
+```bash
+bash scripts/update-minimal-rootfs.sh [rootfs_path]
+```
+
+With no argument it updates all four system base images; pass a path to target one.
+
+Or manually (example path: the minimal-ubuntu image, platform team + template id 0):
+
+```bash
+sudo mount -o loop /var/lib/wrenn/images/teams/0000000000000000000000000/0000000000000000000000000/rootfs.ext4 /mnt
+sudo cp target/x86_64-unknown-linux-musl/release/envd /mnt/usr/local/bin/envd
+sudo umount /mnt
+```

envd-rs/buffa-types-shim/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "buffa-types"
+version = "0.3.0"
+edition = "2024"
+publish = false
+
+[dependencies]
+buffa = "0.3"
+serde = { version = "1", features = ["derive"] }
+
+[build-dependencies]
+connectrpc-build = "0.3"

envd-rs/buffa-types-shim/build.rs

@@ -0,0 +1,9 @@
+fn main() {
+    connectrpc_build::Config::new()
+        .files(&["/usr/include/google/protobuf/timestamp.proto"])
+        .includes(&["/usr/include"])
+        .include_file("_types.rs")
+        .emit_register_fn(false)
+        .compile()
+        .unwrap();
+}

envd-rs/buffa-types-shim/src/lib.rs

@@ -0,0 +1,6 @@
+#![allow(dead_code, non_camel_case_types, unused_imports, clippy::derivable_impls)]
+
+use ::buffa;
+use ::serde;
+
+include!(concat!(env!("OUT_DIR"), "/_types.rs"));

envd-rs/build.rs

@@ -0,0 +1,11 @@
+fn main() {
+    connectrpc_build::Config::new()
+        .files(&[
+            "../proto/envd/process.proto",
+            "../proto/envd/filesystem.proto",
+        ])
+        .includes(&["../proto/envd", "/usr/include"])
+        .include_file("_connectrpc.rs")
+        .compile()
+        .unwrap();
+}

envd-rs/rust-toolchain.toml

@@ -0,0 +1,3 @@
+[toolchain]
+channel = "stable"
+targets = ["x86_64-unknown-linux-gnu", "x86_64-unknown-linux-musl"]

envd-rs/src/auth/mod.rs

@@ -0,0 +1,2 @@
+pub mod signing;
+pub mod token;

envd-rs/src/auth/signing.rs

@@ -0,0 +1,271 @@
+use subtle::ConstantTimeEq;
+
+use crate::auth::token::SecureToken;
+use crate::crypto;
+use zeroize::Zeroize;
+
+pub const READ_OPERATION: &str = "read";
+pub const WRITE_OPERATION: &str = "write";
+
+/// Generate a v1 signature: `v1_{sha256_base64(path:operation:username:token[:expiration])}`
+pub fn generate_signature(
+    token: &SecureToken,
+    path: &str,
+    username: &str,
+    operation: &str,
+    expiration: Option<i64>,
+) -> Result<String, &'static str> {
+    let mut token_bytes = token.bytes().ok_or("access token is not set")?;
+
+    let payload = match expiration {
+        Some(exp) => format!(
+            "{}:{}:{}:{}:{}",
+            path,
+            operation,
+            username,
+            String::from_utf8_lossy(&token_bytes),
+            exp
+        ),
+        None => format!(
+            "{}:{}:{}:{}",
+            path,
+            operation,
+            username,
+            String::from_utf8_lossy(&token_bytes),
+        ),
+    };
+
+    token_bytes.zeroize();
+
+    let hash = crypto::sha256::hash_without_prefix(payload.as_bytes());
+    Ok(format!("v1_{hash}"))
+}
+
+/// Validate a request's signing. Returns Ok(()) if valid.
+pub fn validate_signing(
+    token: &SecureToken,
+    header_token: Option<&str>,
+    signature: Option<&str>,
+    signature_expiration: Option<i64>,
+    username: &str,
+    path: &str,
+    operation: &str,
+) -> Result<(), String> {
+    if !token.is_set() {
+        return Ok(());
+    }
+
+    if let Some(ht) = header_token {
+        if !ht.is_empty() {
+            if token.equals(ht) {
+                return Ok(());
+            }
+            return Err("access token present in header but does not match".into());
+        }
+    }
+
+    let sig = signature.ok_or("missing signature query parameter")?;
+
+    let expected = generate_signature(token, path, username, operation, signature_expiration)
+        .map_err(|e| format!("error generating signing key: {e}"))?;
+
+    // Constant-time compare: both values are fixed-length `v1_<64 hex>` digests,
+    // so this matches the timing-side-channel posture of SecureToken::equals.
+    if expected.as_bytes().ct_eq(sig.as_bytes()).unwrap_u8() != 1 {
+        return Err("invalid signature".into());
+    }
+
+    if let Some(exp) = signature_expiration {
+        let now = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_secs() as i64;
+        if exp < now {
+            return Err("signature is already expired".into());
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn test_token(val: &[u8]) -> SecureToken {
+        let t = SecureToken::new();
+        t.set(val).unwrap();
+        t
+    }
+
+    fn far_future() -> i64 {
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_secs() as i64
+            + 3600
+    }
+
+    #[test]
+    fn generate_starts_with_v1() {
+        let token = test_token(b"secret");
+        let sig = generate_signature(&token, "/file", "root", READ_OPERATION, None).unwrap();
+        assert!(sig.starts_with("v1_"));
+    }
+
+    #[test]
+    fn generate_deterministic() {
+        let token = test_token(b"secret");
+        let s1 = generate_signature(&token, "/file", "root", READ_OPERATION, None).unwrap();
+        let s2 = generate_signature(&token, "/file", "root", READ_OPERATION, None).unwrap();
+        assert_eq!(s1, s2);
+    }
+
+    #[test]
+    fn generate_with_expiration_differs() {
+        let token = test_token(b"secret");
+        let without = generate_signature(&token, "/f", "u", READ_OPERATION, None).unwrap();
+        let with = generate_signature(&token, "/f", "u", READ_OPERATION, Some(9999)).unwrap();
+        assert_ne!(without, with);
+    }
+
+    #[test]
+    fn generate_unset_token_errors() {
+        let token = SecureToken::new();
+        assert!(generate_signature(&token, "/f", "u", READ_OPERATION, None).is_err());
+    }
+
+    #[test]
+    fn validate_no_token_set_passes() {
+        let token = SecureToken::new();
+        assert!(validate_signing(&token, None, None, None, "root", "/f", READ_OPERATION).is_ok());
+    }
+
+    #[test]
+    fn validate_correct_header_token() {
+        let token = test_token(b"secret");
+        assert!(
+            validate_signing(
+                &token,
+                Some("secret"),
+                None,
+                None,
+                "root",
+                "/f",
+                READ_OPERATION
+            )
+            .is_ok()
+        );
+    }
+
+    #[test]
+    fn validate_wrong_header_token() {
+        let token = test_token(b"secret");
+        let result = validate_signing(
+            &token,
+            Some("wrong"),
+            None,
+            None,
+            "root",
+            "/f",
+            READ_OPERATION,
+        );
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("does not match"));
+    }
+
+    #[test]
+    fn validate_valid_signature() {
+        let token = test_token(b"secret");
+        let exp = far_future();
+        let sig = generate_signature(&token, "/file", "root", READ_OPERATION, Some(exp)).unwrap();
+        assert!(
+            validate_signing(
+                &token,
+                None,
+                Some(&sig),
+                Some(exp),
+                "root",
+                "/file",
+                READ_OPERATION
+            )
+            .is_ok()
+        );
+    }
+
+    #[test]
+    fn validate_invalid_signature() {
+        let token = test_token(b"secret");
+        let result = validate_signing(
+            &token,
+            None,
+            Some("v1_bad"),
+            Some(far_future()),
+            "root",
+            "/f",
+            READ_OPERATION,
+        );
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("invalid signature"));
+    }
+
+    #[test]
+    fn validate_expired_signature() {
+        let token = test_token(b"secret");
+        let expired: i64 = 1_000_000;
+        let sig = generate_signature(&token, "/f", "root", READ_OPERATION, Some(expired)).unwrap();
+        let result = validate_signing(
+            &token,
+            None,
+            Some(&sig),
+            Some(expired),
+            "root",
+            "/f",
+            READ_OPERATION,
+        );
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("expired"));
+    }
+
+    #[test]
+    fn validate_missing_signature() {
+        let token = test_token(b"secret");
+        let result = validate_signing(&token, None, None, None, "root", "/f", READ_OPERATION);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("missing signature"));
+    }
+
+    #[test]
+    fn validate_empty_header_token_falls_through_to_signature() {
+        let token = test_token(b"secret");
+        let result = validate_signing(&token, Some(""), None, None, "root", "/f", READ_OPERATION);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("missing signature"));
+    }
+
+    #[test]
+    fn validate_valid_signature_no_expiration() {
+        let token = test_token(b"secret");
+        let sig = generate_signature(&token, "/file", "root", READ_OPERATION, None).unwrap();
+        assert!(
+            validate_signing(
+                &token,
+                None,
+                Some(&sig),
+                None,
+                "root",
+                "/file",
+                READ_OPERATION
+            )
+            .is_ok()
+        );
+    }
+
+    #[test]
+    fn different_operations_produce_different_signatures() {
+        let token = test_token(b"secret");
+        let r = generate_signature(&token, "/f", "root", READ_OPERATION, None).unwrap();
+        let w = generate_signature(&token, "/f", "root", WRITE_OPERATION, None).unwrap();
+        assert_ne!(r, w);
+    }
+}

envd-rs/src/auth/token.rs

@@ -0,0 +1,256 @@
+use std::sync::RwLock;
+
+use subtle::ConstantTimeEq;
+use zeroize::Zeroize;
+
+/// Secure token storage with constant-time comparison and zeroize-on-drop.
+///
+/// Mirrors Go's SecureToken backed by memguard.LockedBuffer.
+/// In Rust we rely on `zeroize` for Drop-based zeroing.
+pub struct SecureToken {
+    inner: RwLock<Option<Vec<u8>>>,
+}
+
+impl SecureToken {
+    pub fn new() -> Self {
+        Self {
+            inner: RwLock::new(None),
+        }
+    }
+
+    pub fn set(&self, token: &[u8]) -> Result<(), &'static str> {
+        if token.is_empty() {
+            return Err("empty token not allowed");
+        }
+        let mut guard = self.inner.write().unwrap();
+        if let Some(ref mut old) = *guard {
+            old.zeroize();
+        }
+        *guard = Some(token.to_vec());
+        Ok(())
+    }
+
+    pub fn is_set(&self) -> bool {
+        let guard = self.inner.read().unwrap();
+        guard.is_some()
+    }
+
+    /// Constant-time comparison.
+    pub fn equals(&self, other: &str) -> bool {
+        let guard = self.inner.read().unwrap();
+        match guard.as_ref() {
+            Some(buf) => buf.as_slice().ct_eq(other.as_bytes()).into(),
+            None => false,
+        }
+    }
+
+    /// Constant-time comparison with another SecureToken.
+    pub fn equals_secure(&self, other: &SecureToken) -> bool {
+        let other_bytes = match other.bytes() {
+            Some(b) => b,
+            None => return false,
+        };
+        let guard = self.inner.read().unwrap();
+        let result = match guard.as_ref() {
+            Some(buf) => buf.as_slice().ct_eq(&other_bytes).into(),
+            None => false,
+        };
+        // other_bytes dropped here, Vec<u8> doesn't auto-zeroize but
+        // we accept this — same as Go's `defer memguard.WipeBytes(otherBytes)`
+        result
+    }
+
+    /// Returns a copy of the token bytes (for signature generation).
+    pub fn bytes(&self) -> Option<Vec<u8>> {
+        let guard = self.inner.read().unwrap();
+        guard.as_ref().map(|b| b.clone())
+    }
+
+    /// Transfer token from another SecureToken, clearing the source.
+    pub fn take_from(&self, src: &SecureToken) {
+        let taken = {
+            let mut src_guard = src.inner.write().unwrap();
+            src_guard.take()
+        };
+        let mut guard = self.inner.write().unwrap();
+        if let Some(ref mut old) = *guard {
+            old.zeroize();
+        }
+        *guard = taken;
+    }
+
+    pub fn destroy(&self) {
+        let mut guard = self.inner.write().unwrap();
+        if let Some(ref mut buf) = *guard {
+            buf.zeroize();
+        }
+        *guard = None;
+    }
+}
+
+impl Drop for SecureToken {
+    fn drop(&mut self) {
+        if let Ok(mut guard) = self.inner.write() {
+            if let Some(ref mut buf) = *guard {
+                buf.zeroize();
+            }
+        }
+    }
+}
+
+/// Deserialize from JSON string, matching Go's UnmarshalJSON behavior.
+/// Expects a quoted JSON string. Rejects escape sequences.
+impl SecureToken {
+    pub fn from_json_bytes(data: &mut [u8]) -> Result<Self, &'static str> {
+        if data.len() < 2 || data[0] != b'"' || data[data.len() - 1] != b'"' {
+            data.zeroize();
+            return Err("invalid secure token JSON string");
+        }
+
+        let content = &data[1..data.len() - 1];
+        if content.contains(&b'\\') {
+            data.zeroize();
+            return Err("invalid secure token: unexpected escape sequence");
+        }
+
+        if content.is_empty() {
+            data.zeroize();
+            return Err("empty token not allowed");
+        }
+
+        let token = Self::new();
+        token.set(content).map_err(|_| "failed to set token")?;
+
+        data.zeroize();
+        Ok(token)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn new_is_unset() {
+        let t = SecureToken::new();
+        assert!(!t.is_set());
+        assert!(!t.equals("anything"));
+    }
+
+    #[test]
+    fn set_and_equals() {
+        let t = SecureToken::new();
+        t.set(b"secret").unwrap();
+        assert!(t.is_set());
+        assert!(t.equals("secret"));
+        assert!(!t.equals("wrong"));
+    }
+
+    #[test]
+    fn set_empty_errors() {
+        let t = SecureToken::new();
+        assert!(t.set(b"").is_err());
+        assert!(!t.is_set());
+    }
+
+    #[test]
+    fn set_overwrites_previous() {
+        let t = SecureToken::new();
+        t.set(b"first").unwrap();
+        t.set(b"second").unwrap();
+        assert!(!t.equals("first"));
+        assert!(t.equals("second"));
+    }
+
+    #[test]
+    fn destroy_clears() {
+        let t = SecureToken::new();
+        t.set(b"secret").unwrap();
+        t.destroy();
+        assert!(!t.is_set());
+        assert!(!t.equals("secret"));
+    }
+
+    #[test]
+    fn bytes_returns_copy() {
+        let t = SecureToken::new();
+        assert!(t.bytes().is_none());
+        t.set(b"hello").unwrap();
+        assert_eq!(t.bytes().unwrap(), b"hello");
+    }
+
+    #[test]
+    fn take_from_transfers_and_clears_source() {
+        let src = SecureToken::new();
+        src.set(b"token").unwrap();
+        let dst = SecureToken::new();
+        dst.take_from(&src);
+        assert!(!src.is_set());
+        assert!(dst.equals("token"));
+    }
+
+    #[test]
+    fn take_from_overwrites_existing() {
+        let src = SecureToken::new();
+        src.set(b"new").unwrap();
+        let dst = SecureToken::new();
+        dst.set(b"old").unwrap();
+        dst.take_from(&src);
+        assert!(dst.equals("new"));
+        assert!(!dst.equals("old"));
+    }
+
+    #[test]
+    fn equals_secure_matching() {
+        let a = SecureToken::new();
+        a.set(b"same").unwrap();
+        let b = SecureToken::new();
+        b.set(b"same").unwrap();
+        assert!(a.equals_secure(&b));
+    }
+
+    #[test]
+    fn equals_secure_different() {
+        let a = SecureToken::new();
+        a.set(b"one").unwrap();
+        let b = SecureToken::new();
+        b.set(b"two").unwrap();
+        assert!(!a.equals_secure(&b));
+    }
+
+    #[test]
+    fn equals_secure_unset() {
+        let a = SecureToken::new();
+        let b = SecureToken::new();
+        assert!(!a.equals_secure(&b));
+    }
+
+    #[test]
+    fn from_json_bytes_valid() {
+        let mut data = b"\"mysecret\"".to_vec();
+        let t = SecureToken::from_json_bytes(&mut data).unwrap();
+        assert!(t.equals("mysecret"));
+        assert!(data.iter().all(|&b| b == 0));
+    }
+
+    #[test]
+    fn from_json_bytes_rejects_missing_quotes() {
+        let mut data = b"noquotes".to_vec();
+        assert!(SecureToken::from_json_bytes(&mut data).is_err());
+        assert!(data.iter().all(|&b| b == 0));
+    }
+
+    #[test]
+    fn from_json_bytes_rejects_escape_sequences() {
+        let mut data = b"\"has\\nescapes\"".to_vec();
+        assert!(SecureToken::from_json_bytes(&mut data).is_err());
+        assert!(data.iter().all(|&b| b == 0));
+    }
+
+    #[test]
+    fn from_json_bytes_rejects_empty_content() {
+        let mut data = b"\"\"".to_vec();
+        assert!(SecureToken::from_json_bytes(&mut data).is_err());
+        assert!(data.iter().all(|&b| b == 0));
+    }
+}

envd-rs/src/cgroups/mod.rs

@@ -0,0 +1,71 @@
+use std::collections::HashMap;
+use std::fs;
+use std::os::unix::io::{OwnedFd, RawFd};
+use std::path::PathBuf;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum ProcessType {
+    Pty,
+    User,
+    Socat,
+}
+
+pub trait CgroupManager: Send + Sync {
+    fn get_fd(&self, proc_type: ProcessType) -> Option<RawFd>;
+}
+
+pub struct Cgroup2Manager {
+    fds: HashMap<ProcessType, OwnedFd>,
+}
+
+impl Cgroup2Manager {
+    pub fn new(
+        root: &str,
+        configs: &[(ProcessType, &str, &[(&str, &str)])],
+    ) -> Result<Self, String> {
+        let mut fds = HashMap::new();
+
+        for (proc_type, sub_path, properties) in configs {
+            let full_path = PathBuf::from(root).join(sub_path);
+
+            fs::create_dir_all(&full_path)
+                .map_err(|e| format!("failed to create cgroup {}: {e}", full_path.display()))?;
+
+            for (name, value) in *properties {
+                let prop_path = full_path.join(name);
+                fs::write(&prop_path, value).map_err(|e| {
+                    format!(
+                        "failed to write cgroup property {}: {e}",
+                        prop_path.display()
+                    )
+                })?;
+            }
+
+            let fd = nix::fcntl::open(
+                &full_path,
+                nix::fcntl::OFlag::O_RDONLY,
+                nix::sys::stat::Mode::empty(),
+            )
+            .map_err(|e| format!("failed to open cgroup {}: {e}", full_path.display()))?;
+
+            fds.insert(*proc_type, fd);
+        }
+
+        Ok(Self { fds })
+    }
+}
+
+impl CgroupManager for Cgroup2Manager {
+    fn get_fd(&self, proc_type: ProcessType) -> Option<RawFd> {
+        use std::os::unix::io::AsRawFd;
+        self.fds.get(&proc_type).map(|fd| fd.as_raw_fd())
+    }
+}
+
+pub struct NoopCgroupManager;
+
+impl CgroupManager for NoopCgroupManager {
+    fn get_fd(&self, _proc_type: ProcessType) -> Option<RawFd> {
+        None
+    }
+}

envd-rs/src/cmd/mod.rs

@@ -0,0 +1,5 @@
+//! Client subcommands for the `envd` binary. These run as short-lived
+//! invocations (e.g. `envd ports`) inside the guest, separate from the
+//! long-running daemon, and exit when done.
+
+pub mod ports;

envd-rs/src/cmd/ports.rs

@@ -0,0 +1,164 @@
+//! `envd ports` — list the open ports inside the sandbox that are reachable
+//! from outside, alongside the URL each is served at.
+//!
+//! Runs as a one-shot client (not the daemon): it scans `/proc/net/tcp[6]`
+//! directly via the shared port helper and reads the sandbox identity that the
+//! daemon recorded under /run/wrenn at /init time. It refuses to run outside a
+//! wrenn sandbox.
+
+use std::fs;
+use std::path::Path;
+
+use crate::config::{DEFAULT_PORT, DEFAULT_PROXY_DOMAIN, WRENN_RUN_DIR};
+use crate::port::conn::reachable_listening_ports;
+
+/// Arguments for the `envd ports` subcommand.
+#[derive(clap::Args)]
+pub struct PortsArgs {
+    /// Override the proxy domain used to build URLs (default: the domain
+    /// injected by the host, falling back to the built-in default).
+    #[arg(long)]
+    domain: Option<String>,
+
+    /// Emit JSON instead of a table.
+    #[arg(long)]
+    json: bool,
+}
+
+#[derive(serde::Serialize)]
+struct PortEntry {
+    port: u32,
+    url: String,
+}
+
+/// Runs the subcommand and returns the desired process exit code.
+pub fn run(args: &PortsArgs) -> i32 {
+    if !inside_sandbox() {
+        eprintln!("envd ports: not running inside a wrenn sandbox");
+        return 1;
+    }
+
+    let sandbox_id = read_identity("WRENN_SANDBOX_ID", ".WRENN_SANDBOX_ID");
+    let domain = args
+        .domain
+        .clone()
+        .filter(|d| !d.is_empty())
+        .or_else(|| read_identity("WRENN_PROXY_DOMAIN", ".WRENN_PROXY_DOMAIN"))
+        .unwrap_or_else(|| DEFAULT_PROXY_DOMAIN.to_string());
+
+    let entries: Vec<PortEntry> = reachable_listening_ports(DEFAULT_PORT as u32)
+        .into_iter()
+        .map(|port| PortEntry {
+            url: build_url(port, sandbox_id.as_deref(), &domain),
+            port,
+        })
+        .collect();
+
+    if args.json {
+        match serde_json::to_string_pretty(&entries) {
+            Ok(s) => println!("{s}"),
+            Err(e) => {
+                eprintln!("envd ports: failed to encode JSON: {e}");
+                return 1;
+            }
+        }
+        return 0;
+    }
+
+    if entries.is_empty() {
+        println!("No open ports.");
+        return 0;
+    }
+
+    println!("{:<6} {}", "PORT", "URL");
+    for e in &entries {
+        println!("{:<6} {}", e.port, e.url);
+    }
+    0
+}
+
+/// A wrenn sandbox is identified by the marker the daemon writes at startup
+/// (`/run/wrenn/.WRENN_SANDBOX`) and the `WRENN_SANDBOX` env var it exports
+/// into spawned processes. Running `envd ports` on a normal host finds neither
+/// and is refused.
+fn inside_sandbox() -> bool {
+    if std::env::var("WRENN_SANDBOX").as_deref() == Ok("true") {
+        return true;
+    }
+    Path::new(WRENN_RUN_DIR).join(".WRENN_SANDBOX").exists()
+}
+
+/// Reads an identity value from the environment, falling back to the matching
+/// /run/wrenn file. Returns None when neither is set or both are blank.
+fn read_identity(env_key: &str, file_name: &str) -> Option<String> {
+    if let Ok(v) = std::env::var(env_key) {
+        let v = v.trim().to_string();
+        if !v.is_empty() {
+            return Some(v);
+        }
+    }
+    match fs::read_to_string(Path::new(WRENN_RUN_DIR).join(file_name)) {
+        Ok(v) => {
+            let v = v.trim().to_string();
+            if v.is_empty() { None } else { Some(v) }
+        }
+        Err(_) => None,
+    }
+}
+
+/// Builds the externally-reachable URL for a port. With a known sandbox ID the
+/// result is a working https URL; without it (identity not yet injected) the
+/// sandbox-ID segment degrades to a `<sandbox-id>` placeholder so output is
+/// still informative.
+fn build_url(port: u32, sandbox_id: Option<&str>, domain: &str) -> String {
+    let id = sandbox_id.unwrap_or("<sandbox-id>");
+    format!("https://{port}-{id}.{domain}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn url_with_sandbox_id() {
+        assert_eq!(
+            build_url(8000, Some("cl-abcd1234"), "wrenn.dev"),
+            "https://8000-cl-abcd1234.wrenn.dev"
+        );
+    }
+
+    #[test]
+    fn url_without_sandbox_id_uses_placeholder() {
+        assert_eq!(
+            build_url(5173, None, "wrenn.dev"),
+            "https://5173-<sandbox-id>.wrenn.dev"
+        );
+    }
+
+    #[test]
+    fn url_honors_custom_domain() {
+        assert_eq!(
+            build_url(3000, Some("cl-deadbeef"), "sandbox.example.com"),
+            "https://3000-cl-deadbeef.sandbox.example.com"
+        );
+    }
+
+    #[test]
+    fn read_identity_prefers_env() {
+        // SAFETY: test-local env var, single-threaded test body.
+        unsafe { std::env::set_var("ENVD_PORTS_TEST_ID", "  cl-fromenv  ") };
+        assert_eq!(
+            read_identity("ENVD_PORTS_TEST_ID", ".nonexistent-file"),
+            Some("cl-fromenv".to_string())
+        );
+        unsafe { std::env::remove_var("ENVD_PORTS_TEST_ID") };
+    }
+
+    #[test]
+    fn read_identity_none_when_unset() {
+        assert_eq!(
+            read_identity("ENVD_PORTS_TEST_UNSET", ".nonexistent-file"),
+            None
+        );
+    }
+}

envd-rs/src/config.rs

@@ -0,0 +1,16 @@
+use std::time::Duration;
+
+pub const DEFAULT_PORT: u16 = 49983;
+pub const IDLE_TIMEOUT: Duration = Duration::from_secs(640);
+pub const CORS_MAX_AGE: Duration = Duration::from_secs(7200);
+pub const PORT_SCANNER_INTERVAL: Duration = Duration::from_millis(1000);
+pub const DEFAULT_USER: &str = "root";
+pub const WRENN_RUN_DIR: &str = "/run/wrenn";
+
+/// Fallback proxy domain used by `envd ports` to build URLs when the host has
+/// not injected one via /init. Matches the host agent's WRENN_PROXY_DOMAIN
+/// default.
+pub const DEFAULT_PROXY_DOMAIN: &str = "wrenn.dev";
+
+pub const KILOBYTE: u64 = 1024;
+pub const MEGABYTE: u64 = 1024 * KILOBYTE;

envd-rs/src/conntracker.rs

@@ -0,0 +1,70 @@
+use std::collections::HashSet;
+use std::sync::Mutex;
+
+/// Tracks active TCP connections.
+pub struct ConnTracker {
+    inner: Mutex<ConnTrackerInner>,
+}
+
+struct ConnTrackerInner {
+    active: HashSet<u64>,
+    next_id: u64,
+}
+
+impl ConnTracker {
+    pub fn new() -> Self {
+        Self {
+            inner: Mutex::new(ConnTrackerInner {
+                active: HashSet::new(),
+                next_id: 0,
+            }),
+        }
+    }
+
+    pub fn register_connection(&self) -> u64 {
+        let mut inner = self.inner.lock().unwrap();
+        let id = inner.next_id;
+        inner.next_id += 1;
+        inner.active.insert(id);
+        id
+    }
+
+    pub fn remove_connection(&self, id: u64) {
+        let mut inner = self.inner.lock().unwrap();
+        inner.active.remove(&id);
+    }
+
+    #[cfg(test)]
+    fn active_count(&self) -> usize {
+        self.inner.lock().unwrap().active.len()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn register_assigns_sequential_ids() {
+        let ct = ConnTracker::new();
+        assert_eq!(ct.register_connection(), 0);
+        assert_eq!(ct.register_connection(), 1);
+        assert_eq!(ct.register_connection(), 2);
+    }
+
+    #[test]
+    fn remove_clears_active() {
+        let ct = ConnTracker::new();
+        let id = ct.register_connection();
+        assert_eq!(ct.active_count(), 1);
+        ct.remove_connection(id);
+        assert_eq!(ct.active_count(), 0);
+    }
+
+    #[test]
+    fn remove_nonexistent_is_noop() {
+        let ct = ConnTracker::new();
+        ct.remove_connection(999);
+        assert_eq!(ct.active_count(), 0);
+    }
+}

envd-rs/src/crypto/hmac_sha256.rs

@@ -0,0 +1,43 @@
+use hmac::{Hmac, Mac};
+use sha2::Sha256;
+
+type HmacSha256 = Hmac<Sha256>;
+
+pub fn compute(key: &[u8], data: &[u8]) -> String {
+    let mut mac = HmacSha256::new_from_slice(key).expect("HMAC accepts any key length");
+    mac.update(data);
+    let result = mac.finalize();
+    hex::encode(result.into_bytes())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn rfc4231_tc1() {
+        let key = &[0x0b; 20];
+        let data = b"Hi There";
+        assert_eq!(
+            compute(key, data),
+            "b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7"
+        );
+    }
+
+    #[test]
+    fn rfc4231_tc2() {
+        let key = b"Jefe";
+        let data = b"what do ya want for nothing?";
+        assert_eq!(
+            compute(key, data),
+            "5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843"
+        );
+    }
+
+    #[test]
+    fn output_is_64_hex_chars() {
+        let result = compute(b"key", b"data");
+        assert_eq!(result.len(), 64);
+        assert!(result.chars().all(|c| c.is_ascii_hexdigit()));
+    }
+}

envd-rs/src/crypto/mod.rs

@@ -0,0 +1,3 @@
+pub mod hmac_sha256;
+pub mod sha256;
+pub mod sha512;

envd-rs/src/crypto/sha256.rs

@@ -0,0 +1,67 @@
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD_NO_PAD;
+use sha2::{Digest, Sha256};
+
+pub fn hash(data: &[u8]) -> String {
+    let h = Sha256::digest(data);
+    let encoded = STANDARD_NO_PAD.encode(h);
+    format!("$sha256${encoded}")
+}
+
+pub fn hash_without_prefix(data: &[u8]) -> String {
+    let h = Sha256::digest(data);
+    STANDARD_NO_PAD.encode(h)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const VECTORS: &[(&[u8], &str)] = &[
+        (b"", "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU"),
+        (b"abc", "ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0"),
+        (
+            b"abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq",
+            "JI1qYdIGOLjlwCaTDD5gOaM85Flk/yFn9uzt1BnbBsE",
+        ),
+    ];
+
+    #[test]
+    fn known_answer_with_prefix() {
+        for (input, expected_b64) in VECTORS {
+            let result = hash(input);
+            assert_eq!(
+                result,
+                format!("$sha256${expected_b64}"),
+                "input: {:?}",
+                String::from_utf8_lossy(input)
+            );
+        }
+    }
+
+    #[test]
+    fn known_answer_without_prefix() {
+        for (input, expected_b64) in VECTORS {
+            let result = hash_without_prefix(input);
+            assert_eq!(
+                result,
+                *expected_b64,
+                "input: {:?}",
+                String::from_utf8_lossy(input)
+            );
+        }
+    }
+
+    #[test]
+    fn no_base64_padding() {
+        for (input, _) in VECTORS {
+            assert!(!hash(input).contains('='));
+            assert!(!hash_without_prefix(input).contains('='));
+        }
+    }
+
+    #[test]
+    fn deterministic() {
+        assert_eq!(hash(b"test"), hash(b"test"));
+    }
+}

envd-rs/src/crypto/sha512.rs

@@ -0,0 +1,58 @@
+use sha2::{Digest, Sha512};
+
+pub fn hash_access_token(token: &str) -> String {
+    let h = Sha512::digest(token.as_bytes());
+    hex::encode(h)
+}
+
+pub fn hash_access_token_bytes(token: &[u8]) -> String {
+    let h = Sha512::digest(token);
+    hex::encode(h)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const VECTORS: &[(&str, &str)] = &[
+        (
+            "",
+            "cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e",
+        ),
+        (
+            "abc",
+            "ddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f",
+        ),
+        (
+            "abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq",
+            "204a8fc6dda82f0a0ced7beb8e08a41657c16ef468b228a8279be331a703c33596fd15c13b1b07f9aa1d3bea57789ca031ad85c7a71dd70354ec631238ca3445",
+        ),
+    ];
+
+    #[test]
+    fn known_answer() {
+        for (input, expected) in VECTORS {
+            assert_eq!(hash_access_token(input), *expected, "input: {input:?}");
+        }
+    }
+
+    #[test]
+    fn str_and_bytes_agree() {
+        for (input, _) in VECTORS {
+            assert_eq!(
+                hash_access_token(input),
+                hash_access_token_bytes(input.as_bytes())
+            );
+        }
+    }
+
+    #[test]
+    fn output_is_lowercase_hex_128_chars() {
+        let h = hash_access_token("anything");
+        assert_eq!(h.len(), 128);
+        assert!(
+            h.chars()
+                .all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase())
+        );
+    }
+}

envd-rs/src/execcontext.rs

@@ -0,0 +1,124 @@
+use dashmap::DashMap;
+use std::sync::{Arc, RwLock};
+
+pub struct Defaults {
+    pub env_vars: Arc<DashMap<String, String>>,
+    user: RwLock<String>,
+    workdir: RwLock<Option<String>>,
+}
+
+impl Defaults {
+    pub fn new(user: &str) -> Self {
+        Self {
+            env_vars: Arc::new(DashMap::new()),
+            user: RwLock::new(user.to_string()),
+            workdir: RwLock::new(None),
+        }
+    }
+
+    pub fn user(&self) -> String {
+        self.user.read().unwrap().clone()
+    }
+
+    pub fn set_user(&self, user: String) {
+        *self.user.write().unwrap() = user;
+    }
+
+    pub fn workdir(&self) -> Option<String> {
+        self.workdir.read().unwrap().clone()
+    }
+
+    pub fn set_workdir(&self, workdir: Option<String>) {
+        *self.workdir.write().unwrap() = workdir;
+    }
+}
+
+pub fn resolve_default_workdir(workdir: &str, default_workdir: Option<&str>) -> String {
+    if !workdir.is_empty() {
+        return workdir.to_string();
+    }
+    if let Some(dw) = default_workdir {
+        return dw.to_string();
+    }
+    String::new()
+}
+
+pub fn resolve_default_username<'a>(
+    username: Option<&'a str>,
+    default_username: &'a str,
+) -> Result<&'a str, &'static str> {
+    if let Some(u) = username {
+        return Ok(u);
+    }
+    if !default_username.is_empty() {
+        return Ok(default_username);
+    }
+    Err("username not provided")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn workdir_explicit_overrides_default() {
+        assert_eq!(
+            resolve_default_workdir("/explicit", Some("/default")),
+            "/explicit"
+        );
+    }
+
+    #[test]
+    fn workdir_empty_uses_default() {
+        assert_eq!(resolve_default_workdir("", Some("/default")), "/default");
+    }
+
+    #[test]
+    fn workdir_empty_no_default_returns_empty() {
+        assert_eq!(resolve_default_workdir("", None), "");
+    }
+
+    #[test]
+    fn workdir_explicit_ignores_none_default() {
+        assert_eq!(resolve_default_workdir("/explicit", None), "/explicit");
+    }
+
+    #[test]
+    fn username_explicit_returns_explicit() {
+        assert_eq!(
+            resolve_default_username(Some("root"), "wrenn").unwrap(),
+            "root"
+        );
+    }
+
+    #[test]
+    fn username_none_uses_default() {
+        assert_eq!(resolve_default_username(None, "wrenn").unwrap(), "wrenn");
+    }
+
+    #[test]
+    fn username_none_empty_default_errors() {
+        assert!(resolve_default_username(None, "").is_err());
+    }
+
+    #[test]
+    fn username_some_overrides_empty_default() {
+        assert_eq!(resolve_default_username(Some("root"), "").unwrap(), "root");
+    }
+
+    #[test]
+    fn defaults_user_set_and_get() {
+        let d = Defaults::new("initial");
+        assert_eq!(d.user(), "initial");
+        d.set_user("changed".into());
+        assert_eq!(d.user(), "changed");
+    }
+
+    #[test]
+    fn defaults_workdir_initially_none() {
+        let d = Defaults::new("user");
+        assert!(d.workdir().is_none());
+        d.set_workdir(Some("/home".into()));
+        assert_eq!(d.workdir().unwrap(), "/home");
+    }
+}

envd-rs/src/http/activity.rs

@@ -0,0 +1,34 @@
+use std::sync::Arc;
+
+use axum::Json;
+use axum::extract::State;
+use axum::http::header;
+use axum::response::IntoResponse;
+use serde::Serialize;
+
+use crate::state::AppState;
+
+/// Liveness snapshot the host activity sampler polls to decide whether a
+/// sandbox is doing real work. All fields are served straight from atomics
+/// updated by the 1s sampler thread — no syscalls per request, so the host
+/// can poll cheaply at a few-second cadence.
+#[derive(Serialize)]
+pub struct Activity {
+    cpu_count: u32,
+    cpu_used_pct: f32,
+    net_bps: u64,
+    disk_bps: u64,
+}
+
+pub async fn get_activity(State(state): State<Arc<AppState>>) -> impl IntoResponse {
+    tracing::trace!("get activity");
+
+    let body = Activity {
+        cpu_count: state.cpu_count(),
+        cpu_used_pct: state.cpu_used_pct(),
+        net_bps: state.net_bps(),
+        disk_bps: state.disk_bps(),
+    };
+
+    ([(header::CACHE_CONTROL, "no-store")], Json(body))
+}

envd-rs/src/http/envs.rs

@@ -0,0 +1,22 @@
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use axum::Json;
+use axum::extract::State;
+use axum::http::header;
+use axum::response::IntoResponse;
+
+use crate::state::AppState;
+
+pub async fn get_envs(State(state): State<Arc<AppState>>) -> impl IntoResponse {
+    tracing::debug!("getting env vars");
+
+    let envs: HashMap<String, String> = state
+        .defaults
+        .env_vars
+        .iter()
+        .map(|entry| (entry.key().clone(), entry.value().clone()))
+        .collect();
+
+    ([(header::CACHE_CONTROL, "no-store")], Json(envs))
+}

envd-rs/src/http/error.rs

@@ -0,0 +1,20 @@
+use axum::Json;
+use axum::http::StatusCode;
+use axum::response::IntoResponse;
+use serde::Serialize;
+
+#[derive(Serialize)]
+struct ErrorBody {
+    code: u16,
+    message: String,
+}
+
+pub fn json_error(status: StatusCode, message: &str) -> impl IntoResponse {
+    (
+        status,
+        Json(ErrorBody {
+            code: status.as_u16(),
+            message: message.to_string(),
+        }),
+    )
+}

envd-rs/src/http/files.rs

@@ -0,0 +1,377 @@
+use std::os::unix::fs::OpenOptionsExt;
+use std::path::Path;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use axum::body::Body;
+use axum::extract::{Query, Request, State};
+use axum::http::{StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use futures::StreamExt;
+use serde::{Deserialize, Serialize};
+use tokio::io::AsyncWriteExt;
+use tokio_util::io::ReaderStream;
+
+use crate::auth::signing;
+use crate::execcontext;
+use crate::permissions::path::{ensure_dirs, expand_and_resolve};
+use crate::permissions::user::lookup_user;
+use crate::state::AppState;
+
+const ACCESS_TOKEN_HEADER: &str = "x-access-token";
+
+/// Monotonic counter for unique temp-file names within this process. Combined
+/// with the pid it guarantees concurrent uploads never collide on the staging
+/// path before the atomic rename.
+static UPLOAD_SEQ: AtomicU64 = AtomicU64::new(0);
+
+#[derive(Deserialize)]
+pub struct FileParams {
+    pub path: Option<String>,
+    pub username: Option<String>,
+    pub signature: Option<String>,
+    pub signature_expiration: Option<i64>,
+}
+
+#[derive(Serialize)]
+struct EntryInfo {
+    path: String,
+    name: String,
+    r#type: &'static str,
+}
+
+fn json_error(status: StatusCode, msg: &str) -> Response {
+    let body = serde_json::json!({ "code": status.as_u16(), "message": msg });
+    (status, axum::Json(body)).into_response()
+}
+
+fn extract_header_token(req: &Request) -> Option<&str> {
+    req.headers()
+        .get(ACCESS_TOKEN_HEADER)
+        .and_then(|v| v.to_str().ok())
+}
+
+fn validate_file_signing(
+    state: &AppState,
+    header_token: Option<&str>,
+    params: &FileParams,
+    path: &str,
+    operation: &str,
+    username: &str,
+) -> Result<(), String> {
+    signing::validate_signing(
+        &state.access_token,
+        header_token,
+        params.signature.as_deref(),
+        params.signature_expiration,
+        username,
+        path,
+        operation,
+    )
+}
+
+/// GET /files — download a file, streamed from disk.
+///
+/// The body is streamed straight off the filesystem so large files never get
+/// buffered into memory. Identity encoding only — no gzip, no range support.
+pub async fn get_files(
+    State(state): State<Arc<AppState>>,
+    Query(params): Query<FileParams>,
+    req: Request,
+) -> Response {
+    let path_str = params.path.as_deref().unwrap_or("");
+    let header_token = extract_header_token(&req);
+
+    let default_user = state.defaults.user();
+    let username =
+        match execcontext::resolve_default_username(params.username.as_deref(), &default_user) {
+            Ok(u) => u.to_string(),
+            Err(e) => return json_error(StatusCode::BAD_REQUEST, e),
+        };
+
+    if let Err(e) = validate_file_signing(
+        &state,
+        header_token,
+        &params,
+        path_str,
+        signing::READ_OPERATION,
+        &username,
+    ) {
+        return json_error(StatusCode::UNAUTHORIZED, &e);
+    }
+
+    let user = match lookup_user(&username) {
+        Ok(u) => u,
+        Err(e) => return json_error(StatusCode::UNAUTHORIZED, &e),
+    };
+
+    let home_dir = user.dir.to_string_lossy().to_string();
+    let default_workdir = state.defaults.workdir();
+    let resolved = match expand_and_resolve(path_str, &home_dir, default_workdir.as_deref()) {
+        Ok(p) => p,
+        Err(e) => return json_error(StatusCode::BAD_REQUEST, &e),
+    };
+
+    let meta = match tokio::fs::metadata(&resolved).await {
+        Ok(m) => m,
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+            return json_error(
+                StatusCode::NOT_FOUND,
+                &format!("path '{}' does not exist", resolved),
+            );
+        }
+        Err(e) => {
+            return json_error(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                &format!("error checking path: {e}"),
+            );
+        }
+    };
+
+    if meta.is_dir() {
+        return json_error(
+            StatusCode::BAD_REQUEST,
+            &format!("path '{}' is a directory", resolved),
+        );
+    }
+
+    if !meta.file_type().is_file() {
+        return json_error(
+            StatusCode::BAD_REQUEST,
+            &format!("path '{}' is not a regular file", resolved),
+        );
+    }
+
+    let file = match tokio::fs::File::open(&resolved).await {
+        Ok(f) => f,
+        Err(e) => {
+            return json_error(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                &format!("error opening file: {e}"),
+            );
+        }
+    };
+
+    let filename = Path::new(&resolved)
+        .file_name()
+        .map(|n| n.to_string_lossy().to_string())
+        .unwrap_or_default();
+    let content_disposition = format!("inline; filename=\"{}\"", filename);
+
+    let body = Body::from_stream(ReaderStream::new(file));
+
+    Response::builder()
+        .status(StatusCode::OK)
+        .header(header::CONTENT_TYPE, "application/octet-stream")
+        .header(header::CONTENT_DISPOSITION, content_disposition)
+        .header(header::CONTENT_LENGTH, meta.len())
+        .body(body)
+        .unwrap()
+}
+
+/// PUT /files — upload a single file, streamed to disk.
+///
+/// The request body is the raw file content (no multipart, no encoding). It is
+/// streamed to a temporary staging file in the destination directory, then
+/// atomically renamed into place — concurrent writers to the same path never
+/// observe a torn file, and the last rename wins.
+pub async fn put_files(
+    State(state): State<Arc<AppState>>,
+    Query(params): Query<FileParams>,
+    req: Request,
+) -> Response {
+    let path_str = params.path.as_deref().unwrap_or("");
+    if path_str.is_empty() {
+        return json_error(StatusCode::BAD_REQUEST, "missing required 'path' parameter");
+    }
+    let header_token = extract_header_token(&req);
+
+    let default_user = state.defaults.user();
+    let username =
+        match execcontext::resolve_default_username(params.username.as_deref(), &default_user) {
+            Ok(u) => u.to_string(),
+            Err(e) => return json_error(StatusCode::BAD_REQUEST, e),
+        };
+
+    if let Err(e) = validate_file_signing(
+        &state,
+        header_token,
+        &params,
+        path_str,
+        signing::WRITE_OPERATION,
+        &username,
+    ) {
+        return json_error(StatusCode::UNAUTHORIZED, &e);
+    }
+
+    let user = match lookup_user(&username) {
+        Ok(u) => u,
+        Err(e) => return json_error(StatusCode::UNAUTHORIZED, &e),
+    };
+
+    let home_dir = user.dir.to_string_lossy().to_string();
+    let uid = user.uid;
+    let gid = user.gid;
+    let default_workdir = state.defaults.workdir();
+
+    let file_path = match expand_and_resolve(path_str, &home_dir, default_workdir.as_deref()) {
+        Ok(p) => p,
+        Err(e) => return json_error(StatusCode::BAD_REQUEST, &e),
+    };
+
+    if let Err((status, msg)) = stream_to_file(req.into_body(), &file_path, uid, gid).await {
+        return json_error(status, &msg);
+    }
+
+    let name = Path::new(&file_path)
+        .file_name()
+        .map(|n| n.to_string_lossy().to_string())
+        .unwrap_or_default();
+
+    axum::Json(EntryInfo {
+        path: file_path,
+        name,
+        r#type: "file",
+    })
+    .into_response()
+}
+
+/// Stream a request body to `path` via a temp file + atomic rename. The staging
+/// file is created with mode 0o666 and chowned to (uid, gid) before the rename,
+/// so the destination appears atomically with the correct owner.
+async fn stream_to_file(
+    body: Body,
+    path: &str,
+    uid: nix::unistd::Uid,
+    gid: nix::unistd::Gid,
+) -> Result<(), (StatusCode, String)> {
+    let target = Path::new(path);
+
+    let dir = target
+        .parent()
+        .map(|p| p.to_string_lossy().to_string())
+        .unwrap_or_default();
+
+    if !dir.is_empty() {
+        ensure_dirs(&dir, uid, gid).map_err(|e| {
+            (
+                StatusCode::INTERNAL_SERVER_ERROR,
+                format!("error ensuring directories: {e}"),
+            )
+        })?;
+    }
+
+    // Reject writing over an existing directory before staging anything.
+    match std::fs::metadata(path) {
+        Ok(meta) if meta.is_dir() => {
+            return Err((
+                StatusCode::BAD_REQUEST,
+                format!("path is a directory: {path}"),
+            ));
+        }
+        Ok(_) => {}
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
+        Err(e) => {
+            return Err((
+                StatusCode::INTERNAL_SERVER_ERROR,
+                format!("error getting file info: {e}"),
+            ));
+        }
+    }
+
+    // Stage in the destination directory so the rename stays on one filesystem.
+    let seq = UPLOAD_SEQ.fetch_add(1, Ordering::Relaxed);
+    let tmp_name = format!(".envd-upload.{}.{}", std::process::id(), seq);
+    let tmp_path = if dir.is_empty() {
+        tmp_name
+    } else {
+        format!("{dir}/{tmp_name}")
+    };
+
+    let map_open_err = |e: std::io::Error| {
+        if e.raw_os_error() == Some(libc::ENOSPC) {
+            return (
+                StatusCode::INSUFFICIENT_STORAGE,
+                "not enough disk space available".to_string(),
+            );
+        }
+        (
+            StatusCode::INTERNAL_SERVER_ERROR,
+            format!("error opening file: {e}"),
+        )
+    };
+
+    let std_file = std::fs::OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .mode(0o666)
+        .open(&tmp_path)
+        .map_err(map_open_err)?;
+
+    // From here on, any failure must clean up the staging file.
+    let result = write_body_to_tmp(body, std_file, &tmp_path, uid, gid).await;
+    if result.is_err() {
+        let _ = std::fs::remove_file(&tmp_path);
+        return result.map(|_| ());
+    }
+
+    std::fs::rename(&tmp_path, path).map_err(|e| {
+        let _ = std::fs::remove_file(&tmp_path);
+        (
+            StatusCode::INTERNAL_SERVER_ERROR,
+            format!("error finalizing file: {e}"),
+        )
+    })?;
+
+    Ok(())
+}
+
+async fn write_body_to_tmp(
+    body: Body,
+    std_file: std::fs::File,
+    tmp_path: &str,
+    uid: nix::unistd::Uid,
+    gid: nix::unistd::Gid,
+) -> Result<(), (StatusCode, String)> {
+    let mut file = tokio::fs::File::from_std(std_file);
+
+    let mut stream = body.into_data_stream();
+    while let Some(chunk) = stream.next().await {
+        let bytes = chunk.map_err(|e| {
+            (
+                StatusCode::BAD_REQUEST,
+                format!("error reading request body: {e}"),
+            )
+        })?;
+        file.write_all(&bytes).await.map_err(|e| {
+            if e.raw_os_error() == Some(libc::ENOSPC) {
+                return (
+                    StatusCode::INSUFFICIENT_STORAGE,
+                    "not enough disk space available".to_string(),
+                );
+            }
+            (
+                StatusCode::INTERNAL_SERVER_ERROR,
+                format!("error writing file: {e}"),
+            )
+        })?;
+    }
+
+    file.flush().await.map_err(|e| {
+        (
+            StatusCode::INTERNAL_SERVER_ERROR,
+            format!("error flushing file: {e}"),
+        )
+    })?;
+
+    // chown the staging file so it lands at the destination already owned by
+    // the target user.
+    std::os::unix::fs::chown(tmp_path, Some(uid.as_raw()), Some(gid.as_raw())).map_err(|e| {
+        (
+            StatusCode::INTERNAL_SERVER_ERROR,
+            format!("error changing ownership: {e}"),
+        )
+    })?;
+
+    Ok(())
+}

envd-rs/src/http/health.rs

@@ -0,0 +1,18 @@
+use std::sync::Arc;
+
+use axum::Json;
+use axum::extract::State;
+use axum::http::header;
+use axum::response::IntoResponse;
+use serde_json::json;
+
+use crate::state::AppState;
+
+pub async fn get_health(State(state): State<Arc<AppState>>) -> impl IntoResponse {
+    tracing::trace!("health check");
+
+    (
+        [(header::CACHE_CONTROL, "no-store")],
+        Json(json!({ "version": state.version })),
+    )
+}

envd-rs/src/http/init.rs

@@ -0,0 +1,320 @@
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use axum::Json;
+use axum::extract::State;
+use axum::http::{StatusCode, header};
+use axum::response::IntoResponse;
+use serde::Deserialize;
+
+use crate::state::AppState;
+
+#[derive(Deserialize, Default)]
+pub struct InitRequest {
+    #[serde(rename = "access_token")]
+    pub access_token: Option<String>,
+    #[serde(rename = "defaultUser")]
+    pub default_user: Option<String>,
+    #[serde(rename = "defaultWorkdir")]
+    pub default_workdir: Option<String>,
+    #[serde(rename = "envVars")]
+    pub env_vars: Option<HashMap<String, String>>,
+    #[serde(rename = "hyperloop_ip")]
+    pub hyperloop_ip: Option<String>,
+    pub timestamp: Option<String>,
+    pub sandbox_id: Option<String>,
+    pub template_id: Option<String>,
+    /// Public proxy domain (e.g. "wrenn.dev"). Used by `envd ports` to build
+    /// the {port}-{sandbox_id}.{domain} URLs.
+    pub proxy_domain: Option<String>,
+    /// New lifecycle identifier for this resume. When it changes between
+    /// /init calls, envd treats the call as a post-resume hook: the port
+    /// forwarder is restarted and the clock is stepped.
+    pub lifecycle_id: Option<String>,
+}
+
+/// POST /init — called by host agent after boot.
+pub async fn post_init(
+    State(state): State<Arc<AppState>>,
+    body: Option<Json<InitRequest>>,
+) -> impl IntoResponse {
+    let init_req = body.map(|b| b.0).unwrap_or_default();
+
+    // Validate access token if provided
+    if let Some(ref token_str) = init_req.access_token {
+        if let Err(e) = validate_init_access_token(&state, token_str).await {
+            tracing::error!(error = %e, "init: access token validation failed");
+            return (StatusCode::UNAUTHORIZED, e).into_response();
+        }
+    }
+
+    // Post-resume lifecycle hook: restart port forwarder so socat children
+    // are reaped + respawned against the new wall clock and any rotated
+    // listeners. Must run BEFORE the stale-timestamp early-return so a
+    // resume with an out-of-order timestamp still refreshes the subsystem.
+    let lifecycle_changed = if let Some(ref new_id) = init_req.lifecycle_id {
+        state.bump_lifecycle(new_id)
+    } else {
+        false
+    };
+    if lifecycle_changed {
+        // Each new lifecycle (i.e. a snapshot restore) requires a fresh memory
+        // preload pass — pages materialised before the previous pause are now
+        // back in the source memory-ranges file as the host re-restored them
+        // lazily. Reset the flags so the next POST /memory/preload kicks off
+        // a new loader instead of returning the stale "already-done".
+        //
+        // The generation bump + reset happen under the error mutex — the same
+        // critical section a loader thread publishes its result in. A loader
+        // from the PREVIOUS lifecycle can be frozen mid-walk by the pause and
+        // thaw here; the bump makes it stop and discard its result instead of
+        // storing a stale done=true that the host would trust for the next
+        // snapshot. cancel is deliberately cleared (not set): the stale thread
+        // stops on generation mismatch, and the new run must start uncancelled.
+        use std::sync::atomic::Ordering;
+        {
+            let mut err = state.mem_preload_error.lock().unwrap();
+            state.mem_preload_generation.fetch_add(1, Ordering::SeqCst);
+            state.mem_preload_cancel.store(false, Ordering::SeqCst);
+            state.mem_preload_started.store(false, Ordering::SeqCst);
+            state.reset_preload_run(&mut err);
+        }
+
+        if let Some(ref port_sub) = state.port_subsystem {
+            tracing::info!("lifecycle changed, restarting port subsystem");
+            port_sub.restart();
+        }
+        // Instant wall-clock step on resume. The host wall time arrives in
+        // init_req.timestamp; chrony's PHC refclock needs several poll cycles
+        // (poll 2 = 4s) before it has a valid offset to step to, so makestep
+        // alone leaves the clock stale for seconds after a resume. Set
+        // CLOCK_REALTIME directly here for an immediate jump, then let chronyd
+        // keep disciplining drift against /dev/ptp0.
+        if let Some(ref ts_str) = init_req.timestamp {
+            if let Ok(nanos) = parse_timestamp_to_nanos(ts_str) {
+                step_realtime_clock(nanos);
+            }
+        }
+        // Also nudge chrony to re-sync its internal offset against the
+        // now-correct clock + PHC immediately, bypassing its slew period.
+        // Best effort — the direct step above already corrected wall time.
+        tokio::spawn(async {
+            match tokio::process::Command::new("chronyc")
+                .args(["makestep"])
+                .output()
+                .await
+            {
+                Ok(out) if out.status.success() => {
+                    tracing::info!("chronyc makestep ok");
+                }
+                Ok(out) => {
+                    let stderr = String::from_utf8_lossy(&out.stderr);
+                    tracing::warn!(stderr = %stderr, "chronyc makestep failed");
+                }
+                Err(e) => {
+                    tracing::warn!(error = %e, "chronyc makestep spawn failed");
+                }
+            }
+        });
+    }
+
+    // Idempotent timestamp check. Run after lifecycle handling so a
+    // stale-timestamp /init still gets to refresh ports + step clock.
+    // The actual clock step happens in the lifecycle block above; this
+    // only gates the rest of the apply path on monotonic timestamps.
+    if let Some(ref ts_str) = init_req.timestamp {
+        if let Ok(ts) = parse_timestamp_to_nanos(ts_str) {
+            if !state.last_set_time.set_to_greater(ts) {
+                return (
+                    StatusCode::NO_CONTENT,
+                    [(header::CACHE_CONTROL, "no-store")],
+                )
+                    .into_response();
+            }
+        }
+    }
+
+    // Apply env vars
+    if let Some(ref vars) = init_req.env_vars {
+        tracing::debug!(count = vars.len(), "setting env vars");
+        for (k, v) in vars {
+            state.defaults.env_vars.insert(k.clone(), v.clone());
+        }
+    }
+
+    // Set access token
+    if let Some(ref token_str) = init_req.access_token {
+        if !token_str.is_empty() {
+            tracing::debug!("setting access token");
+            let _ = state.access_token.set(token_str.as_bytes());
+        } else if state.access_token.is_set() {
+            tracing::debug!("clearing access token");
+            state.access_token.destroy();
+        }
+    }
+
+    // Set default user
+    if let Some(ref user) = init_req.default_user {
+        if !user.is_empty() {
+            tracing::debug!(user = %user, "setting default user");
+            state.defaults.set_user(user.clone());
+        }
+    }
+
+    // Set default workdir
+    if let Some(ref workdir) = init_req.default_workdir {
+        if !workdir.is_empty() {
+            tracing::debug!(workdir = %workdir, "setting default workdir");
+            state.defaults.set_workdir(Some(workdir.clone()));
+        }
+    }
+
+    // Hyperloop /etc/hosts setup. Awaited so callers that immediately
+    // resolve events.wrenn.local see the entry. Cheap (two file ops).
+    if let Some(ref ip) = init_req.hyperloop_ip {
+        setup_hyperloop(ip, &state.defaults.env_vars).await;
+    }
+
+    // Set sandbox/template metadata from request body. Deliberately NOT
+    // written into envd's own process environment: std::env::set_var is
+    // undefined behavior with the multi-threaded runtime live (concurrent
+    // getenv from any thread races the environ rewrite), and nothing needs
+    // it there — spawned processes get these via defaults.env_vars, and
+    // out-of-band consumers (e.g. the `envd ports` subcommand's
+    // read_identity) fall back to the run files.
+    if let Some(ref id) = init_req.sandbox_id {
+        tracing::debug!(sandbox_id = %id, "setting sandbox ID from init request");
+        write_run_file(".WRENN_SANDBOX_ID", id);
+        state
+            .defaults
+            .env_vars
+            .insert("WRENN_SANDBOX_ID".into(), id.clone());
+    }
+    if let Some(ref id) = init_req.template_id {
+        tracing::debug!(template_id = %id, "setting template ID from init request");
+        write_run_file(".WRENN_TEMPLATE_ID", id);
+        state
+            .defaults
+            .env_vars
+            .insert("WRENN_TEMPLATE_ID".into(), id.clone());
+    }
+    if let Some(ref domain) = init_req.proxy_domain {
+        if !domain.is_empty() {
+            tracing::debug!(proxy_domain = %domain, "setting proxy domain from init request");
+            write_run_file(".WRENN_PROXY_DOMAIN", domain);
+            state
+                .defaults
+                .env_vars
+                .insert("WRENN_PROXY_DOMAIN".into(), domain.clone());
+        }
+    }
+
+    (
+        StatusCode::NO_CONTENT,
+        [(header::CACHE_CONTROL, "no-store")],
+    )
+        .into_response()
+}
+
+async fn validate_init_access_token(state: &AppState, request_token: &str) -> Result<(), String> {
+    // Fast path: matches existing token
+    if state.access_token.is_set()
+        && !request_token.is_empty()
+        && state.access_token.equals(request_token)
+    {
+        return Ok(());
+    }
+
+    // First-time setup: no existing token
+    if !state.access_token.is_set() {
+        return Ok(());
+    }
+
+    if request_token.is_empty() {
+        return Err("access token reset not authorized".into());
+    }
+
+    Err("access token validation failed".into())
+}
+
+async fn setup_hyperloop(address: &str, env_vars: &dashmap::DashMap<String, String>) {
+    // Reject anything that is not a bare IP address before it reaches
+    // /etc/hosts. Without this, a newline in `address` would inject arbitrary
+    // additional host entries into the file.
+    if address.parse::<std::net::IpAddr>().is_err() {
+        tracing::error!(%address, "hyperloop address is not a valid IP; skipping /etc/hosts entry");
+        return;
+    }
+
+    // Write to /etc/hosts: events.wrenn.local → address
+    let entry = format!("{address} events.wrenn.local\n");
+
+    match std::fs::read_to_string("/etc/hosts") {
+        Ok(contents) => {
+            let filtered: String = contents
+                .lines()
+                .filter(|line| !line.contains("events.wrenn.local"))
+                .collect::<Vec<_>>()
+                .join("\n");
+            let new_contents = format!("{filtered}\n{entry}");
+            if let Err(e) = std::fs::write("/etc/hosts", new_contents) {
+                tracing::error!(error = %e, "failed to modify hosts file");
+                return;
+            }
+        }
+        Err(e) => {
+            tracing::error!(error = %e, "failed to read hosts file");
+            return;
+        }
+    }
+
+    env_vars.insert("WRENN_EVENTS_ADDRESS".into(), format!("http://{address}"));
+}
+
+fn write_run_file(name: &str, value: &str) {
+    let dir = std::path::Path::new(crate::config::WRENN_RUN_DIR);
+    if let Err(e) = std::fs::create_dir_all(dir) {
+        tracing::warn!(error = %e, "failed to create /run/wrenn");
+        return;
+    }
+    if let Err(e) = std::fs::write(dir.join(name), value) {
+        tracing::warn!(error = %e, name, "failed to write run file");
+    }
+}
+
+/// Hard-steps CLOCK_REALTIME to `nanos` since the Unix epoch. Requires
+/// CAP_SYS_TIME, which envd has as PID 1 in the guest. Best effort — on
+/// failure the clock is left for chrony to discipline against the PHC.
+// libc::time_t is deprecated pending musl 1.2's 64-bit switch, but the
+// timespec.tv_sec field is still typed as time_t on this target.
+#[allow(deprecated)]
+fn step_realtime_clock(nanos: i64) {
+    let ts = libc::timespec {
+        tv_sec: (nanos / 1_000_000_000) as libc::time_t,
+        tv_nsec: (nanos % 1_000_000_000) as libc::c_long,
+    };
+    // SAFETY: ts is a valid timespec; CLOCK_REALTIME is settable as root.
+    let rc = unsafe { libc::clock_settime(libc::CLOCK_REALTIME, &ts) };
+    if rc != 0 {
+        tracing::warn!(error = %std::io::Error::last_os_error(),
+            "clock_settime(CLOCK_REALTIME) failed");
+    } else {
+        tracing::info!(
+            nanos,
+            "stepped CLOCK_REALTIME from host timestamp on resume"
+        );
+    }
+}
+
+/// Parses a host-provided timestamp into nanoseconds since the Unix epoch.
+/// Accepts either RFC3339 (`2026-05-17T16:13:03.123456Z`) or a float-seconds
+/// string (legacy callers).
+fn parse_timestamp_to_nanos(ts: &str) -> Result<i64, ()> {
+    if let Ok(parsed) = chrono::DateTime::parse_from_rfc3339(ts) {
+        return Ok(parsed.timestamp_nanos_opt().ok_or(())?);
+    }
+    if let Ok(secs) = ts.parse::<f64>() {
+        return Ok((secs * 1_000_000_000.0) as i64);
+    }
+    Err(())
+}

envd-rs/src/http/memory.rs

@@ -0,0 +1,616 @@
+// POST /memory/preload — guest-side helper that materialises every physical
+// RAM page so a subsequent ch.snapshot writes a self-contained memory-ranges
+// file. Required after a restore with memory_restore_mode=ondemand: pages
+// that were never demand-faulted live only in the source memory-ranges file
+// and would become holes (read back as zero) in the new snapshot.
+//
+// Trigger is one-byte-per-page reads through /dev/mem (fallback /proc/kcore
+// PT_LOAD segments). The guest kernel walks its direct map → accesses the
+// physical page → host kernel handles the EPT entry → CH's userfaultfd
+// handler fills the page from the source memory-ranges file.
+//
+// Wire protocol:
+//   POST /memory/preload         — starts the loader (idempotent while a run
+//                                  is in flight or completed successfully;
+//                                  restarts a run that ended failed/cancelled)
+//                                  and returns the current status JSON
+//                                  immediately
+//   GET  /memory/preload         — returns the current status JSON
+//   POST /memory/preload/cancel  — signals the loader to stop early
+//
+// Returning immediately avoids any HTTP-level header timeout in the caller
+// while materialisation (hundreds of MiB at one byte per page) runs in a
+// background blocking thread.
+
+use std::fs;
+use std::io::{Read, Seek, SeekFrom};
+use std::os::unix::fs::FileExt;
+use std::sync::Arc;
+use std::sync::atomic::Ordering;
+use std::time::Instant;
+
+use axum::Json;
+use axum::extract::State;
+use axum::http::StatusCode;
+use axum::response::IntoResponse;
+use serde::Serialize;
+
+use crate::state::AppState;
+
+const PAGE_SIZE: u64 = 4096;
+
+#[derive(Serialize, Clone)]
+pub struct PreloadStatus {
+    /// One of: "idle", "running", "done", "failed", "cancelled".
+    pub state: &'static str,
+    pub regions: u64,
+    pub pages: u64,
+    pub bytes: u64,
+    pub elapsed_sec: f64,
+    pub source: &'static str,
+    pub error: Option<String>,
+}
+
+pub async fn post_memory_preload(State(state): State<Arc<AppState>>) -> impl IntoResponse {
+    // First caller wins the CAS and spawns the loader; subsequent callers
+    // just report the existing status — EXCEPT when the previous run finished
+    // in failed/cancelled state, which may be retried. Without the retry, one
+    // transient failure would block the host's pause/snapshot gate until the
+    // next /init (which never comes while the sandbox stays running).
+    //
+    // Both the fresh-run reset and the retry check run under the error mutex
+    // — the same critical section /init's reset and the loader's result
+    // publication use — so concurrent POSTs cannot both claim a retry and a
+    // frozen /init cannot interleave.
+    // The generation MUST be captured inside the same mutex-held block as the
+    // CAS/reset: loading it after the lock drops lets an interleaving /init
+    // (bump + started=false) tag this loader with the NEW generation, and a
+    // follow-up POST would then spawn a second concurrent full-RAM walk.
+    let start_generation = {
+        let mut err = state.mem_preload_error.lock().unwrap();
+        let fresh = state
+            .mem_preload_started
+            .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst)
+            .is_ok();
+        let retry = !fresh
+            && state.mem_preload_done.load(Ordering::SeqCst)
+            && (err.is_some() || state.mem_preload_cancel.load(Ordering::SeqCst));
+        if fresh || retry {
+            // Clear leftovers (previous lifecycle's or failed run's result) so
+            // a stale done=true can't masquerade as this run's completion.
+            state.reset_preload_run(&mut err);
+            state.mem_preload_cancel.store(false, Ordering::SeqCst);
+            Some(state.mem_preload_generation.load(Ordering::SeqCst))
+        } else {
+            None
+        }
+    };
+
+    if let Some(generation) = start_generation {
+        let state_clone = Arc::clone(&state);
+        // Detached blocking thread — no axum task lifetime ties it to the
+        // request, so the connection can close immediately without aborting
+        // materialisation. Lifecycle bump on the next /init clears the flags
+        // for a fresh run after a restore; this thread stops (and refuses to
+        // publish) once the generation it captured is no longer current — a
+        // pause can freeze it mid-walk and thaw it in the NEXT lifecycle.
+        std::thread::spawn(move || {
+            let started = Instant::now();
+            let outcome = preload_blocking(&state_clone, generation);
+
+            // Publish under the error mutex so a concurrent /init bump can't
+            // interleave: either this store lands before the bump (and /init
+            // resets it), or the generation no longer matches and the result
+            // is discarded.
+            let mut err = state_clone.mem_preload_error.lock().unwrap();
+            if state_clone.mem_preload_generation.load(Ordering::SeqCst) != generation {
+                tracing::info!(
+                    generation,
+                    "memory preload result discarded: stale lifecycle"
+                );
+                return;
+            }
+            match outcome {
+                Ok((source, regions, pages, bytes)) => {
+                    let elapsed = started.elapsed().as_secs_f64();
+                    state_clone
+                        .mem_preload_regions
+                        .store(regions, Ordering::SeqCst);
+                    state_clone.mem_preload_pages.store(pages, Ordering::SeqCst);
+                    state_clone.mem_preload_bytes.store(bytes, Ordering::SeqCst);
+                    state_clone
+                        .mem_preload_elapsed_us
+                        .store((elapsed * 1_000_000.0) as u64, Ordering::SeqCst);
+                    set_source(&state_clone, source);
+                    *err = None;
+                    state_clone.mem_preload_done.store(true, Ordering::SeqCst);
+                    tracing::info!(
+                        regions,
+                        pages,
+                        bytes,
+                        elapsed_sec = elapsed,
+                        source,
+                        "memory preload complete"
+                    );
+                }
+                Err(e) => {
+                    let elapsed = started.elapsed().as_secs_f64();
+                    state_clone
+                        .mem_preload_elapsed_us
+                        .store((elapsed * 1_000_000.0) as u64, Ordering::SeqCst);
+                    *err = Some(e.clone());
+                    state_clone.mem_preload_done.store(true, Ordering::SeqCst);
+                    tracing::warn!(error = %e, "memory preload failed");
+                }
+            }
+        });
+    }
+
+    let status = read_status(&state);
+    (StatusCode::OK, Json(status))
+}
+
+pub async fn get_memory_preload(State(state): State<Arc<AppState>>) -> impl IntoResponse {
+    (StatusCode::OK, Json(read_status(&state)))
+}
+
+pub async fn post_memory_preload_cancel(State(state): State<Arc<AppState>>) -> impl IntoResponse {
+    state.mem_preload_cancel.store(true, Ordering::SeqCst);
+    StatusCode::NO_CONTENT
+}
+
+fn read_status(state: &AppState) -> PreloadStatus {
+    let started = state.mem_preload_started.load(Ordering::SeqCst);
+    let done = state.mem_preload_done.load(Ordering::SeqCst);
+    let cancelled = state.mem_preload_cancel.load(Ordering::SeqCst);
+    let error = state.mem_preload_error.lock().unwrap().clone();
+
+    let lane = if !started {
+        "idle"
+    } else if !done {
+        "running"
+    } else if let Some(_) = &error {
+        "failed"
+    } else if cancelled {
+        "cancelled"
+    } else {
+        "done"
+    };
+
+    PreloadStatus {
+        state: lane,
+        regions: state.mem_preload_regions.load(Ordering::SeqCst),
+        pages: state.mem_preload_pages.load(Ordering::SeqCst),
+        bytes: state.mem_preload_bytes.load(Ordering::SeqCst),
+        elapsed_sec: state.mem_preload_elapsed_us.load(Ordering::SeqCst) as f64 / 1_000_000.0,
+        source: get_source(state),
+        error,
+    }
+}
+
+fn set_source(state: &AppState, src: &'static str) {
+    let code: u8 = match src {
+        "/dev/mem" => 1,
+        "/proc/kcore" => 2,
+        _ => 0,
+    };
+    state.mem_preload_source.store(code, Ordering::SeqCst);
+}
+
+fn get_source(state: &AppState) -> &'static str {
+    match state.mem_preload_source.load(Ordering::SeqCst) {
+        1 => "/dev/mem",
+        2 => "/proc/kcore",
+        _ => "",
+    }
+}
+
+fn preload_blocking(
+    state: &AppState,
+    generation: u64,
+) -> Result<(&'static str, u64, u64, u64), String> {
+    let ranges = parse_system_ram_ranges().map_err(|e| format!("iomem: {e}"))?;
+    if ranges.is_empty() {
+        return Err("no System RAM ranges found in /proc/iomem".into());
+    }
+
+    let mut pages: u64 = 0;
+    let mut bytes: u64 = 0;
+
+    match preload_via_devmem(&ranges, state, generation, &mut pages, &mut bytes) {
+        Ok(()) => Ok(("/dev/mem", ranges.len() as u64, pages, bytes)),
+        Err(devmem_err) => {
+            tracing::warn!(
+                error = %devmem_err,
+                "/dev/mem preload failed, falling back to /proc/kcore"
+            );
+            pages = 0;
+            bytes = 0;
+            preload_via_kcore(state, generation, &mut pages, &mut bytes)
+                .map_err(|e| format!("/dev/mem: {devmem_err}; /proc/kcore: {e}"))?;
+            Ok(("/proc/kcore", ranges.len() as u64, pages, bytes))
+        }
+    }
+}
+
+// should_stop reports whether the walk must abort: an explicit cancel, or the
+// lifecycle moved on (a pause froze this thread and a resume /init bumped the
+// generation — continuing would fault pages nobody waits for and eventually
+// publish a stale result).
+fn should_stop(state: &AppState, generation: u64) -> bool {
+    state.mem_preload_cancel.load(Ordering::SeqCst)
+        || state.mem_preload_generation.load(Ordering::SeqCst) != generation
+}
+
+fn parse_system_ram_ranges() -> std::io::Result<Vec<(u64, u64)>> {
+    let data = fs::read_to_string("/proc/iomem")?;
+    let mut out = Vec::new();
+    for line in data.lines() {
+        if line.starts_with(|c: char| c.is_whitespace()) {
+            continue;
+        }
+        let Some((range, label)) = line.split_once(" : ") else {
+            continue;
+        };
+        if label.trim() != "System RAM" {
+            continue;
+        }
+        let Some((start, end)) = range.split_once('-') else {
+            continue;
+        };
+        let start = u64::from_str_radix(start.trim(), 16).ok();
+        let end = u64::from_str_radix(end.trim(), 16).ok();
+        if let (Some(s), Some(e)) = (start, end) {
+            out.push((s, e.saturating_add(1)));
+        }
+    }
+    Ok(out)
+}
+
+fn preload_via_devmem(
+    ranges: &[(u64, u64)],
+    state: &AppState,
+    generation: u64,
+    pages: &mut u64,
+    bytes: &mut u64,
+) -> std::io::Result<()> {
+    let f = fs::File::open("/dev/mem")?;
+    let mut buf = [0u8; 1];
+    for (start, end) in ranges {
+        let mut off = *start;
+        while off < *end {
+            if should_stop(state, generation) {
+                return Ok(());
+            }
+            f.read_at(&mut buf, off)?;
+            *pages += 1;
+            *bytes += PAGE_SIZE;
+            // Publish progress so GET /memory/preload reports useful numbers
+            // while the loader is still running.
+            if *pages % 1024 == 0 {
+                state.mem_preload_pages.store(*pages, Ordering::SeqCst);
+                state.mem_preload_bytes.store(*bytes, Ordering::SeqCst);
+            }
+            off = off.saturating_add(PAGE_SIZE);
+        }
+    }
+    Ok(())
+}
+
+// Read physical RAM through /proc/kcore's per-range direct-map segments.
+//
+// The kernel emits one KCORE_RAM PT_LOAD *per contiguous System RAM range*
+// (walk_system_ram_range), each with vaddr = direct_map_base + phys_start and
+// file_size = range size — there is NO single segment covering all of RAM.
+// Segments must therefore be matched range-by-range against /proc/iomem;
+// picking "a big kernel-space segment" instead lands on the vmalloc or
+// vmemmap region, which the kernel zero-fills for unmapped addresses without
+// ever touching a physical page — the reads "succeed" instantly and nothing
+// is materialised. Matching failure is a hard error for the same reason:
+// reading the wrong segment is indistinguishable from success.
+fn preload_via_kcore(
+    state: &AppState,
+    generation: u64,
+    pages: &mut u64,
+    bytes: &mut u64,
+) -> std::io::Result<()> {
+    let ram_ranges = parse_system_ram_ranges()?;
+    if ram_ranges.is_empty() {
+        return Err(std::io::Error::new(
+            std::io::ErrorKind::InvalidData,
+            "no System RAM ranges to bound kcore walk",
+        ));
+    }
+
+    let mut f = fs::File::open("/proc/kcore")?;
+    let segments = parse_kcore_pt_load(&mut f)?;
+    if segments.is_empty() {
+        return Err(std::io::Error::new(
+            std::io::ErrorKind::InvalidData,
+            "no PT_LOAD segments in /proc/kcore",
+        ));
+    }
+
+    let ram_segments = match_ram_segments(&ram_ranges, &segments)
+        .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
+
+    let mut buf = [0u8; 1];
+    let mut read_errors: u64 = 0;
+    for seg in &ram_segments {
+        let end = seg.file_offset.saturating_add(seg.len);
+        let mut off = seg.file_offset;
+        while off < end {
+            if should_stop(state, generation) {
+                return Ok(());
+            }
+            match f.read_at(&mut buf, off) {
+                Ok(_) => {
+                    *pages += 1;
+                    *bytes += PAGE_SIZE;
+                    if *pages % 256 == 0 {
+                        state.mem_preload_pages.store(*pages, Ordering::SeqCst);
+                        state.mem_preload_bytes.store(*bytes, Ordering::SeqCst);
+                    }
+                }
+                Err(_) => read_errors += 1,
+            }
+            off = off.saturating_add(PAGE_SIZE);
+        }
+    }
+
+    // A few failed reads are tolerable (hwpoison, offline pages); a walk where
+    // nothing was read means the segments were wrong — report it rather than
+    // letting the host trust an empty "done".
+    if *pages == 0 {
+        return Err(std::io::Error::new(
+            std::io::ErrorKind::InvalidData,
+            format!("kcore walk read no pages ({read_errors} read errors)"),
+        ));
+    }
+    if read_errors > 0 {
+        tracing::warn!(
+            read_errors,
+            pages = *pages,
+            "kcore preload skipped unreadable pages"
+        );
+    }
+    Ok(())
+}
+
+// A resolved (file_offset, length) window in /proc/kcore corresponding to one
+// System RAM range.
+struct RamSegment {
+    file_offset: u64,
+    len: u64,
+}
+
+// Match every System RAM range from /proc/iomem to its KCORE_RAM PT_LOAD
+// segment. RAM segments share a single direct-map base (vaddr = base +
+// phys_start; base is KASLR-randomised, so it must be derived, not assumed).
+// Candidate bases come from size-matched (segment, range) pairs; a base is
+// accepted only if EVERY RAM range has a segment at its expected vaddr with
+// the expected size. This can never select vmalloc/vmemmap segments: their
+// sizes (tens of TB) match no iomem range.
+//
+// Sizes are compared after clamping the iomem range to page boundaries:
+// kcore's segments are PFN-granular (walk_system_ram_range uses
+// PFN_UP/PFN_DOWN) while iomem ranges are byte-granular — the classic
+// 0x1000-0x9fbff low-RAM range is 0x9ec00 bytes in iomem but 0x9e000 in
+// kcore. Exact byte matching would reject every kernel that has such a range.
+fn match_ram_segments(
+    ranges: &[(u64, u64)],
+    segments: &[KcoreSegment],
+) -> Result<Vec<RamSegment>, String> {
+    const KERNEL_SPACE_MIN: u64 = 0xffff_8000_0000_0000;
+
+    // Page-clamp: [PFN_UP(start), PFN_DOWN(end)). Ranges smaller than one
+    // page after clamping have no kcore segment and nothing to preload.
+    let clamped: Vec<(u64, u64)> = ranges
+        .iter()
+        .map(|(start, end)| (start.next_multiple_of(PAGE_SIZE), end & !(PAGE_SIZE - 1)))
+        .filter(|(start, end)| end > start)
+        .collect();
+    if clamped.is_empty() {
+        return Err("no page-sized System RAM ranges after clamping".into());
+    }
+
+    let mut candidates: Vec<u64> = Vec::new();
+    for s in segments.iter().filter(|s| s.vaddr >= KERNEL_SPACE_MIN) {
+        for (start, end) in &clamped {
+            if s.file_size == end - start {
+                if let Some(base) = s.vaddr.checked_sub(*start) {
+                    candidates.push(base);
+                }
+            }
+        }
+    }
+    candidates.sort_unstable();
+    candidates.dedup();
+
+    let try_base = |base: u64| -> Option<Vec<RamSegment>> {
+        clamped
+            .iter()
+            .map(|(start, end)| {
+                segments
+                    .iter()
+                    .find(|s| s.vaddr == base + start && s.file_size == end - start)
+                    .map(|s| RamSegment {
+                        file_offset: s.file_offset,
+                        len: end - start,
+                    })
+            })
+            .collect()
+    };
+
+    for base in &candidates {
+        if let Some(out) = try_base(*base) {
+            return Ok(out);
+        }
+    }
+
+    Err(format!(
+        "no consistent direct-map base for {} RAM ranges across {} PT_LOAD segments \
+         ({} candidate bases tried)",
+        clamped.len(),
+        segments.len(),
+        candidates.len(),
+    ))
+}
+
+struct KcoreSegment {
+    file_offset: u64,
+    file_size: u64,
+    vaddr: u64,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const BASE: u64 = 0xffff_8880_0000_0000; // typical direct-map base, no KASLR
+    const GIB: u64 = 1 << 30;
+    const TIB: u64 = 1 << 40;
+
+    fn seg(vaddr: u64, file_size: u64, file_offset: u64) -> KcoreSegment {
+        KcoreSegment {
+            file_offset,
+            file_size,
+            vaddr,
+        }
+    }
+
+    // Typical CH guest: low RAM hole below 1MB, main range, plus the huge
+    // vmalloc/vmemmap segments that the old heuristic used to pick.
+    fn typical_segments() -> Vec<KcoreSegment> {
+        vec![
+            seg(0xffff_c900_0000_0000, 32 * TIB, 0x1000), // vmalloc
+            seg(0xffff_ea00_0000_0000, TIB, 0x2000),      // vmemmap
+            seg(BASE + 0x1000, 0x9e000, 0x10000),         // RAM 0x1000-0x9efff
+            seg(BASE + 0x100000, 2 * GIB - 0x100000, 0x20000), // RAM 1MB-2GB
+        ]
+    }
+
+    // Byte-granular, as /proc/iomem reports them: the low range ends at
+    // 0x9fbff (parse adds 1 → 0x9fc00), NOT page-aligned. kcore's segment for
+    // it is PFN-clamped to 0x9e000 bytes — matching must tolerate that.
+    fn typical_ranges() -> Vec<(u64, u64)> {
+        vec![(0x1000, 0x9fc00), (0x100000, 2 * GIB)]
+    }
+
+    #[test]
+    fn matches_all_ranges_and_skips_vmalloc() {
+        let out = match_ram_segments(&typical_ranges(), &typical_segments()).unwrap();
+        assert_eq!(out.len(), 2);
+        assert_eq!(out[0].file_offset, 0x10000);
+        assert_eq!(out[0].len, 0x9e000);
+        assert_eq!(out[1].file_offset, 0x20000);
+        assert_eq!(out[1].len, 2 * GIB - 0x100000);
+    }
+
+    #[test]
+    fn kaslr_base_is_derived_not_assumed() {
+        let kaslr = BASE + 37 * GIB; // PUD-granular randomisation
+        let segments = vec![
+            seg(0xffff_c900_0000_0000, 32 * TIB, 0x1000),
+            seg(kaslr + 0x1000, 0x9e000, 0x10000),
+            seg(kaslr + 0x100000, 2 * GIB - 0x100000, 0x20000),
+        ];
+        let out = match_ram_segments(&typical_ranges(), &segments).unwrap();
+        assert_eq!(out[1].file_offset, 0x20000);
+    }
+
+    #[test]
+    fn errors_when_a_range_has_no_segment() {
+        // Second RAM range's segment missing → no base covers all ranges.
+        let segments = vec![
+            seg(0xffff_c900_0000_0000, 32 * TIB, 0x1000),
+            seg(BASE + 0x1000, 0x9e000, 0x10000),
+        ];
+        assert!(match_ram_segments(&typical_ranges(), &segments).is_err());
+    }
+
+    #[test]
+    fn errors_instead_of_falling_back_to_vmalloc() {
+        // Only huge kernel segments present (the exact shape that fooled the
+        // old `file_size >= total_ram` heuristic).
+        let segments = vec![
+            seg(0xffff_c900_0000_0000, 32 * TIB, 0x1000),
+            seg(0xffff_ea00_0000_0000, TIB, 0x2000),
+        ];
+        assert!(match_ram_segments(&typical_ranges(), &segments).is_err());
+    }
+
+    #[test]
+    fn unaligned_range_is_page_clamped() {
+        // Range with unaligned start AND end: kcore clamps to
+        // [PFN_UP(start), PFN_DOWN(end)).
+        let ranges = vec![(0x2400, 0x9fbff + 1)];
+        let segments = vec![
+            seg(0xffff_c900_0000_0000, 32 * TIB, 0x1000),
+            seg(BASE + 0x3000, 0x9c000, 0x10000), // 0x3000..0x9f000
+        ];
+        let out = match_ram_segments(&ranges, &segments).unwrap();
+        assert_eq!(out.len(), 1);
+        assert_eq!(out[0].file_offset, 0x10000);
+        assert_eq!(out[0].len, 0x9c000);
+    }
+
+    #[test]
+    fn sub_page_range_is_skipped() {
+        // A range smaller than one page after clamping (e.g. 0x9fc00-0x9ffff)
+        // has no kcore segment; it must be dropped, not fail the match.
+        let ranges = vec![(0x9fc00, 0xa0000), (0x100000, 2 * GIB)];
+        let segments = vec![seg(BASE + 0x100000, 2 * GIB - 0x100000, 0x20000)];
+        let out = match_ram_segments(&ranges, &segments).unwrap();
+        assert_eq!(out.len(), 1);
+        assert_eq!(out[0].file_offset, 0x20000);
+    }
+
+    #[test]
+    fn ambiguous_same_size_ranges_still_resolve() {
+        // Two RAM ranges of identical size: candidate bases from cross pairs
+        // must be rejected; only the true base matches both ranges.
+        let ranges = vec![(0x0, GIB), (2 * GIB, 3 * GIB)];
+        let segments = vec![seg(BASE, GIB, 0x10000), seg(BASE + 2 * GIB, GIB, 0x20000)];
+        let out = match_ram_segments(&ranges, &segments).unwrap();
+        assert_eq!(out[0].file_offset, 0x10000);
+        assert_eq!(out[1].file_offset, 0x20000);
+    }
+}
+
+fn parse_kcore_pt_load(f: &mut fs::File) -> std::io::Result<Vec<KcoreSegment>> {
+    let mut hdr = [0u8; 64];
+    f.seek(SeekFrom::Start(0))?;
+    f.read_exact(&mut hdr)?;
+
+    if &hdr[0..4] != b"\x7fELF" || hdr[4] != 2 {
+        return Err(std::io::Error::new(
+            std::io::ErrorKind::InvalidData,
+            "not an ELF64 file",
+        ));
+    }
+
+    let e_phoff = u64::from_le_bytes(hdr[32..40].try_into().unwrap());
+    let e_phentsize = u16::from_le_bytes(hdr[54..56].try_into().unwrap()) as u64;
+    let e_phnum = u16::from_le_bytes(hdr[56..58].try_into().unwrap()) as u64;
+
+    let mut out = Vec::new();
+    let mut entry = vec![0u8; e_phentsize as usize];
+    for i in 0..e_phnum {
+        f.seek(SeekFrom::Start(e_phoff + i * e_phentsize))?;
+        f.read_exact(&mut entry)?;
+        let p_type = u32::from_le_bytes(entry[0..4].try_into().unwrap());
+        if p_type != 1 {
+            continue;
+        }
+        let p_offset = u64::from_le_bytes(entry[8..16].try_into().unwrap());
+        let p_vaddr = u64::from_le_bytes(entry[16..24].try_into().unwrap());
+        let p_filesz = u64::from_le_bytes(entry[32..40].try_into().unwrap());
+        out.push(KcoreSegment {
+            file_offset: p_offset,
+            file_size: p_filesz,
+            vaddr: p_vaddr,
+        });
+    }
+    Ok(out)
+}

envd-rs/src/http/metrics.rs

@@ -0,0 +1,89 @@
+use std::sync::Arc;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use axum::Json;
+use axum::extract::State;
+use axum::http::{StatusCode, header};
+use axum::response::IntoResponse;
+use serde::Serialize;
+
+use crate::state::AppState;
+
+#[derive(Serialize)]
+pub struct Metrics {
+    ts: i64,
+    cpu_count: u32,
+    cpu_used_pct: f32,
+    mem_total_mib: u64,
+    mem_used_mib: u64,
+    mem_total: u64,
+    mem_used: u64,
+    disk_used: u64,
+    disk_total: u64,
+}
+
+pub async fn get_metrics(State(state): State<Arc<AppState>>) -> impl IntoResponse {
+    tracing::trace!("get metrics");
+
+    match collect_metrics(&state) {
+        Ok(m) => (
+            StatusCode::OK,
+            [(header::CACHE_CONTROL, "no-store")],
+            Json(m),
+        )
+            .into_response(),
+        Err(e) => {
+            tracing::error!(error = %e, "failed to get metrics");
+            StatusCode::INTERNAL_SERVER_ERROR.into_response()
+        }
+    }
+}
+
+fn collect_metrics(state: &AppState) -> Result<Metrics, String> {
+    let cpu_count = state.cpu_count();
+    let cpu_used_pct_rounded = state.cpu_used_pct();
+
+    let mut sys = sysinfo::System::new();
+    sys.refresh_memory();
+    let mem_total = sys.total_memory();
+    let mem_available = sys.available_memory();
+    let mem_used = mem_total.saturating_sub(mem_available);
+    let mem_total_mib = mem_total / 1024 / 1024;
+    let mem_used_mib = mem_used / 1024 / 1024;
+
+    let (disk_total, disk_used) = disk_stats("/").map_err(|e| e.to_string())?;
+
+    let ts = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_secs() as i64;
+
+    Ok(Metrics {
+        ts,
+        cpu_count,
+        cpu_used_pct: cpu_used_pct_rounded,
+        mem_total_mib,
+        mem_used_mib,
+        mem_total,
+        mem_used,
+        disk_used,
+        disk_total,
+    })
+}
+
+fn disk_stats(path: &str) -> Result<(u64, u64), nix::Error> {
+    use std::ffi::CString;
+
+    let c_path = CString::new(path).unwrap();
+    let mut stat: libc::statfs = unsafe { std::mem::zeroed() };
+    let ret = unsafe { libc::statfs(c_path.as_ptr(), &mut stat) };
+    if ret != 0 {
+        return Err(nix::Error::last());
+    }
+
+    let block = stat.f_bsize as u64;
+    let total = stat.f_blocks * block;
+    let available = stat.f_bavail * block;
+
+    Ok((total, total - available))
+}

envd-rs/src/http/mod.rs

@@ -0,0 +1,69 @@
+pub mod activity;
+pub mod envs;
+pub mod error;
+pub mod files;
+pub mod health;
+pub mod init;
+pub mod memory;
+pub mod metrics;
+pub mod snapshot;
+pub mod volumes;
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use axum::Router;
+use axum::routing::{get, post};
+use http::Method;
+use http::header::{CACHE_CONTROL, HeaderName};
+use tower_http::cors::{AllowHeaders, AllowMethods, AllowOrigin, CorsLayer};
+
+use crate::config::CORS_MAX_AGE;
+use crate::state::AppState;
+
+pub fn router(state: Arc<AppState>) -> Router {
+    let cors = CorsLayer::new()
+        .allow_origin(AllowOrigin::any())
+        .allow_methods(AllowMethods::list([
+            Method::HEAD,
+            Method::GET,
+            Method::POST,
+            Method::PUT,
+            Method::PATCH,
+            Method::DELETE,
+        ]))
+        .allow_headers(AllowHeaders::any())
+        .expose_headers([
+            HeaderName::from_static("location"),
+            CACHE_CONTROL,
+            HeaderName::from_static("x-content-type-options"),
+            HeaderName::from_static("connect-content-encoding"),
+            HeaderName::from_static("connect-protocol-version"),
+            HeaderName::from_static("grpc-encoding"),
+            HeaderName::from_static("grpc-message"),
+            HeaderName::from_static("grpc-status"),
+            HeaderName::from_static("grpc-status-details-bin"),
+        ])
+        .max_age(Duration::from_secs(CORS_MAX_AGE.as_secs()));
+
+    Router::new()
+        .route("/health", get(health::get_health))
+        .route("/activity", get(activity::get_activity))
+        .route("/metrics", get(metrics::get_metrics))
+        .route("/envs", get(envs::get_envs))
+        .route("/init", post(init::post_init))
+        .route("/snapshot/prepare", post(snapshot::post_snapshot_prepare))
+        .route(
+            "/memory/preload",
+            get(memory::get_memory_preload).post(memory::post_memory_preload),
+        )
+        .route(
+            "/memory/preload/cancel",
+            post(memory::post_memory_preload_cancel),
+        )
+        .route("/files", get(files::get_files).put(files::put_files))
+        .route("/volumes/mount", post(volumes::post_mount))
+        .route("/volumes/unmount", post(volumes::post_unmount))
+        .layer(cors)
+        .with_state(state)
+}

envd-rs/src/http/snapshot.rs

@@ -0,0 +1,67 @@
+use std::sync::Arc;
+
+use axum::extract::State;
+use axum::http::{StatusCode, header};
+use axum::response::IntoResponse;
+use nix::unistd::sync;
+
+use crate::state::AppState;
+
+/// POST /snapshot/prepare — called by the host agent immediately before it
+/// invokes vm.pause + vm.snapshot. The handler quiesces guest state so the
+/// resulting snapshot is clean: outstanding writes are flushed to disk, the
+/// VFS page cache is dropped (so the dm-snapshot CoW is the source of truth),
+/// and the port forwarder is stopped to prevent socat children from being
+/// frozen mid-handshake.
+pub async fn post_snapshot_prepare(State(state): State<Arc<AppState>>) -> impl IntoResponse {
+    // Stop port forwarder + scanner so no socat process is captured in the
+    // snapshot with a half-open TCP connection. /init on resume restarts it.
+    if let Some(ref port_sub) = state.port_subsystem {
+        port_sub.stop();
+    }
+
+    // Flush in-memory FS state, then drop the VFS page cache +
+    // dentries/inodes. sync first so the pages we drop are clean; dropping
+    // reduces snapshot size by ensuring CH only persists memory pages the
+    // guest actually needs.
+    flush_and_drop_caches("first pass").await;
+
+    // Best-effort fstrim on the rootfs so unused blocks are returned to the
+    // dm-snapshot, keeping CoW size minimal.
+    let _ = tokio::process::Command::new("fstrim")
+        .arg("/")
+        .output()
+        .await;
+
+    // Second pass after fstrim: fstrim re-reads superblock / group descriptor
+    // pages that we just evicted, putting them back in the page cache. This
+    // drops those and any other late readers (e.g. sync flushers).
+    flush_and_drop_caches("second pass").await;
+
+    // No balloon settle window here: free-page reporting drains asynchronously,
+    // so any pages not yet hole-punched by the host at snapshot time are written
+    // verbatim — but with init_on_free=1 the guest zeroes them on free, and the
+    // host-side background zero-page punch reclaims them off the pause critical
+    // path. Trading a fixed ~1s of pause latency for a slightly larger artifact
+    // that the async punch later shrinks anyway.
+
+    tracing::info!("snapshot/prepare: quiesced");
+    (
+        StatusCode::NO_CONTENT,
+        [(header::CACHE_CONTROL, "no-store")],
+    )
+}
+
+// sync(2) can block for seconds flushing dirty pages, and the drop_caches
+// write blocks while the kernel evicts — both run on the blocking pool or
+// they starve every async task sharing the worker thread (health probes,
+// exec streams) for the whole quiesce window.
+async fn flush_and_drop_caches(pass: &'static str) {
+    let _ = tokio::task::spawn_blocking(move || {
+        sync();
+        if let Err(e) = std::fs::write("/proc/sys/vm/drop_caches", "3") {
+            tracing::warn!(error = %e, pass, "drop_caches failed (continuing)");
+        }
+    })
+    .await;
+}

envd-rs/src/http/volumes.rs

@@ -0,0 +1,252 @@
+use std::sync::Arc;
+use std::time::Duration;
+
+use axum::Json;
+use axum::extract::State;
+use axum::http::{StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use serde::Deserialize;
+
+use crate::state::AppState;
+
+#[derive(Deserialize)]
+pub struct MountRequest {
+    /// virtio-blk serial set by the host in the VM config; used to resolve the
+    /// block device via /sys/block/*/serial regardless of enumeration order.
+    pub serial: String,
+    /// Guest path to mount the volume at (e.g. "/mnt/vol-...").
+    pub mount_path: String,
+}
+
+#[derive(Deserialize)]
+pub struct UnmountRequest {
+    pub mount_path: String,
+}
+
+fn json_error(status: StatusCode, msg: &str) -> Response {
+    let body = serde_json::json!({ "code": status.as_u16(), "message": msg });
+    (status, Json(body)).into_response()
+}
+
+fn no_content() -> Response {
+    (
+        StatusCode::NO_CONTENT,
+        [(header::CACHE_CONTROL, "no-store")],
+    )
+        .into_response()
+}
+
+/// POST /volumes/mount — called by the host agent after boot for each attached
+/// volume. Resolves the block device by its virtio-blk serial, formats it with
+/// ext4 only if it has no filesystem yet (existing data is never reformatted),
+/// then mounts it at the requested path.
+pub async fn post_mount(
+    State(_state): State<Arc<AppState>>,
+    Json(req): Json<MountRequest>,
+) -> Response {
+    // Serials are host-generated hex tokens; reject anything else before it
+    // reaches a sysfs comparison / command argument.
+    if req.serial.is_empty() || !req.serial.chars().all(|c| c.is_ascii_alphanumeric()) {
+        return json_error(StatusCode::BAD_REQUEST, "invalid volume serial");
+    }
+    if req.mount_path.is_empty() {
+        return json_error(StatusCode::BAD_REQUEST, "mount_path is required");
+    }
+
+    let device = match resolve_device_by_serial(&req.serial).await {
+        Some(d) => d,
+        None => {
+            return json_error(
+                StatusCode::NOT_FOUND,
+                &format!("no block device with serial {}", req.serial),
+            );
+        }
+    };
+
+    // blkid exit status: 0 = a filesystem/signature is present (leave it alone),
+    // 2 = no recognized signature (format it), anything else = probe error.
+    // Tracked so the permissions of an existing volume are never touched — only
+    // a filesystem this call created gets opened up below.
+    let formatted = match has_filesystem(&device).await {
+        Ok(true) => {
+            tracing::info!(device, "volume already has a filesystem; skipping mkfs");
+            false
+        }
+        Ok(false) => {
+            if let Err(e) = mkfs_ext4(&device).await {
+                return json_error(StatusCode::INTERNAL_SERVER_ERROR, &e);
+            }
+            true
+        }
+        Err(e) => {
+            return json_error(StatusCode::INTERNAL_SERVER_ERROR, &e);
+        }
+    };
+
+    if let Err(e) = tokio::fs::create_dir_all(&req.mount_path).await {
+        return json_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("create mount dir: {e}"),
+        );
+    }
+
+    // No -t: let the kernel autodetect the filesystem, so a pre-existing
+    // non-ext4 volume still mounts.
+    match tokio::process::Command::new("mount")
+        .arg(&device)
+        .arg(&req.mount_path)
+        .output()
+        .await
+    {
+        Ok(out) if out.status.success() => {
+            if formatted {
+                open_mount_root(&req.mount_path);
+            }
+            tracing::info!(device, mount_path = %req.mount_path, "volume mounted");
+            no_content()
+        }
+        Ok(out) => {
+            let stderr = String::from_utf8_lossy(&out.stderr);
+            // Already mounted at the target is success for an idempotent retry.
+            if stderr.contains("already mounted") {
+                return no_content();
+            }
+            json_error(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                &format!("mount failed: {}", stderr.trim()),
+            )
+        }
+        Err(e) => json_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("mount command failed: {e}"),
+        ),
+    }
+}
+
+/// open_mount_root relaxes the permissions of a just-formatted volume so every
+/// user in the capsule can use it.
+///
+/// mkfs.ext4 leaves the filesystem root owned by root with mode 0755, which
+/// locks out every non-root user — including the template's default user, which
+/// is who the file API and exec run as. Without this a caller has to sudo to
+/// write to their own volume. 1777 is /tmp's mode: world-writable, with the
+/// sticky bit so one user cannot remove another's files.
+///
+/// Only ever called straight after a first-time format. Re-mounting an existing
+/// volume leaves its permissions exactly as its owner last set them.
+///
+/// Applied to the mounted root rather than the directory created before the
+/// mount — that one is hidden underneath and changing it would have no effect.
+///
+/// Best-effort: a failure here leaves a root-only volume that is still mounted
+/// and holds its data, which is not worth failing the whole capsule create over.
+fn open_mount_root(mount_path: &str) {
+    use std::os::unix::fs::PermissionsExt;
+
+    if let Err(e) = std::fs::set_permissions(mount_path, std::fs::Permissions::from_mode(0o1777)) {
+        tracing::warn!(
+            mount_path,
+            error = %e,
+            "failed to relax volume permissions; only root will be able to write to it"
+        );
+    }
+}
+
+/// POST /volumes/unmount — called best-effort before a graceful capsule destroy.
+/// Flushes buffered writes (sync) and unmounts so the backing file is
+/// consistent. Idempotent: unmounting an already-unmounted path is fine.
+pub async fn post_unmount(
+    State(_state): State<Arc<AppState>>,
+    Json(req): Json<UnmountRequest>,
+) -> Response {
+    if req.mount_path.is_empty() {
+        return json_error(StatusCode::BAD_REQUEST, "mount_path is required");
+    }
+
+    // sync flushes all filesystems, guaranteeing the volume's data reaches its
+    // backing file even if the umount below is skipped or fails.
+    let _ = tokio::task::spawn_blocking(nix::unistd::sync).await;
+
+    let _ = tokio::process::Command::new("umount")
+        .arg(&req.mount_path)
+        .output()
+        .await;
+
+    no_content()
+}
+
+/// resolve_device_by_serial finds the /dev path of the virtio-blk device whose
+/// serial matches. Polls briefly since a boot-time disk may not be fully
+/// enumerated the instant envd is asked to mount it.
+async fn resolve_device_by_serial(serial: &str) -> Option<String> {
+    for _ in 0..50 {
+        if let Some(dev) = find_block_by_serial(serial) {
+            return Some(dev);
+        }
+        tokio::time::sleep(Duration::from_millis(100)).await;
+    }
+    None
+}
+
+fn find_block_by_serial(serial: &str) -> Option<String> {
+    let entries = std::fs::read_dir("/sys/block").ok()?;
+    for entry in entries.flatten() {
+        let name = entry.file_name();
+        let name = name.to_string_lossy();
+        // Only virtio-blk devices carry a serial we set; skip loop/ram/etc.
+        if !name.starts_with("vd") {
+            continue;
+        }
+        let serial_path = format!("/sys/block/{name}/serial");
+        if let Ok(s) = std::fs::read_to_string(&serial_path) {
+            if s.trim() == serial {
+                return Some(format!("/dev/{name}"));
+            }
+        }
+    }
+    None
+}
+
+/// has_filesystem returns true when blkid detects any filesystem signature on
+/// the device. Guards mkfs so existing data is never reformatted.
+async fn has_filesystem(device: &str) -> Result<bool, String> {
+    let out = tokio::process::Command::new("blkid")
+        .arg(device)
+        .output()
+        .await
+        .map_err(|e| format!("blkid spawn failed: {e}"))?;
+    match out.status.code() {
+        // 0 with output = a signature was printed. Guard on the output too so a
+        // blkid variant that always exits 0 (e.g. busybox) is handled: empty
+        // output means no filesystem.
+        Some(0) => Ok(!String::from_utf8_lossy(&out.stdout).trim().is_empty()),
+        // util-linux blkid: 2 = nothing detected.
+        Some(2) => Ok(false),
+        // 4 (usage) / 8 (error) / signal — treat as a probe failure.
+        other => Err(format!(
+            "blkid probe failed (exit {:?}): {}",
+            other,
+            String::from_utf8_lossy(&out.stderr).trim()
+        )),
+    }
+}
+
+async fn mkfs_ext4(device: &str) -> Result<(), String> {
+    // -F: the target is a whole virtio-blk device, not a partition; without it
+    // mkfs.ext4 prompts and would hang. Safe here — only reached when blkid
+    // found no existing signature.
+    let out = tokio::process::Command::new("mkfs.ext4")
+        .args(["-q", "-F", device])
+        .output()
+        .await
+        .map_err(|e| format!("mkfs.ext4 spawn failed: {e}"))?;
+    if out.status.success() {
+        tracing::info!(device, "formatted volume with ext4");
+        Ok(())
+    } else {
+        Err(format!(
+            "mkfs.ext4 failed: {}",
+            String::from_utf8_lossy(&out.stderr).trim()
+        ))
+    }
+}

envd-rs/src/logging.rs

@@ -0,0 +1,17 @@
+use tracing_subscriber::{EnvFilter, fmt, layer::SubscriberExt, util::SubscriberInitExt};
+
+pub fn init(json: bool) {
+    let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info"));
+
+    if json {
+        tracing_subscriber::registry()
+            .with(filter)
+            .with(fmt::layer().json().flatten_event(true))
+            .init();
+    } else {
+        tracing_subscriber::registry()
+            .with(filter)
+            .with(fmt::layer())
+            .init();
+    }
+}

envd-rs/src/main.rs

@@ -0,0 +1,260 @@
+#![allow(dead_code)]
+
+mod auth;
+mod cgroups;
+mod cmd;
+mod config;
+mod conntracker;
+mod crypto;
+mod execcontext;
+mod http;
+mod logging;
+mod permissions;
+mod port;
+mod rpc;
+mod state;
+mod util;
+
+use std::fs;
+use std::net::SocketAddr;
+use std::path::Path;
+use std::sync::Arc;
+
+use clap::Parser;
+use tokio::net::TcpListener;
+
+use config::{DEFAULT_PORT, DEFAULT_USER, WRENN_RUN_DIR};
+use execcontext::Defaults;
+use port::subsystem::PortSubsystem;
+use state::AppState;
+
+const VERSION: &str = env!("CARGO_PKG_VERSION");
+
+const COMMIT: &str = {
+    match option_env!("ENVD_COMMIT") {
+        Some(c) => c,
+        None => "unknown",
+    }
+};
+
+#[derive(Parser)]
+#[command(name = "envd", about = "Wrenn guest agent daemon")]
+struct Cli {
+    /// Client subcommand. When omitted, envd runs as the guest daemon.
+    #[command(subcommand)]
+    command: Option<Commands>,
+
+    #[arg(long, default_value_t = DEFAULT_PORT)]
+    port: u16,
+
+    #[arg(long)]
+    version: bool,
+
+    #[arg(long)]
+    commit: bool,
+
+    #[arg(long = "cmd", default_value = "")]
+    start_cmd: String,
+
+    #[arg(long = "cgroup-root", default_value = "/sys/fs/cgroup")]
+    cgroup_root: String,
+}
+
+#[derive(clap::Subcommand)]
+enum Commands {
+    /// List externally-reachable open ports and the URL each is served at.
+    Ports(cmd::ports::PortsArgs),
+}
+
+#[tokio::main]
+async fn main() {
+    let cli = Cli::parse();
+
+    if cli.version {
+        println!("{VERSION}");
+        return;
+    }
+    if cli.commit {
+        println!("{COMMIT}");
+        return;
+    }
+
+    // Client subcommands are short-lived: run and exit before any daemon setup.
+    if let Some(Commands::Ports(args)) = &cli.command {
+        std::process::exit(cmd::ports::run(args));
+    }
+
+    logging::init(true);
+
+    if let Err(e) = fs::create_dir_all(WRENN_RUN_DIR) {
+        tracing::error!(error = %e, "failed to create wrenn run directory");
+    }
+
+    let defaults = Defaults::new(DEFAULT_USER);
+    defaults
+        .env_vars
+        .insert("WRENN_SANDBOX".into(), "true".into());
+
+    let wrenn_sandbox_path = Path::new(WRENN_RUN_DIR).join(".WRENN_SANDBOX");
+    if let Err(e) = fs::write(&wrenn_sandbox_path, b"true") {
+        tracing::error!(error = %e, "failed to write sandbox file");
+    }
+
+    // Cgroup manager
+    let cgroup_manager: Arc<dyn cgroups::CgroupManager> = match cgroups::Cgroup2Manager::new(
+        &cli.cgroup_root,
+        &[
+            (
+                cgroups::ProcessType::Pty,
+                "wrenn/pty",
+                &[] as &[(&str, &str)],
+            ),
+            (
+                cgroups::ProcessType::User,
+                "wrenn/user",
+                &[] as &[(&str, &str)],
+            ),
+            (
+                cgroups::ProcessType::Socat,
+                "wrenn/socat",
+                &[] as &[(&str, &str)],
+            ),
+        ],
+    ) {
+        Ok(m) => {
+            tracing::info!("cgroup2 manager initialized");
+            Arc::new(m)
+        }
+        Err(e) => {
+            tracing::warn!(error = %e, "cgroup2 init failed, using noop");
+            Arc::new(cgroups::NoopCgroupManager)
+        }
+    };
+
+    // Port subsystem
+    let port_subsystem = Arc::new(PortSubsystem::new(Arc::clone(&cgroup_manager)));
+    port_subsystem.start();
+    tracing::info!("port subsystem started");
+
+    let state = AppState::new(
+        defaults,
+        VERSION.to_string(),
+        COMMIT.to_string(),
+        Some(Arc::clone(&port_subsystem)),
+    );
+
+    // Memory reclaimer — drop page cache when available memory is low.
+    // The balloon device can only reclaim pages the guest kernel freed.
+    {
+        let state_for_reclaimer = Arc::clone(&state);
+        std::thread::spawn(move || memory_reclaimer(state_for_reclaimer));
+    }
+
+    // RPC services (Connect protocol — serves Connect + gRPC + gRPC-Web on same port)
+    let connect_router = rpc::rpc_router(Arc::clone(&state));
+
+    let app = http::router(Arc::clone(&state)).fallback_service(connect_router.into_axum_service());
+
+    // --cmd: spawn initial process if specified
+    if !cli.start_cmd.is_empty() {
+        let cmd = cli.start_cmd.clone();
+        let state_clone = Arc::clone(&state);
+        tokio::spawn(async move {
+            spawn_initial_command(&cmd, &state_clone);
+        });
+    }
+
+    let addr = SocketAddr::from(([0, 0, 0, 0], cli.port));
+    tracing::info!(
+        port = cli.port,
+        version = VERSION,
+        commit = COMMIT,
+        "envd starting"
+    );
+
+    let listener = TcpListener::bind(addr).await.expect("failed to bind");
+
+    let graceful = axum::serve(listener, app).with_graceful_shutdown(async move {
+        tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
+            .expect("failed to register SIGTERM")
+            .recv()
+            .await;
+        tracing::info!("SIGTERM received, shutting down");
+    });
+
+    if let Err(e) = graceful.await {
+        tracing::error!(error = %e, "server error");
+    }
+
+    port_subsystem.stop();
+}
+
+fn spawn_initial_command(cmd: &str, state: &AppState) {
+    use crate::permissions::user::lookup_user;
+    use crate::rpc::process_handler;
+    use std::collections::HashMap;
+
+    let default_user = state.defaults.user();
+    let user = match lookup_user(&default_user) {
+        Ok(u) => u,
+        Err(e) => {
+            tracing::error!(error = %e, "cmd: failed to lookup user");
+            return;
+        }
+    };
+
+    let home = user.dir.to_string_lossy().to_string();
+    let default_workdir = state.defaults.workdir();
+    let cwd = default_workdir.as_deref().unwrap_or(&home);
+
+    match process_handler::spawn_process(
+        cmd,
+        &[],
+        &HashMap::new(),
+        cwd,
+        None,
+        false,
+        Some("init-cmd".to_string()),
+        &user,
+        &state.defaults.env_vars,
+    ) {
+        Ok(spawned) => {
+            tracing::info!(pid = spawned.handle.pid, cmd, "initial command spawned");
+        }
+        Err(e) => {
+            tracing::error!(error = %e, cmd, "failed to spawn initial command");
+        }
+    }
+}
+
+fn memory_reclaimer(_state: Arc<AppState>) {
+    use std::time::Duration;
+
+    const CHECK_INTERVAL: Duration = Duration::from_secs(10);
+    const DROP_THRESHOLD_PCT: u64 = 80;
+
+    loop {
+        std::thread::sleep(CHECK_INTERVAL);
+
+        let mut sys = sysinfo::System::new();
+        sys.refresh_memory();
+        let total = sys.total_memory();
+        let available = sys.available_memory();
+
+        if total == 0 {
+            continue;
+        }
+
+        let used_pct = ((total - available) * 100) / total;
+        if used_pct >= DROP_THRESHOLD_PCT {
+            if let Err(e) = std::fs::write("/proc/sys/vm/drop_caches", "3") {
+                tracing::debug!(error = %e, "drop_caches failed");
+            } else {
+                let mut sys2 = sysinfo::System::new();
+                sys2.refresh_memory();
+                let freed_mb = sys2.available_memory().saturating_sub(available) / (1024 * 1024);
+                tracing::info!(used_pct, freed_mb, "page cache dropped");
+            }
+        }
+    }
+}

envd-rs/src/permissions/mod.rs

@@ -0,0 +1,2 @@
+pub mod path;
+pub mod user;

envd-rs/src/permissions/path.rs

@@ -0,0 +1,238 @@
+use std::fs;
+use std::os::unix::fs::chown;
+use std::path::{Path, PathBuf};
+
+use nix::unistd::{Gid, Uid};
+
+pub(crate) fn expand_tilde(path: &str, home_dir: &str) -> Result<String, String> {
+    if path.is_empty() || !path.starts_with('~') {
+        return Ok(path.to_string());
+    }
+    if path.len() > 1 && path.as_bytes()[1] != b'/' && path.as_bytes()[1] != b'\\' {
+        return Err("cannot expand user-specific home dir".into());
+    }
+    Ok(format!("{}{}", home_dir, &path[1..]))
+}
+
+pub fn expand_and_resolve(
+    path: &str,
+    home_dir: &str,
+    default_path: Option<&str>,
+) -> Result<String, String> {
+    let path = if path.is_empty() {
+        default_path.unwrap_or("").to_string()
+    } else {
+        path.to_string()
+    };
+
+    let path = expand_tilde(&path, home_dir)?;
+
+    if Path::new(&path).is_absolute() {
+        return Ok(path);
+    }
+
+    let joined = PathBuf::from(home_dir).join(&path);
+    joined
+        .canonicalize()
+        .or_else(|_| Ok(joined))
+        .map(|p| p.to_string_lossy().to_string())
+}
+
+pub fn ensure_dirs(path: &str, uid: Uid, gid: Gid) -> Result<(), String> {
+    let path = Path::new(path);
+    let mut current = PathBuf::new();
+
+    for component in path.components() {
+        current.push(component);
+        let current_str = current.to_string_lossy();
+
+        if current_str == "/" {
+            continue;
+        }
+
+        match fs::metadata(&current) {
+            Ok(meta) => {
+                if !meta.is_dir() {
+                    return Err(format!("path is a file: {current_str}"));
+                }
+            }
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+                if let Err(ce) = fs::create_dir(&current) {
+                    // Concurrent request may have created it between the stat
+                    // and here — fine as long as it's a directory now. The
+                    // winner did its own chown; don't re-chown their dir.
+                    let now_dir = fs::metadata(&current).map(|m| m.is_dir()).unwrap_or(false);
+                    if !now_dir {
+                        return Err(format!("failed to create directory {current_str}: {ce}"));
+                    }
+                } else {
+                    chown(&current, Some(uid.as_raw()), Some(gid.as_raw()))
+                        .map_err(|e| format!("failed to chown directory {current_str}: {e}"))?;
+                }
+            }
+            Err(e) => {
+                return Err(format!("failed to stat directory {current_str}: {e}"));
+            }
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // expand_tilde
+
+    #[test]
+    fn tilde_empty_passthrough() {
+        assert_eq!(expand_tilde("", "/home/u").unwrap(), "");
+    }
+
+    #[test]
+    fn tilde_no_tilde_passthrough() {
+        assert_eq!(expand_tilde("/absolute", "/home/u").unwrap(), "/absolute");
+    }
+
+    #[test]
+    fn tilde_bare() {
+        assert_eq!(expand_tilde("~", "/home/user").unwrap(), "/home/user");
+    }
+
+    #[test]
+    fn tilde_slash_path() {
+        assert_eq!(
+            expand_tilde("~/docs", "/home/user").unwrap(),
+            "/home/user/docs"
+        );
+    }
+
+    #[test]
+    fn tilde_nested() {
+        assert_eq!(expand_tilde("~/a/b/c", "/h").unwrap(), "/h/a/b/c");
+    }
+
+    #[test]
+    fn tilde_other_user_errors() {
+        assert!(expand_tilde("~bob/foo", "/home/user").is_err());
+    }
+
+    #[test]
+    fn tilde_relative_no_tilde() {
+        assert_eq!(
+            expand_tilde("relative/path", "/home/u").unwrap(),
+            "relative/path"
+        );
+    }
+
+    #[test]
+    fn tilde_cmd_like() {
+        assert_eq!(
+            expand_tilde("~/bin/myapp", "/home/user").unwrap(),
+            "/home/user/bin/myapp"
+        );
+    }
+
+    #[test]
+    fn tilde_bare_path_arg() {
+        assert_eq!(expand_tilde("~", "/home/user").unwrap(), "/home/user");
+    }
+
+    #[test]
+    fn tilde_slash_only() {
+        assert_eq!(expand_tilde("~/", "/home/u").unwrap(), "/home/u/");
+    }
+
+    #[test]
+    fn tilde_embedded_not_expanded() {
+        assert_eq!(expand_tilde("/a/~/b", "/home/u").unwrap(), "/a/~/b");
+    }
+
+    #[test]
+    fn tilde_long_home_dir() {
+        assert_eq!(
+            expand_tilde("~/code/project", "/very/long/home/directory/path").unwrap(),
+            "/very/long/home/directory/path/code/project"
+        );
+    }
+
+    // expand_and_resolve
+
+    #[test]
+    fn resolve_absolute_passthrough() {
+        assert_eq!(
+            expand_and_resolve("/abs/path", "/home", None).unwrap(),
+            "/abs/path"
+        );
+    }
+
+    #[test]
+    fn resolve_empty_uses_default() {
+        assert_eq!(
+            expand_and_resolve("", "/home", Some("/default")).unwrap(),
+            "/default"
+        );
+    }
+
+    #[test]
+    fn resolve_empty_no_default_falls_back_to_home() {
+        // Empty path with no default → joins "" with home_dir → returns home_dir
+        let result = expand_and_resolve("", "/home", None).unwrap();
+        assert_eq!(result, "/home");
+    }
+
+    #[test]
+    fn resolve_tilde_expands() {
+        assert_eq!(
+            expand_and_resolve("~/dir", "/home/u", None).unwrap(),
+            "/home/u/dir"
+        );
+    }
+
+    #[test]
+    fn resolve_relative_joins_home() {
+        let result = expand_and_resolve("subdir", "/tmp", None).unwrap();
+        // Relative path joined with home and canonicalized (or raw join on missing)
+        assert!(result.starts_with("/tmp"));
+        assert!(result.contains("subdir"));
+    }
+
+    #[test]
+    fn resolve_tilde_other_user_errors() {
+        assert!(expand_and_resolve("~bob", "/home/u", None).is_err());
+    }
+
+    // ensure_dirs
+
+    #[test]
+    fn ensure_dirs_creates_nested() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let path = tmp.path().join("a/b/c");
+        let uid = nix::unistd::getuid();
+        let gid = nix::unistd::getgid();
+        ensure_dirs(path.to_str().unwrap(), uid, gid).unwrap();
+        assert!(path.is_dir());
+    }
+
+    #[test]
+    fn ensure_dirs_existing_is_ok() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let uid = nix::unistd::getuid();
+        let gid = nix::unistd::getgid();
+        ensure_dirs(tmp.path().to_str().unwrap(), uid, gid).unwrap();
+    }
+
+    #[test]
+    fn ensure_dirs_file_in_path_errors() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let file_path = tmp.path().join("afile");
+        std::fs::write(&file_path, "").unwrap();
+        let nested = file_path.join("subdir");
+        let uid = nix::unistd::getuid();
+        let gid = nix::unistd::getgid();
+        let result = ensure_dirs(nested.to_str().unwrap(), uid, gid);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("path is a file"));
+    }
+}

envd-rs/src/permissions/user.rs

@@ -0,0 +1,32 @@
+use nix::unistd::{Gid, Group, Uid, User};
+
+pub fn lookup_user(username: &str) -> Result<User, String> {
+    User::from_name(username)
+        .map_err(|e| format!("error looking up user '{username}': {e}"))?
+        .ok_or_else(|| format!("user '{username}' not found"))
+}
+
+pub fn get_uid_gid(user: &User) -> (Uid, Gid) {
+    (user.uid, user.gid)
+}
+
+pub fn get_user_groups(user: &User) -> Vec<Gid> {
+    let c_name = std::ffi::CString::new(user.name.as_str()).unwrap();
+    nix::unistd::getgrouplist(&c_name, user.gid).unwrap_or_default()
+}
+
+pub fn lookup_username_by_uid(uid: Uid) -> String {
+    User::from_uid(uid)
+        .ok()
+        .flatten()
+        .map(|u| u.name)
+        .unwrap_or_else(|| uid.to_string())
+}
+
+pub fn lookup_groupname_by_gid(gid: Gid) -> String {
+    Group::from_gid(gid)
+        .ok()
+        .flatten()
+        .map(|g| g.name)
+        .unwrap_or_else(|| gid.to_string())
+}

envd-rs/src/port/conn.rs

@@ -0,0 +1,365 @@
+use std::io::{self, BufRead};
+
+#[derive(Debug, Clone)]
+pub struct ConnStat {
+    pub local_ip: String,
+    pub local_port: u32,
+    pub status: String,
+    pub family: u32,
+    pub inode: u64,
+}
+
+fn tcp_state_name(hex: &str) -> &'static str {
+    match hex {
+        "01" => "ESTABLISHED",
+        "02" => "SYN_SENT",
+        "03" => "SYN_RECV",
+        "04" => "FIN_WAIT1",
+        "05" => "FIN_WAIT2",
+        "06" => "TIME_WAIT",
+        "07" => "CLOSE",
+        "08" => "CLOSE_WAIT",
+        "09" => "LAST_ACK",
+        "0A" => "LISTEN",
+        "0B" => "CLOSING",
+        _ => "UNKNOWN",
+    }
+}
+
+pub fn read_tcp_connections() -> Vec<ConnStat> {
+    let mut conns = Vec::new();
+    if let Ok(c) = parse_proc_net_tcp("/proc/net/tcp", libc::AF_INET as u32) {
+        conns.extend(c);
+    }
+    if let Ok(c) = parse_proc_net_tcp("/proc/net/tcp6", libc::AF_INET6 as u32) {
+        conns.extend(c);
+    }
+    conns
+}
+
+/// Returns the TCP ports in LISTEN state that are reachable from outside the
+/// guest through the host proxy. A port qualifies when it is bound to a
+/// wildcard address (`0.0.0.0`/`::`, directly reachable on the TAP interface)
+/// or to loopback (`127.0.0.1`/`::1`, bridged to the TAP IP by the socat
+/// forwarder). Ports bound to any other specific address are not routable from
+/// the host and are excluded, as is `exclude_port` (envd's own control port).
+/// The result is deduplicated and sorted ascending.
+pub fn reachable_listening_ports(exclude_port: u32) -> Vec<u32> {
+    filter_reachable_ports(&read_tcp_connections(), exclude_port)
+}
+
+fn filter_reachable_ports(conns: &[ConnStat], exclude_port: u32) -> Vec<u32> {
+    let mut ports: Vec<u32> = conns
+        .iter()
+        .filter(|c| c.status == "LISTEN")
+        .filter(|c| is_reachable_bind(&c.local_ip))
+        .map(|c| c.local_port)
+        .filter(|p| *p != exclude_port)
+        .collect();
+    ports.sort_unstable();
+    ports.dedup();
+    ports
+}
+
+/// A bind address is reachable from the host when it is a wildcard (directly
+/// routed via the TAP interface) or loopback (socat-forwarded to the TAP IP).
+fn is_reachable_bind(ip: &str) -> bool {
+    matches!(ip, "0.0.0.0" | "::" | "127.0.0.1" | "::1")
+}
+
+fn parse_proc_net_tcp(path: &str, family: u32) -> io::Result<Vec<ConnStat>> {
+    let file = std::fs::File::open(path)?;
+    let reader = io::BufReader::new(file);
+    let mut conns = Vec::new();
+    let mut first = true;
+
+    for line in reader.lines() {
+        let line = line?;
+        if first {
+            first = false;
+            continue;
+        }
+        let line = line.trim().to_string();
+        if line.is_empty() {
+            continue;
+        }
+
+        let fields: Vec<&str> = line.split_whitespace().collect();
+        if fields.len() < 10 {
+            continue;
+        }
+
+        let (ip, port) = match parse_hex_addr(fields[1], family) {
+            Some(v) => v,
+            None => continue,
+        };
+
+        let state = tcp_state_name(fields[3]);
+
+        let inode: u64 = match fields[9].parse() {
+            Ok(v) => v,
+            Err(_) => continue,
+        };
+
+        conns.push(ConnStat {
+            local_ip: ip,
+            local_port: port,
+            status: state.to_string(),
+            family,
+            inode,
+        });
+    }
+
+    Ok(conns)
+}
+
+fn parse_hex_addr(s: &str, family: u32) -> Option<(String, u32)> {
+    let (ip_hex, port_hex) = s.split_once(':')?;
+    let port = u32::from_str_radix(port_hex, 16).ok()?;
+    let ip_bytes = hex::decode(ip_hex).ok()?;
+
+    let ip_str = if family == libc::AF_INET as u32 {
+        if ip_bytes.len() != 4 {
+            return None;
+        }
+        format!(
+            "{}.{}.{}.{}",
+            ip_bytes[3], ip_bytes[2], ip_bytes[1], ip_bytes[0]
+        )
+    } else {
+        if ip_bytes.len() != 16 {
+            return None;
+        }
+        let mut octets = [0u8; 16];
+        for i in 0..4 {
+            octets[i * 4] = ip_bytes[i * 4 + 3];
+            octets[i * 4 + 1] = ip_bytes[i * 4 + 2];
+            octets[i * 4 + 2] = ip_bytes[i * 4 + 1];
+            octets[i * 4 + 3] = ip_bytes[i * 4];
+        }
+        let addr = std::net::Ipv6Addr::from(octets);
+        addr.to_string()
+    };
+
+    Some((ip_str, port))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Write;
+
+    // tcp_state_name
+
+    #[test]
+    fn state_all_known_codes() {
+        assert_eq!(tcp_state_name("01"), "ESTABLISHED");
+        assert_eq!(tcp_state_name("02"), "SYN_SENT");
+        assert_eq!(tcp_state_name("03"), "SYN_RECV");
+        assert_eq!(tcp_state_name("04"), "FIN_WAIT1");
+        assert_eq!(tcp_state_name("05"), "FIN_WAIT2");
+        assert_eq!(tcp_state_name("06"), "TIME_WAIT");
+        assert_eq!(tcp_state_name("07"), "CLOSE");
+        assert_eq!(tcp_state_name("08"), "CLOSE_WAIT");
+        assert_eq!(tcp_state_name("09"), "LAST_ACK");
+        assert_eq!(tcp_state_name("0A"), "LISTEN");
+        assert_eq!(tcp_state_name("0B"), "CLOSING");
+    }
+
+    #[test]
+    fn state_unknown_code() {
+        assert_eq!(tcp_state_name("FF"), "UNKNOWN");
+        assert_eq!(tcp_state_name("00"), "UNKNOWN");
+    }
+
+    // parse_hex_addr
+
+    #[test]
+    fn ipv4_localhost() {
+        let (ip, port) = parse_hex_addr("0100007F:0050", libc::AF_INET as u32).unwrap();
+        assert_eq!(ip, "127.0.0.1");
+        assert_eq!(port, 80);
+    }
+
+    #[test]
+    fn ipv4_any() {
+        let (ip, port) = parse_hex_addr("00000000:0035", libc::AF_INET as u32).unwrap();
+        assert_eq!(ip, "0.0.0.0");
+        assert_eq!(port, 53);
+    }
+
+    #[test]
+    fn ipv4_real_address() {
+        // 192.168.1.1 in little-endian = 0101A8C0
+        let (ip, port) = parse_hex_addr("0101A8C0:01BB", libc::AF_INET as u32).unwrap();
+        assert_eq!(ip, "192.168.1.1");
+        assert_eq!(port, 443);
+    }
+
+    #[test]
+    fn ipv4_wrong_byte_count_returns_none() {
+        assert!(parse_hex_addr("0100:0050", libc::AF_INET as u32).is_none());
+    }
+
+    #[test]
+    fn invalid_hex_returns_none() {
+        assert!(parse_hex_addr("ZZZZZZZZ:0050", libc::AF_INET as u32).is_none());
+    }
+
+    #[test]
+    fn no_colon_returns_none() {
+        assert!(parse_hex_addr("0100007F0050", libc::AF_INET as u32).is_none());
+    }
+
+    #[test]
+    fn ipv6_loopback() {
+        // ::1 in /proc/net/tcp6 format: 00000000000000000000000001000000
+        let (ip, port) = parse_hex_addr(
+            "00000000000000000000000001000000:0035",
+            libc::AF_INET6 as u32,
+        )
+        .unwrap();
+        assert_eq!(ip, "::1");
+        assert_eq!(port, 53);
+    }
+
+    #[test]
+    fn ipv6_wrong_byte_count_returns_none() {
+        assert!(parse_hex_addr("0100007F:0050", libc::AF_INET6 as u32).is_none());
+    }
+
+    // parse_proc_net_tcp
+
+    fn write_tcp_file(content: &str) -> tempfile::NamedTempFile {
+        let mut f = tempfile::NamedTempFile::new().unwrap();
+        f.write_all(content.as_bytes()).unwrap();
+        f.flush().unwrap();
+        f
+    }
+
+    #[test]
+    fn parse_empty_file() {
+        let f = write_tcp_file(
+            "  sl  local_address rem_address   st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode\n",
+        );
+        let conns = parse_proc_net_tcp(f.path().to_str().unwrap(), libc::AF_INET as u32).unwrap();
+        assert!(conns.is_empty());
+    }
+
+    #[test]
+    fn parse_single_entry() {
+        let content = "\
+  sl  local_address rem_address   st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode
+   0: 0100007F:0050 00000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 12345 1 00000000\n";
+        let f = write_tcp_file(content);
+        let conns = parse_proc_net_tcp(f.path().to_str().unwrap(), libc::AF_INET as u32).unwrap();
+        assert_eq!(conns.len(), 1);
+        assert_eq!(conns[0].local_ip, "127.0.0.1");
+        assert_eq!(conns[0].local_port, 80);
+        assert_eq!(conns[0].status, "LISTEN");
+        assert_eq!(conns[0].inode, 12345);
+        assert_eq!(conns[0].family, libc::AF_INET as u32);
+    }
+
+    #[test]
+    fn parse_skips_malformed_rows() {
+        let content = "\
+  sl  local_address rem_address   st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode
+   0: 0100007F:0050 00000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 12345 1 00000000
+   bad line
+   1: short\n";
+        let f = write_tcp_file(content);
+        let conns = parse_proc_net_tcp(f.path().to_str().unwrap(), libc::AF_INET as u32).unwrap();
+        assert_eq!(conns.len(), 1);
+    }
+
+    #[test]
+    fn parse_multiple_entries() {
+        let content = "\
+  sl  local_address rem_address   st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode
+   0: 0100007F:0050 00000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 100 1 00000000
+   1: 00000000:01BB 00000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 200 1 00000000\n";
+        let f = write_tcp_file(content);
+        let conns = parse_proc_net_tcp(f.path().to_str().unwrap(), libc::AF_INET as u32).unwrap();
+        assert_eq!(conns.len(), 2);
+        assert_eq!(conns[0].local_port, 80);
+        assert_eq!(conns[1].local_port, 443);
+    }
+
+    #[test]
+    fn parse_nonexistent_file_errors() {
+        assert!(parse_proc_net_tcp("/nonexistent/path", libc::AF_INET as u32).is_err());
+    }
+
+    // reachable port filtering
+
+    fn conn(ip: &str, port: u32, status: &str) -> ConnStat {
+        ConnStat {
+            local_ip: ip.to_string(),
+            local_port: port,
+            status: status.to_string(),
+            family: libc::AF_INET as u32,
+            inode: 0,
+        }
+    }
+
+    #[test]
+    fn reachable_bind_accepts_wildcard_and_loopback() {
+        assert!(is_reachable_bind("0.0.0.0"));
+        assert!(is_reachable_bind("::"));
+        assert!(is_reachable_bind("127.0.0.1"));
+        assert!(is_reachable_bind("::1"));
+    }
+
+    #[test]
+    fn reachable_bind_rejects_specific_address() {
+        assert!(!is_reachable_bind("192.168.1.5"));
+        assert!(!is_reachable_bind("169.254.0.21"));
+        assert!(!is_reachable_bind("10.0.0.1"));
+    }
+
+    #[test]
+    fn filter_keeps_only_listen_state() {
+        let conns = vec![
+            conn("0.0.0.0", 8000, "LISTEN"),
+            conn("0.0.0.0", 9000, "ESTABLISHED"),
+        ];
+        assert_eq!(filter_reachable_ports(&conns, 49983), vec![8000]);
+    }
+
+    #[test]
+    fn filter_excludes_unreachable_binds() {
+        let conns = vec![
+            conn("127.0.0.1", 8000, "LISTEN"),
+            conn("169.254.0.21", 8001, "LISTEN"), // socat's own listener
+            conn("192.168.1.5", 8002, "LISTEN"),
+        ];
+        assert_eq!(filter_reachable_ports(&conns, 49983), vec![8000]);
+    }
+
+    #[test]
+    fn filter_excludes_envd_control_port() {
+        let conns = vec![
+            conn("0.0.0.0", 49983, "LISTEN"),
+            conn("0.0.0.0", 8000, "LISTEN"),
+        ];
+        assert_eq!(filter_reachable_ports(&conns, 49983), vec![8000]);
+    }
+
+    #[test]
+    fn filter_dedups_and_sorts() {
+        // Same port on IPv4 wildcard and IPv6 loopback collapses to one entry.
+        let conns = vec![
+            conn("::1", 8000, "LISTEN"),
+            conn("0.0.0.0", 8000, "LISTEN"),
+            conn("0.0.0.0", 3000, "LISTEN"),
+        ];
+        assert_eq!(filter_reachable_ports(&conns, 49983), vec![3000, 8000]);
+    }
+
+    #[test]
+    fn filter_empty_when_no_listeners() {
+        let conns = vec![conn("0.0.0.0", 8000, "ESTABLISHED")];
+        assert!(filter_reachable_ports(&conns, 49983).is_empty());
+    }
+}

envd-rs/src/port/forwarder.rs

@@ -0,0 +1,181 @@
+use std::collections::HashMap;
+use std::os::unix::process::CommandExt;
+use std::process::Command;
+use std::sync::Arc;
+
+use tokio::sync::mpsc;
+use tokio_util::sync::CancellationToken;
+
+use crate::cgroups::{CgroupManager, ProcessType};
+
+use super::conn::ConnStat;
+
+const DEFAULT_GATEWAY_IP: &str = "169.254.0.21";
+
+#[derive(PartialEq)]
+enum PortState {
+    Forward,
+    Delete,
+}
+
+struct PortToForward {
+    pid: Option<u32>,
+    inode: u64,
+    family: u32,
+    state: PortState,
+    port: u32,
+}
+
+fn family_to_ip_version(family: u32) -> u32 {
+    if family == libc::AF_INET as u32 {
+        4
+    } else if family == libc::AF_INET6 as u32 {
+        6
+    } else {
+        0
+    }
+}
+
+pub struct Forwarder {
+    cgroup_manager: Arc<dyn CgroupManager>,
+    ports: HashMap<String, PortToForward>,
+    source_ip: String,
+}
+
+impl Forwarder {
+    pub fn new(cgroup_manager: Arc<dyn CgroupManager>) -> Self {
+        Self {
+            cgroup_manager,
+            ports: HashMap::new(),
+            source_ip: DEFAULT_GATEWAY_IP.to_string(),
+        }
+    }
+
+    pub async fn start_forwarding(
+        &mut self,
+        mut rx: mpsc::Receiver<Vec<ConnStat>>,
+        cancel: CancellationToken,
+    ) {
+        loop {
+            tokio::select! {
+                _ = cancel.cancelled() => {
+                    self.stop_all();
+                    return;
+                }
+                msg = rx.recv() => {
+                    match msg {
+                        Some(conns) => self.process_scan(conns),
+                        None => {
+                            self.stop_all();
+                            return;
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    fn process_scan(&mut self, conns: Vec<ConnStat>) {
+        for ptf in self.ports.values_mut() {
+            ptf.state = PortState::Delete;
+        }
+
+        for conn in &conns {
+            let key = format!("{}-{}", conn.inode, conn.local_port);
+            if let Some(ptf) = self.ports.get_mut(&key) {
+                ptf.state = PortState::Forward;
+            } else {
+                tracing::debug!(
+                    ip = %conn.local_ip,
+                    port = conn.local_port,
+                    family = family_to_ip_version(conn.family),
+                    "detected new port on localhost"
+                );
+                let mut ptf = PortToForward {
+                    pid: None,
+                    inode: conn.inode,
+                    family: family_to_ip_version(conn.family),
+                    state: PortState::Forward,
+                    port: conn.local_port,
+                };
+                self.start_port_forwarding(&mut ptf);
+                self.ports.insert(key, ptf);
+            }
+        }
+
+        let to_stop: Vec<String> = self
+            .ports
+            .iter()
+            .filter(|(_, v)| v.state == PortState::Delete)
+            .map(|(k, _)| k.clone())
+            .collect();
+
+        for key in to_stop {
+            if let Some(ptf) = self.ports.get(&key) {
+                stop_port_forwarding(ptf);
+            }
+            self.ports.remove(&key);
+        }
+    }
+
+    fn start_port_forwarding(&self, ptf: &mut PortToForward) {
+        let listen_arg = format!(
+            "TCP4-LISTEN:{},bind={},reuseaddr,fork",
+            ptf.port, self.source_ip
+        );
+        let connect_arg = format!("TCP{}:localhost:{}", ptf.family, ptf.port);
+
+        let mut cmd = Command::new("socat");
+        cmd.args(["-d", "-d", "-d", &listen_arg, &connect_arg]);
+
+        unsafe {
+            let cgroup_fd = self.cgroup_manager.get_fd(ProcessType::Socat);
+            cmd.pre_exec(move || {
+                libc::setpgid(0, 0);
+                if let Some(fd) = cgroup_fd {
+                    let pid_str = format!("{}", libc::getpid());
+                    let tasks_path = format!("/proc/self/fd/{}/cgroup.procs", fd);
+                    let _ = std::fs::write(&tasks_path, pid_str.as_bytes());
+                }
+                Ok(())
+            });
+        }
+
+        tracing::debug!(
+            port = ptf.port,
+            inode = ptf.inode,
+            family = ptf.family,
+            source_ip = %self.source_ip,
+            "starting port forwarding"
+        );
+
+        match cmd.spawn() {
+            Ok(child) => {
+                ptf.pid = Some(child.id());
+                std::thread::spawn(move || {
+                    let mut child = child;
+                    let _ = child.wait();
+                });
+            }
+            Err(e) => {
+                tracing::error!(error = %e, port = ptf.port, "failed to start socat");
+            }
+        }
+    }
+
+    fn stop_all(&mut self) {
+        for ptf in self.ports.values() {
+            stop_port_forwarding(ptf);
+        }
+        self.ports.clear();
+    }
+}
+
+fn stop_port_forwarding(ptf: &PortToForward) {
+    if let Some(pid) = ptf.pid {
+        tracing::debug!(port = ptf.port, pid, "stopping port forwarding");
+        unsafe {
+            libc::kill(-(pid as i32), libc::SIGKILL);
+        }
+    }
+}

envd-rs/src/port/mod.rs

@@ -0,0 +1,4 @@
+pub mod conn;
+pub mod forwarder;
+pub mod scanner;
+pub mod subsystem;

envd-rs/src/port/scanner.rs

@@ -0,0 +1,81 @@
+use std::sync::{Arc, RwLock};
+use std::time::Duration;
+
+use tokio::sync::mpsc;
+use tokio_util::sync::CancellationToken;
+
+use super::conn::{ConnStat, read_tcp_connections};
+
+pub struct ScannerFilter {
+    pub ips: Vec<String>,
+    pub state: String,
+}
+
+impl ScannerFilter {
+    pub fn matches(&self, conn: &ConnStat) -> bool {
+        if self.state.is_empty() && self.ips.is_empty() {
+            return false;
+        }
+        self.ips.contains(&conn.local_ip) && self.state == conn.status
+    }
+}
+
+pub struct ScannerSubscriber {
+    pub tx: mpsc::Sender<Vec<ConnStat>>,
+    pub filter: Option<ScannerFilter>,
+}
+
+pub struct Scanner {
+    period: Duration,
+    subs: RwLock<Vec<(String, Arc<ScannerSubscriber>)>>,
+}
+
+impl Scanner {
+    pub fn new(period: Duration) -> Self {
+        Self {
+            period,
+            subs: RwLock::new(Vec::new()),
+        }
+    }
+
+    pub fn add_subscriber(
+        &self,
+        id: &str,
+        filter: Option<ScannerFilter>,
+    ) -> mpsc::Receiver<Vec<ConnStat>> {
+        let (tx, rx) = mpsc::channel(4);
+        let sub = Arc::new(ScannerSubscriber { tx, filter });
+        let mut subs = self.subs.write().unwrap();
+        subs.push((id.to_string(), sub));
+        rx
+    }
+
+    pub fn remove_subscriber(&self, id: &str) {
+        let mut subs = self.subs.write().unwrap();
+        subs.retain(|(sid, _)| sid != id);
+    }
+
+    pub async fn scan_and_broadcast(&self, cancel: CancellationToken) {
+        loop {
+            let conns = tokio::task::spawn_blocking(read_tcp_connections)
+                .await
+                .unwrap_or_default();
+
+            {
+                let subs = self.subs.read().unwrap();
+                for (_, sub) in subs.iter() {
+                    let payload = match &sub.filter {
+                        Some(f) => conns.iter().filter(|c| f.matches(c)).cloned().collect(),
+                        None => conns.clone(),
+                    };
+                    let _ = sub.tx.try_send(payload);
+                }
+            }
+
+            tokio::select! {
+                _ = cancel.cancelled() => return,
+                _ = tokio::time::sleep(self.period) => {}
+            }
+        }
+    }
+}

envd-rs/src/port/subsystem.rs

@@ -0,0 +1,78 @@
+use std::sync::Arc;
+
+use tokio_util::sync::CancellationToken;
+
+use crate::cgroups::CgroupManager;
+use crate::config::PORT_SCANNER_INTERVAL;
+
+use super::forwarder::Forwarder;
+use super::scanner::{Scanner, ScannerFilter};
+
+pub struct PortSubsystem {
+    cgroup_manager: Arc<dyn CgroupManager>,
+    cancel: std::sync::Mutex<Option<CancellationToken>>,
+}
+
+impl PortSubsystem {
+    pub fn new(cgroup_manager: Arc<dyn CgroupManager>) -> Self {
+        Self {
+            cgroup_manager,
+            cancel: std::sync::Mutex::new(None),
+        }
+    }
+
+    pub fn start(&self) {
+        let mut guard = self.cancel.lock().unwrap();
+        if guard.is_some() {
+            return;
+        }
+
+        let cancel = CancellationToken::new();
+        *guard = Some(cancel.clone());
+        drop(guard);
+
+        let cgroup_manager = Arc::clone(&self.cgroup_manager);
+        let cancel_scanner = cancel.clone();
+        let cancel_forwarder = cancel.clone();
+
+        tokio::spawn(async move {
+            let scanner = Arc::new(Scanner::new(PORT_SCANNER_INTERVAL));
+            let rx = scanner.add_subscriber(
+                "port-forwarder",
+                Some(ScannerFilter {
+                    ips: vec![
+                        "127.0.0.1".to_string(),
+                        "localhost".to_string(),
+                        "::1".to_string(),
+                    ],
+                    state: "LISTEN".to_string(),
+                }),
+            );
+
+            let scanner_clone = Arc::clone(&scanner);
+
+            let scanner_handle = tokio::spawn(async move {
+                scanner_clone.scan_and_broadcast(cancel_scanner).await;
+            });
+
+            let forwarder_handle = tokio::spawn(async move {
+                let mut forwarder = Forwarder::new(cgroup_manager);
+                forwarder.start_forwarding(rx, cancel_forwarder).await;
+            });
+
+            let _ = tokio::join!(scanner_handle, forwarder_handle);
+        });
+    }
+
+    pub fn stop(&self) {
+        let mut guard = self.cancel.lock().unwrap();
+        if let Some(cancel) = guard.take() {
+            cancel.cancel();
+        }
+    }
+
+    pub fn restart(&self) {
+        self.stop();
+        self.start();
+    }
+}

envd-rs/src/rpc/entry.rs

@@ -0,0 +1,229 @@
+use std::os::unix::fs::MetadataExt;
+use std::path::Path;
+
+use connectrpc::{ConnectError, ErrorCode};
+
+use crate::permissions::user::{lookup_groupname_by_gid, lookup_username_by_uid};
+use crate::rpc::pb::filesystem::{EntryInfo, FileType};
+use nix::unistd::{Gid, Uid};
+
+const NFS_SUPER_MAGIC: i64 = 0x6969;
+const CIFS_MAGIC: i64 = 0xFF534D42;
+const SMB_SUPER_MAGIC: i64 = 0x517B;
+const SMB2_MAGIC_NUMBER: i64 = 0xFE534D42;
+const FUSE_SUPER_MAGIC: i64 = 0x65735546;
+
+pub fn is_network_mount(path: &str) -> Result<bool, String> {
+    let c_path = std::ffi::CString::new(path).map_err(|e| e.to_string())?;
+    let mut stat: libc::statfs = unsafe { std::mem::zeroed() };
+    let ret = unsafe { libc::statfs(c_path.as_ptr(), &mut stat) };
+    if ret != 0 {
+        return Err(format!(
+            "statfs {path}: {}",
+            std::io::Error::last_os_error()
+        ));
+    }
+    let fs_type = stat.f_type as i64;
+    Ok(matches!(
+        fs_type,
+        NFS_SUPER_MAGIC | CIFS_MAGIC | SMB_SUPER_MAGIC | SMB2_MAGIC_NUMBER | FUSE_SUPER_MAGIC
+    ))
+}
+
+pub fn build_entry_info(path: &str) -> Result<EntryInfo, ConnectError> {
+    let p = Path::new(path);
+
+    let lstat = std::fs::symlink_metadata(p).map_err(|e| {
+        if e.kind() == std::io::ErrorKind::NotFound {
+            ConnectError::new(ErrorCode::NotFound, format!("file not found: {e}"))
+        } else {
+            ConnectError::new(ErrorCode::Internal, format!("error getting file info: {e}"))
+        }
+    })?;
+
+    let is_symlink = lstat.file_type().is_symlink();
+
+    let (file_type, mode, symlink_target) = if is_symlink {
+        let target = std::fs::canonicalize(p)
+            .map(|t| t.to_string_lossy().to_string())
+            .unwrap_or_else(|_| path.to_string());
+
+        let target_type = match std::fs::metadata(p) {
+            Ok(meta) => meta_to_file_type(&meta),
+            Err(_) => FileType::FILE_TYPE_UNSPECIFIED,
+        };
+
+        let target_mode = std::fs::metadata(p).map(|m| m.mode() & 0o7777).unwrap_or(0);
+
+        (target_type, target_mode, Some(target))
+    } else {
+        let ft = meta_to_file_type(&lstat);
+        let mode = lstat.mode() & 0o7777;
+        (ft, mode, None)
+    };
+
+    let uid = lstat.uid();
+    let gid = lstat.gid();
+    let owner = lookup_username_by_uid(Uid::from_raw(uid));
+    let group = lookup_groupname_by_gid(Gid::from_raw(gid));
+
+    let modified_time = {
+        let mtime_sec = lstat.mtime();
+        let mtime_nsec = lstat.mtime_nsec() as i32;
+        if mtime_sec == 0 && mtime_nsec == 0 {
+            None
+        } else {
+            Some(buffa_types::google::protobuf::Timestamp {
+                seconds: mtime_sec,
+                nanos: mtime_nsec,
+                ..Default::default()
+            })
+        }
+    };
+
+    let name = p
+        .file_name()
+        .map(|n| n.to_string_lossy().to_string())
+        .unwrap_or_default();
+
+    let permissions = format_permissions(lstat.mode());
+
+    Ok(EntryInfo {
+        name,
+        r#type: buffa::EnumValue::Known(file_type),
+        path: path.to_string(),
+        size: lstat.len() as i64,
+        mode,
+        permissions,
+        owner,
+        group,
+        modified_time: modified_time.into(),
+        symlink_target: symlink_target,
+        ..Default::default()
+    })
+}
+
+fn meta_to_file_type(meta: &std::fs::Metadata) -> FileType {
+    if meta.is_file() {
+        FileType::FILE_TYPE_FILE
+    } else if meta.is_dir() {
+        FileType::FILE_TYPE_DIRECTORY
+    } else if meta.file_type().is_symlink() {
+        FileType::FILE_TYPE_SYMLINK
+    } else {
+        FileType::FILE_TYPE_UNSPECIFIED
+    }
+}
+
+fn format_permissions(mode: u32) -> String {
+    let file_type = match mode & libc::S_IFMT {
+        libc::S_IFDIR => 'd',
+        libc::S_IFLNK => 'L',
+        libc::S_IFREG => '-',
+        libc::S_IFBLK => 'b',
+        libc::S_IFCHR => 'c',
+        libc::S_IFIFO => 'p',
+        libc::S_IFSOCK => 'S',
+        _ => '?',
+    };
+
+    let perms = mode & 0o777;
+    let mut s = String::with_capacity(10);
+    s.push(file_type);
+    for shift in [6, 3, 0] {
+        let bits = (perms >> shift) & 7;
+        s.push(if bits & 4 != 0 { 'r' } else { '-' });
+        s.push(if bits & 2 != 0 { 'w' } else { '-' });
+        s.push(if bits & 1 != 0 { 'x' } else { '-' });
+    }
+    s
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // format_permissions
+
+    #[test]
+    fn regular_file_755() {
+        assert_eq!(format_permissions(libc::S_IFREG | 0o755), "-rwxr-xr-x");
+    }
+
+    #[test]
+    fn directory_755() {
+        assert_eq!(format_permissions(libc::S_IFDIR | 0o755), "drwxr-xr-x");
+    }
+
+    #[test]
+    fn symlink_777() {
+        assert_eq!(format_permissions(libc::S_IFLNK | 0o777), "Lrwxrwxrwx");
+    }
+
+    #[test]
+    fn regular_file_000() {
+        assert_eq!(format_permissions(libc::S_IFREG | 0o000), "----------");
+    }
+
+    #[test]
+    fn regular_file_644() {
+        assert_eq!(format_permissions(libc::S_IFREG | 0o644), "-rw-r--r--");
+    }
+
+    #[test]
+    fn block_device() {
+        assert_eq!(format_permissions(libc::S_IFBLK | 0o660), "brw-rw----");
+    }
+
+    #[test]
+    fn char_device() {
+        assert_eq!(format_permissions(libc::S_IFCHR | 0o666), "crw-rw-rw-");
+    }
+
+    #[test]
+    fn fifo() {
+        assert_eq!(format_permissions(libc::S_IFIFO | 0o644), "prw-r--r--");
+    }
+
+    #[test]
+    fn socket() {
+        assert_eq!(format_permissions(libc::S_IFSOCK | 0o755), "Srwxr-xr-x");
+    }
+
+    #[test]
+    fn unknown_type() {
+        assert_eq!(format_permissions(0o755), "?rwxr-xr-x");
+    }
+
+    #[test]
+    fn setuid_in_mode_only_affects_lower_bits() {
+        // setuid (0o4755) — format_permissions masks with 0o777, so same as 0o755
+        assert_eq!(
+            format_permissions(libc::S_IFREG | 0o4755),
+            format_permissions(libc::S_IFREG | 0o755),
+        );
+    }
+
+    #[test]
+    fn output_always_10_chars() {
+        for mode in [0o000, 0o777, 0o644, 0o755, 0o4755] {
+            assert_eq!(format_permissions(libc::S_IFREG | mode).len(), 10);
+        }
+    }
+
+    // meta_to_file_type — needs real filesystem
+
+    #[test]
+    fn meta_regular_file() {
+        let f = tempfile::NamedTempFile::new().unwrap();
+        let meta = std::fs::metadata(f.path()).unwrap();
+        assert_eq!(meta_to_file_type(&meta), FileType::FILE_TYPE_FILE);
+    }
+
+    #[test]
+    fn meta_directory() {
+        let d = tempfile::TempDir::new().unwrap();
+        let meta = std::fs::metadata(d.path()).unwrap();
+        assert_eq!(meta_to_file_type(&meta), FileType::FILE_TYPE_DIRECTORY);
+    }
+}

envd-rs/src/rpc/filesystem_service.rs

@@ -0,0 +1,419 @@
+use std::path::{Path, PathBuf};
+use std::pin::Pin;
+use std::sync::{Arc, Mutex};
+
+use connectrpc::{ConnectError, Context, ErrorCode};
+use dashmap::DashMap;
+use futures::Stream;
+
+use crate::permissions::path::{ensure_dirs, expand_and_resolve};
+use crate::permissions::user::lookup_user;
+use crate::rpc::entry::build_entry_info;
+use crate::rpc::pb::filesystem::*;
+use crate::state::AppState;
+
+pub struct FilesystemServiceImpl {
+    state: Arc<AppState>,
+    watchers: DashMap<String, WatcherHandle>,
+}
+
+struct WatcherHandle {
+    events: Arc<Mutex<Vec<FilesystemEvent>>>,
+    _watcher: notify::RecommendedWatcher,
+}
+
+impl FilesystemServiceImpl {
+    pub fn new(state: Arc<AppState>) -> Self {
+        Self {
+            state,
+            watchers: DashMap::new(),
+        }
+    }
+
+    fn resolve_path(&self, path: &str) -> Result<String, ConnectError> {
+        let username = self.state.defaults.user();
+        let user = lookup_user(&username).map_err(|e| {
+            ConnectError::new(ErrorCode::Unauthenticated, format!("invalid user: {e}"))
+        })?;
+
+        let home_dir = user.dir.to_string_lossy().to_string();
+        let default_workdir = self.state.defaults.workdir();
+
+        expand_and_resolve(path, &home_dir, default_workdir.as_deref())
+            .map_err(|e| ConnectError::new(ErrorCode::InvalidArgument, e))
+    }
+}
+
+impl Filesystem for FilesystemServiceImpl {
+    async fn stat(
+        &self,
+        ctx: Context,
+        request: buffa::view::OwnedView<StatRequestView<'static>>,
+    ) -> Result<(StatResponse, Context), ConnectError> {
+        let path = self.resolve_path(request.path)?;
+        let entry = build_entry_info(&path)?;
+        Ok((
+            StatResponse {
+                entry: entry.into(),
+                ..Default::default()
+            },
+            ctx,
+        ))
+    }
+
+    async fn make_dir(
+        &self,
+        ctx: Context,
+        request: buffa::view::OwnedView<MakeDirRequestView<'static>>,
+    ) -> Result<(MakeDirResponse, Context), ConnectError> {
+        let path = self.resolve_path(request.path)?;
+
+        match std::fs::metadata(&path) {
+            Ok(meta) => {
+                if meta.is_dir() {
+                    return Err(ConnectError::new(
+                        ErrorCode::AlreadyExists,
+                        format!("directory already exists: {path}"),
+                    ));
+                }
+                return Err(ConnectError::new(
+                    ErrorCode::InvalidArgument,
+                    format!("path exists but is not a directory: {path}"),
+                ));
+            }
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
+            Err(e) => {
+                return Err(ConnectError::new(
+                    ErrorCode::Internal,
+                    format!("error getting file info: {e}"),
+                ));
+            }
+        }
+
+        let username = self.state.defaults.user();
+        let user = lookup_user(&username).map_err(|e| ConnectError::new(ErrorCode::Internal, e))?;
+
+        ensure_dirs(&path, user.uid, user.gid)
+            .map_err(|e| ConnectError::new(ErrorCode::Internal, e))?;
+
+        let entry = build_entry_info(&path)?;
+        Ok((
+            MakeDirResponse {
+                entry: entry.into(),
+                ..Default::default()
+            },
+            ctx,
+        ))
+    }
+
+    async fn r#move(
+        &self,
+        ctx: Context,
+        request: buffa::view::OwnedView<MoveRequestView<'static>>,
+    ) -> Result<(MoveResponse, Context), ConnectError> {
+        let source = self.resolve_path(request.source)?;
+        let destination = self.resolve_path(request.destination)?;
+
+        let username = self.state.defaults.user();
+        let user = lookup_user(&username).map_err(|e| ConnectError::new(ErrorCode::Internal, e))?;
+
+        if let Some(parent) = Path::new(&destination).parent() {
+            ensure_dirs(&parent.to_string_lossy(), user.uid, user.gid)
+                .map_err(|e| ConnectError::new(ErrorCode::Internal, e))?;
+        }
+
+        std::fs::rename(&source, &destination).map_err(|e| {
+            if e.kind() == std::io::ErrorKind::NotFound {
+                ConnectError::new(ErrorCode::NotFound, format!("source not found: {e}"))
+            } else {
+                ConnectError::new(ErrorCode::Internal, format!("error renaming: {e}"))
+            }
+        })?;
+
+        let entry = build_entry_info(&destination)?;
+        Ok((
+            MoveResponse {
+                entry: entry.into(),
+                ..Default::default()
+            },
+            ctx,
+        ))
+    }
+
+    async fn list_dir(
+        &self,
+        ctx: Context,
+        request: buffa::view::OwnedView<ListDirRequestView<'static>>,
+    ) -> Result<(ListDirResponse, Context), ConnectError> {
+        let mut depth = request.depth as usize;
+        if depth == 0 {
+            depth = 1;
+        }
+
+        let path = self.resolve_path(request.path)?;
+
+        // The recursive walk stats every entry (plus uid/gid lookups) — on a
+        // large tree that is seconds of blocking syscalls, so it runs on the
+        // blocking pool instead of a runtime worker thread.
+        let entries = tokio::task::spawn_blocking(move || {
+            let resolved = std::fs::canonicalize(&path).map_err(|e| {
+                if e.kind() == std::io::ErrorKind::NotFound {
+                    ConnectError::new(ErrorCode::NotFound, format!("path not found: {e}"))
+                } else {
+                    ConnectError::new(ErrorCode::Internal, format!("error resolving path: {e}"))
+                }
+            })?;
+            let resolved_str = resolved.to_string_lossy().to_string();
+
+            let meta = std::fs::metadata(&resolved).map_err(|e| {
+                ConnectError::new(ErrorCode::Internal, format!("error getting file info: {e}"))
+            })?;
+            if !meta.is_dir() {
+                return Err(ConnectError::new(
+                    ErrorCode::InvalidArgument,
+                    format!("path is not a directory: {path}"),
+                ));
+            }
+
+            walk_dir(&path, &resolved_str, depth)
+        })
+        .await
+        .map_err(|e| ConnectError::new(ErrorCode::Internal, format!("list_dir task: {e}")))??;
+        Ok((
+            ListDirResponse {
+                entries,
+                ..Default::default()
+            },
+            ctx,
+        ))
+    }
+
+    async fn remove(
+        &self,
+        ctx: Context,
+        request: buffa::view::OwnedView<RemoveRequestView<'static>>,
+    ) -> Result<(RemoveResponse, Context), ConnectError> {
+        let path = self.resolve_path(request.path)?;
+
+        // remove_dir_all recurses through the whole tree — blocking pool, not
+        // a runtime worker thread.
+        tokio::task::spawn_blocking(move || {
+            if let Err(e1) = std::fs::remove_dir_all(&path) {
+                if let Err(e2) = std::fs::remove_file(&path) {
+                    return Err(ConnectError::new(
+                        ErrorCode::Internal,
+                        format!("error removing: {e1}; also tried as file: {e2}"),
+                    ));
+                }
+            }
+            Ok(())
+        })
+        .await
+        .map_err(|e| ConnectError::new(ErrorCode::Internal, format!("remove task: {e}")))??;
+
+        Ok((
+            RemoveResponse {
+                ..Default::default()
+            },
+            ctx,
+        ))
+    }
+
+    async fn watch_dir(
+        &self,
+        _ctx: Context,
+        _request: buffa::view::OwnedView<WatchDirRequestView<'static>>,
+    ) -> Result<
+        (
+            Pin<Box<dyn Stream<Item = Result<WatchDirResponse, ConnectError>> + Send>>,
+            Context,
+        ),
+        ConnectError,
+    > {
+        Err(ConnectError::new(
+            ErrorCode::Unimplemented,
+            "watch_dir streaming not yet implemented",
+        ))
+    }
+
+    async fn create_watcher(
+        &self,
+        ctx: Context,
+        request: buffa::view::OwnedView<CreateWatcherRequestView<'static>>,
+    ) -> Result<(CreateWatcherResponse, Context), ConnectError> {
+        use notify::{RecursiveMode, Watcher};
+
+        let path = self.resolve_path(request.path)?;
+        let recursive = request.recursive;
+
+        if let Ok(true) = crate::rpc::entry::is_network_mount(&path) {
+            return Err(ConnectError::new(
+                ErrorCode::FailedPrecondition,
+                "watching network mounts is not supported",
+            ));
+        }
+
+        let watcher_id = simple_id();
+        let events: Arc<Mutex<Vec<FilesystemEvent>>> = Arc::new(Mutex::new(Vec::new()));
+        let events_cb = Arc::clone(&events);
+
+        let mut watcher =
+            notify::recommended_watcher(move |res: Result<notify::Event, notify::Error>| {
+                if let Ok(event) = res {
+                    let event_type = match event.kind {
+                        notify::EventKind::Create(_) => EventType::EVENT_TYPE_CREATE,
+                        notify::EventKind::Modify(notify::event::ModifyKind::Data(_)) => {
+                            EventType::EVENT_TYPE_WRITE
+                        }
+                        notify::EventKind::Modify(notify::event::ModifyKind::Metadata(_)) => {
+                            EventType::EVENT_TYPE_CHMOD
+                        }
+                        notify::EventKind::Remove(_) => EventType::EVENT_TYPE_REMOVE,
+                        notify::EventKind::Modify(notify::event::ModifyKind::Name(_)) => {
+                            EventType::EVENT_TYPE_RENAME
+                        }
+                        _ => return,
+                    };
+
+                    for p in &event.paths {
+                        if let Ok(mut guard) = events_cb.lock() {
+                            guard.push(FilesystemEvent {
+                                name: p.to_string_lossy().to_string(),
+                                r#type: buffa::EnumValue::Known(event_type),
+                                ..Default::default()
+                            });
+                        }
+                    }
+                }
+            })
+            .map_err(|e| {
+                ConnectError::new(
+                    ErrorCode::Internal,
+                    format!("failed to create watcher: {e}"),
+                )
+            })?;
+
+        let mode = if recursive {
+            RecursiveMode::Recursive
+        } else {
+            RecursiveMode::NonRecursive
+        };
+
+        watcher.watch(Path::new(&path), mode).map_err(|e| {
+            ConnectError::new(ErrorCode::Internal, format!("failed to watch path: {e}"))
+        })?;
+
+        self.watchers.insert(
+            watcher_id.clone(),
+            WatcherHandle {
+                events,
+                _watcher: watcher,
+            },
+        );
+
+        Ok((
+            CreateWatcherResponse {
+                watcher_id,
+                ..Default::default()
+            },
+            ctx,
+        ))
+    }
+
+    async fn get_watcher_events(
+        &self,
+        ctx: Context,
+        request: buffa::view::OwnedView<GetWatcherEventsRequestView<'static>>,
+    ) -> Result<(GetWatcherEventsResponse, Context), ConnectError> {
+        let watcher_id: &str = request.watcher_id;
+        let handle = self.watchers.get(watcher_id).ok_or_else(|| {
+            ConnectError::new(
+                ErrorCode::NotFound,
+                format!("watcher not found: {watcher_id}"),
+            )
+        })?;
+
+        let events = {
+            let mut guard = handle.events.lock().unwrap();
+            std::mem::take(&mut *guard)
+        };
+
+        Ok((
+            GetWatcherEventsResponse {
+                events,
+                ..Default::default()
+            },
+            ctx,
+        ))
+    }
+
+    async fn remove_watcher(
+        &self,
+        ctx: Context,
+        request: buffa::view::OwnedView<RemoveWatcherRequestView<'static>>,
+    ) -> Result<(RemoveWatcherResponse, Context), ConnectError> {
+        let watcher_id: &str = request.watcher_id;
+        self.watchers.remove(watcher_id);
+        Ok((
+            RemoveWatcherResponse {
+                ..Default::default()
+            },
+            ctx,
+        ))
+    }
+}
+
+fn walk_dir(
+    requested_path: &str,
+    resolved_path: &str,
+    depth: usize,
+) -> Result<Vec<EntryInfo>, ConnectError> {
+    let mut entries = Vec::new();
+    let base = Path::new(resolved_path);
+
+    for result in walkdir::WalkDir::new(resolved_path)
+        .min_depth(1)
+        .max_depth(depth)
+        .follow_links(false)
+    {
+        let dir_entry = match result {
+            Ok(e) => e,
+            Err(e) => {
+                if e.io_error()
+                    .is_some_and(|io| io.kind() == std::io::ErrorKind::NotFound)
+                {
+                    continue;
+                }
+                return Err(ConnectError::new(
+                    ErrorCode::Internal,
+                    format!("error reading directory: {e}"),
+                ));
+            }
+        };
+
+        let entry_path = dir_entry.path();
+        let mut entry = match build_entry_info(&entry_path.to_string_lossy()) {
+            Ok(e) => e,
+            Err(e) if e.code == ErrorCode::NotFound => continue,
+            Err(e) => return Err(e),
+        };
+
+        if let Ok(rel) = entry_path.strip_prefix(base) {
+            let remapped = PathBuf::from(requested_path).join(rel);
+            entry.path = remapped.to_string_lossy().to_string();
+        }
+
+        entries.push(entry);
+    }
+
+    Ok(entries)
+}
+
+fn simple_id() -> String {
+    use std::time::{SystemTime, UNIX_EPOCH};
+    let nanos = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_nanos();
+    format!("w-{nanos:x}")
+}

envd-rs/src/rpc/mod.rs

@@ -0,0 +1,26 @@
+pub mod entry;
+pub mod filesystem_service;
+pub mod pb;
+pub mod process_handler;
+pub mod process_service;
+
+use std::sync::Arc;
+
+use crate::rpc::filesystem_service::FilesystemServiceImpl;
+use crate::rpc::process_service::ProcessServiceImpl;
+use crate::state::AppState;
+
+use pb::filesystem::FilesystemExt;
+use pb::process::ProcessExt;
+
+/// Build the connect-rust Router with both RPC services registered.
+pub fn rpc_router(state: Arc<AppState>) -> connectrpc::Router {
+    let process_svc = Arc::new(ProcessServiceImpl::new(Arc::clone(&state)));
+    let filesystem_svc = Arc::new(FilesystemServiceImpl::new(Arc::clone(&state)));
+
+    let router = connectrpc::Router::new();
+    let router = process_svc.register(router);
+    let router = filesystem_svc.register(router);
+
+    router
+}

envd-rs/src/rpc/pb.rs

@@ -0,0 +1,15 @@
+#![allow(
+    dead_code,
+    non_camel_case_types,
+    unused_imports,
+    clippy::derivable_impls
+)]
+
+use ::buffa;
+use ::buffa_types;
+use ::connectrpc;
+use ::futures;
+use ::http_body;
+use ::serde;
+
+include!(concat!(env!("OUT_DIR"), "/_connectrpc.rs"));

envd-rs/src/rpc/process_handler.rs

@@ -0,0 +1,898 @@
+use std::collections::VecDeque;
+use std::io::Read;
+use std::os::fd::{AsFd, OwnedFd};
+use std::os::unix::io::{AsRawFd, RawFd};
+use std::os::unix::process::CommandExt;
+use std::process::Stdio;
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+use connectrpc::{ConnectError, ErrorCode};
+use nix::pty::{Winsize, openpty};
+use nix::sys::signal::{self, Signal};
+use nix::unistd::Pid;
+use tokio::io::Interest;
+use tokio::io::unix::AsyncFd;
+use tokio::sync::broadcast;
+
+use crate::rpc::pb::process::*;
+
+const STD_CHUNK_SIZE: usize = 32768;
+const PTY_CHUNK_SIZE: usize = 16384;
+const BROADCAST_CAPACITY: usize = 4096;
+
+// Coalescing window for output reads. After the first read of a burst we keep
+// draining whatever is already available on the fd for up to COALESCE_FLUSH_MS
+// (or until COALESCE_CAP bytes accumulate), then publish one merged chunk. This
+// collapses a full-screen TUI redraw — which the app emits as many small writes
+// — into a single stream message, cutting per-message framing/encoding overhead
+// across the whole path. Total added latency per flush is bounded by the window.
+const COALESCE_FLUSH_MS: u64 = 4;
+const COALESCE_CAP: usize = 64 * 1024;
+
+// Upper bound on the per-process output kept for replay. A late Connect gets
+// the most recent OUTPUT_LOG_CAPACITY bytes (older output is evicted) so the
+// buffer can never grow without bound for a chatty long-running process.
+const OUTPUT_LOG_CAPACITY: usize = 256 * 1024;
+
+// Bound on how long one input write may wait for the target process to drain
+// its buffer. The stdin pipe / pty master is O_NONBLOCK, so a full buffer
+// parks the writing task (never an OS thread); within this window a
+// briefly-full buffer recovers transparently, past it the write fails with
+// ResourceExhausted instead of hanging forever on a process that stopped
+// reading its input.
+const INPUT_WRITE_TIMEOUT: Duration = Duration::from_secs(5);
+
+#[derive(Clone)]
+pub enum DataEvent {
+    Stdout(Vec<u8>),
+    Stderr(Vec<u8>),
+    Pty(Vec<u8>),
+}
+
+#[derive(Clone)]
+pub struct EndEvent {
+    pub exit_code: i32,
+    pub exited: bool,
+    pub status: String,
+    pub error: Option<String>,
+}
+
+/// Bounded ring of recent output, kept so a late Connect can replay what it
+/// missed. Evicts oldest events once the retained bytes exceed the cap.
+#[derive(Default)]
+struct OutputLog {
+    events: VecDeque<DataEvent>,
+    bytes: usize,
+}
+
+impl OutputLog {
+    fn push(&mut self, ev: &DataEvent) {
+        self.bytes += ev_len(ev);
+        self.events.push_back(ev.clone());
+        while self.bytes > OUTPUT_LOG_CAPACITY {
+            match self.events.pop_front() {
+                Some(old) => self.bytes -= ev_len(&old),
+                None => break,
+            }
+        }
+    }
+
+    fn snapshot(&self) -> Vec<DataEvent> {
+        self.events.iter().cloned().collect()
+    }
+}
+
+fn ev_len(ev: &DataEvent) -> usize {
+    match ev {
+        DataEvent::Stdout(d) | DataEvent::Stderr(d) | DataEvent::Pty(d) => d.len(),
+    }
+}
+
+/// Blocking read loop that coalesces bursts: once a read returns, keep draining
+/// whatever is already available on the fd (bounded by [`COALESCE_FLUSH_MS`] and
+/// [`COALESCE_CAP`]) before handing the accumulated bytes to `publish`. A full
+/// TUI redraw — emitted by the app as many small writes — collapses into one
+/// output message instead of dozens. Latency added per flush is bounded by the
+/// window, so interactive feel is preserved even for a slow trickle of output.
+fn coalesce_read_loop<R, F>(mut reader: R, chunk_size: usize, mut publish: F)
+where
+    R: Read + AsRawFd,
+    F: FnMut(Vec<u8>),
+{
+    let fd = reader.as_raw_fd();
+    let mut rbuf = vec![0u8; chunk_size];
+    let mut acc: Vec<u8> = Vec::new();
+    loop {
+        match reader.read(&mut rbuf) {
+            Ok(0) => break,
+            Ok(n) => {
+                acc.extend_from_slice(&rbuf[..n]);
+                let deadline = Instant::now() + Duration::from_millis(COALESCE_FLUSH_MS);
+                while acc.len() < COALESCE_CAP {
+                    let remaining = deadline.saturating_duration_since(Instant::now());
+                    if remaining.is_zero() {
+                        break;
+                    }
+                    let mut pfd = libc::pollfd {
+                        fd,
+                        events: libc::POLLIN,
+                        revents: 0,
+                    };
+                    let timeout_ms = remaining.as_millis().min(i32::MAX as u128) as i32;
+                    let r = unsafe { libc::poll(&mut pfd, 1, timeout_ms) };
+                    if r < 0 {
+                        // Interrupted by a signal (envd runs as PID 1, so SIGCHLD
+                        // et al. land here): retry within the remaining window
+                        // instead of cutting the coalesce burst short.
+                        let errno = std::io::Error::last_os_error().raw_os_error();
+                        if errno == Some(libc::EINTR) {
+                            continue;
+                        }
+                        break;
+                    }
+                    if r == 0 || (pfd.revents & libc::POLLIN) == 0 {
+                        break;
+                    }
+                    match reader.read(&mut rbuf) {
+                        Ok(0) => {
+                            if !acc.is_empty() {
+                                publish(std::mem::take(&mut acc));
+                            }
+                            return;
+                        }
+                        Ok(m) => acc.extend_from_slice(&rbuf[..m]),
+                        Err(_) => break,
+                    }
+                }
+                publish(std::mem::take(&mut acc));
+            }
+            Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => {
+                // The pty master is O_NONBLOCK for the input write path and
+                // shares its file description with this reader. Wait for
+                // readability and retry; on POLLHUP/POLLERR the retried read
+                // returns 0/EIO and ends the loop.
+                let mut pfd = libc::pollfd {
+                    fd,
+                    events: libc::POLLIN,
+                    revents: 0,
+                };
+                if unsafe { libc::poll(&mut pfd, 1, -1) } < 0 {
+                    let errno = std::io::Error::last_os_error().raw_os_error();
+                    if errno != Some(libc::EINTR) {
+                        break;
+                    }
+                }
+            }
+            Err(e) if e.kind() == std::io::ErrorKind::Interrupted => {}
+            Err(_) => break,
+        }
+    }
+    if !acc.is_empty() {
+        publish(acc);
+    }
+}
+
+pub struct ProcessHandle {
+    pub config: ProcessConfig,
+    pub tag: Option<String>,
+    pub pid: u32,
+
+    data_tx: broadcast::Sender<DataEvent>,
+    end_tx: broadcast::Sender<EndEvent>,
+    ended: Mutex<Option<EndEvent>>,
+    output_log: Mutex<OutputLog>,
+
+    stdin: Mutex<Option<std::process::ChildStdin>>,
+    pty_master: Mutex<Option<std::fs::File>>,
+    // Serializes input writes so concurrent chunks land in order. A tokio
+    // mutex: a writer parked on a full buffer holds it across an await, and
+    // the next writer waits as a suspended task — no OS thread is pinned.
+    input_gate: tokio::sync::Mutex<()>,
+}
+
+impl ProcessHandle {
+    pub fn subscribe_data(&self) -> broadcast::Receiver<DataEvent> {
+        self.data_tx.subscribe()
+    }
+
+    /// Append a chunk to the replay buffer and broadcast it live, under one
+    /// lock. The shared lock is what makes [`subscribe_data_replay`] race-free:
+    /// a concurrent attach sees this chunk either in its snapshot or on its live
+    /// receiver — never both, never neither.
+    pub fn publish_data(&self, ev: DataEvent) {
+        let mut log = self.output_log.lock().unwrap();
+        log.push(&ev);
+        let _ = self.data_tx.send(ev);
+    }
+
+    /// Snapshot the buffered output and subscribe to live output atomically, so
+    /// a late Connect replays what it missed and then continues live with no gap
+    /// or duplicate across the handoff.
+    pub fn subscribe_data_replay(&self) -> (Vec<DataEvent>, broadcast::Receiver<DataEvent>) {
+        let log = self.output_log.lock().unwrap();
+        let snapshot = log.snapshot();
+        let rx = self.data_tx.subscribe();
+        (snapshot, rx)
+    }
+
+    pub fn subscribe_end(&self) -> broadcast::Receiver<EndEvent> {
+        self.end_tx.subscribe()
+    }
+
+    pub fn cached_end(&self) -> Option<EndEvent> {
+        self.ended.lock().unwrap().clone()
+    }
+
+    pub fn send_signal(&self, sig: Signal) -> Result<(), ConnectError> {
+        // Signal the whole process group (negative pid), not just the immediate
+        // /bin/sh wrapper. Otherwise children the process spawned are orphaned
+        // and keep running. Both spawn paths make the process a group leader
+        // (setsid for pty, setpgid for pipe), so pgid == pid.
+        signal::kill(Pid::from_raw(-(self.pid as i32)), sig).map_err(|e| {
+            ConnectError::new(ErrorCode::Internal, format!("error sending signal: {e}"))
+        })
+    }
+
+    pub async fn write_stdin(&self, data: &[u8]) -> Result<(), ConnectError> {
+        let _ordered = self.input_gate.lock().await;
+        // Dup the fd under the std mutex, then release it before awaiting:
+        // close_stdin stays responsive while a write is parked, and the fd
+        // stays valid for this write even if stdin is closed concurrently.
+        let fd = {
+            let guard = self.stdin.lock().unwrap();
+            match guard.as_ref() {
+                Some(stdin) => dup_writer_fd(stdin, "stdin")?,
+                None => {
+                    return Err(ConnectError::new(
+                        ErrorCode::FailedPrecondition,
+                        "stdin not enabled or closed",
+                    ));
+                }
+            }
+        };
+        write_nonblocking(fd, data, "stdin").await
+    }
+
+    pub async fn write_pty(&self, data: &[u8]) -> Result<(), ConnectError> {
+        let _ordered = self.input_gate.lock().await;
+        let fd = {
+            let guard = self.pty_master.lock().unwrap();
+            match guard.as_ref() {
+                Some(master) => dup_writer_fd(master, "pty")?,
+                None => {
+                    return Err(ConnectError::new(
+                        ErrorCode::FailedPrecondition,
+                        "pty not assigned to process",
+                    ));
+                }
+            }
+        };
+        write_nonblocking(fd, data, "pty").await
+    }
+
+    pub fn close_stdin(&self) -> Result<(), ConnectError> {
+        if self.pty_master.lock().unwrap().is_some() {
+            return Err(ConnectError::new(
+                ErrorCode::FailedPrecondition,
+                "cannot close stdin for PTY process — send Ctrl+D (0x04) instead",
+            ));
+        }
+        let mut guard = self.stdin.lock().unwrap();
+        *guard = None;
+        Ok(())
+    }
+
+    pub fn resize_pty(&self, cols: u16, rows: u16) -> Result<(), ConnectError> {
+        let guard = self.pty_master.lock().unwrap();
+        match guard.as_ref() {
+            Some(master) => {
+                use std::os::unix::io::AsRawFd;
+                let ws = libc::winsize {
+                    ws_row: rows,
+                    ws_col: cols,
+                    ws_xpixel: 0,
+                    ws_ypixel: 0,
+                };
+                let ret = unsafe { libc::ioctl(master.as_raw_fd(), libc::TIOCSWINSZ, &ws) };
+                if ret != 0 {
+                    return Err(ConnectError::new(
+                        ErrorCode::Internal,
+                        format!(
+                            "ioctl TIOCSWINSZ failed: {}",
+                            std::io::Error::last_os_error()
+                        ),
+                    ));
+                }
+                Ok(())
+            }
+            None => Err(ConnectError::new(
+                ErrorCode::FailedPrecondition,
+                "tty not assigned to process",
+            )),
+        }
+    }
+}
+
+fn dup_writer_fd(f: &impl AsFd, what: &str) -> Result<OwnedFd, ConnectError> {
+    f.as_fd()
+        .try_clone_to_owned()
+        .map_err(|e| ConnectError::new(ErrorCode::Internal, format!("dup {what} fd: {e}")))
+}
+
+/// Write `data` to a non-blocking fd from async context. Small interactive
+/// writes complete inline; a full buffer surfaces as WouldBlock and we await
+/// writability with a deadline, so a process that stopped reading its input
+/// costs a parked task — never a pinned OS thread.
+async fn write_nonblocking(fd: OwnedFd, data: &[u8], what: &str) -> Result<(), ConnectError> {
+    let afd = AsyncFd::with_interest(fd, Interest::WRITABLE)
+        .map_err(|e| ConnectError::new(ErrorCode::Internal, format!("register {what} fd: {e}")))?;
+    let deadline = tokio::time::Instant::now() + INPUT_WRITE_TIMEOUT;
+    let mut written = 0usize;
+    while written < data.len() {
+        let rest = &data[written..];
+        let n = unsafe {
+            libc::write(
+                afd.get_ref().as_raw_fd(),
+                rest.as_ptr() as *const libc::c_void,
+                rest.len(),
+            )
+        };
+        if n >= 0 {
+            written += n as usize;
+            continue;
+        }
+        let err = std::io::Error::last_os_error();
+        match err.kind() {
+            std::io::ErrorKind::WouldBlock => {
+                match tokio::time::timeout_at(deadline, afd.writable()).await {
+                    Ok(Ok(mut ready)) => ready.clear_ready(),
+                    Ok(Err(e)) => {
+                        return Err(ConnectError::new(
+                            ErrorCode::Internal,
+                            format!("error waiting for {what} to become writable: {e}"),
+                        ));
+                    }
+                    Err(_) => {
+                        return Err(ConnectError::new(
+                            ErrorCode::ResourceExhausted,
+                            format!(
+                                "{what} input buffer full ({written} of {} bytes written): process is not reading its input",
+                                data.len()
+                            ),
+                        ));
+                    }
+                }
+            }
+            std::io::ErrorKind::Interrupted => {}
+            _ => {
+                return Err(ConnectError::new(
+                    ErrorCode::Internal,
+                    format!("error writing to {what}: {err}"),
+                ));
+            }
+        }
+    }
+    Ok(())
+}
+
+fn set_nonblocking(fd: RawFd) -> std::io::Result<()> {
+    let flags = unsafe { libc::fcntl(fd, libc::F_GETFL) };
+    if flags < 0 {
+        return Err(std::io::Error::last_os_error());
+    }
+    if unsafe { libc::fcntl(fd, libc::F_SETFL, flags | libc::O_NONBLOCK) } < 0 {
+        return Err(std::io::Error::last_os_error());
+    }
+    Ok(())
+}
+
+pub struct SpawnedProcess {
+    pub handle: Arc<ProcessHandle>,
+    pub data_rx: broadcast::Receiver<DataEvent>,
+    pub end_rx: broadcast::Receiver<EndEvent>,
+}
+
+/// Switch the child to the target gid/uid, dropping supplementary groups first
+/// and checking every step. Order is load-bearing: supplementary groups must be
+/// cleared while still privileged (setgroups after setuid fails), otherwise a
+/// non-root child inherits PID 1's root supplementary groups. Checking the
+/// return values turns a failed drop into a failed spawn instead of silently
+/// executing the command as root.
+///
+/// Runs inside `pre_exec`, so it must stay async-signal-safe: raw libc calls
+/// only, no allocation.
+///
+/// When envd is not running as root (dev/test hosts), it holds no privilege to
+/// drop — `setgroups`/`setgid`/`setuid` would fail with EPERM. In that case the
+/// child already runs unprivileged as the current user, so skip the drop.
+unsafe fn switch_user(uid: libc::uid_t, gid: libc::gid_t) -> std::io::Result<()> {
+    unsafe {
+        if libc::geteuid() != 0 {
+            return Ok(());
+        }
+        if libc::setgroups(0, std::ptr::null()) != 0 {
+            return Err(std::io::Error::last_os_error());
+        }
+        if libc::setgid(gid) != 0 {
+            return Err(std::io::Error::last_os_error());
+        }
+        if libc::setuid(uid) != 0 {
+            return Err(std::io::Error::last_os_error());
+        }
+    }
+    Ok(())
+}
+
+pub fn spawn_process(
+    cmd_str: &str,
+    args: &[String],
+    envs: &std::collections::HashMap<String, String>,
+    cwd: &str,
+    pty_opts: Option<(u16, u16)>,
+    enable_stdin: bool,
+    tag: Option<String>,
+    user: &nix::unistd::User,
+    default_env_vars: &dashmap::DashMap<String, String>,
+) -> Result<SpawnedProcess, ConnectError> {
+    let mut env: Vec<(String, String)> = Vec::new();
+    env.push(("PATH".into(), std::env::var("PATH").unwrap_or_default()));
+    let home = user.dir.to_string_lossy().to_string();
+    env.push(("HOME".into(), home));
+    env.push(("USER".into(), user.name.clone()));
+    env.push(("LOGNAME".into(), user.name.clone()));
+    if !user.shell.as_os_str().is_empty() {
+        env.push(("SHELL".into(), user.shell.to_string_lossy().to_string()));
+    }
+
+    default_env_vars.iter().for_each(|entry| {
+        env.push((entry.key().clone(), entry.value().clone()));
+    });
+
+    for (k, v) in envs {
+        env.push((k.clone(), v.clone()));
+    }
+
+    // Reset the child's nice value only when envd itself was started at an
+    // elevated nice value (delta > 0 means raising the nice number / lowering
+    // priority, which is permitted for non-root processes). A non-root process
+    // cannot improve its priority, so skip the `nice` wrapper otherwise — it
+    // would fail with EPERM ("cannot set niceness: permission denied") for
+    // commands run as a non-root user. Writing 100 to the process's own
+    // oom_score_adj is always permitted (raising the score).
+    let nice_delta = 0 - current_nice();
+    let profile_source = r#"test -f /etc/profile && . /etc/profile
+test -f "${HOME}/.bashrc" && . "${HOME}/.bashrc""#;
+
+    // Resolve the user's login shell, falling back to /bin/sh. Commands without
+    // explicit args are interpreted by this shell so pipes, quoting, escape
+    // sequences, backslash line-continuations, and other shell syntax work
+    // without the caller having to wrap them in `sh -c` themselves.
+    let shell = {
+        let s = user.shell.to_string_lossy();
+        if s.is_empty() {
+            "/bin/sh".to_string()
+        } else {
+            s.to_string()
+        }
+    };
+
+    // What the wrapper finally exec's, after the optional `nice` prefix.
+    //   - no args: run cmd_str as a shell command line via the login shell
+    //     ($1 is cmd_str; $0 of the inner shell is the shell path).
+    //   - with args: exec the program + args directly, no shell interpretation
+    //     (backward-compatible program/argv form).
+    let target = if cmd_str.is_empty() && args.is_empty() {
+        // No command at all (e.g. an interactive PTY session with no explicit
+        // command): launch the user's login shell directly. Under a pty its
+        // stdin is a tty, so it starts interactively.
+        format!(r#""{shell}""#)
+    } else if args.is_empty() {
+        format!(r#""{shell}" -c "$1" "{shell}""#)
+    } else {
+        r#""$@""#.to_string()
+    };
+    let nice_prefix = if nice_delta > 0 {
+        format!("/usr/bin/nice -n {nice_delta} ")
+    } else {
+        String::new()
+    };
+    let oom_script = format!(
+        r#"echo 100 > /proc/$$/oom_score_adj
+{profile_source}
+exec {nice_prefix}{target}"#
+    );
+    let mut wrapper_args = vec![
+        "-c".to_string(),
+        oom_script,
+        "--".to_string(),
+        cmd_str.to_string(),
+    ];
+    wrapper_args.extend_from_slice(args);
+
+    let uid = user.uid.as_raw();
+    let gid = user.gid.as_raw();
+
+    let (data_tx, _) = broadcast::channel(BROADCAST_CAPACITY);
+    let (end_tx, _) = broadcast::channel(16);
+
+    let config = ProcessConfig {
+        cmd: cmd_str.to_string(),
+        args: args.to_vec(),
+        envs: envs.clone(),
+        cwd: Some(cwd.to_string()),
+        ..Default::default()
+    };
+
+    if let Some((cols, rows)) = pty_opts {
+        let pty_result = openpty(
+            Some(&Winsize {
+                ws_row: rows,
+                ws_col: cols,
+                ws_xpixel: 0,
+                ws_ypixel: 0,
+            }),
+            None,
+        )
+        .map_err(|e| ConnectError::new(ErrorCode::Internal, format!("openpty failed: {e}")))?;
+
+        let master_fd = pty_result.master;
+        let slave_fd = pty_result.slave;
+
+        let mut command = std::process::Command::new(&shell);
+        command
+            .args(&wrapper_args)
+            .env_clear()
+            .envs(env.iter().map(|(k, v)| (k.as_str(), v.as_str())))
+            .current_dir(cwd);
+
+        unsafe {
+            use std::os::unix::io::AsRawFd;
+            let slave_raw = slave_fd.as_raw_fd();
+            let master_raw = master_fd.as_raw_fd();
+            command.pre_exec(move || {
+                libc::close(master_raw);
+                nix::unistd::setsid()
+                    .map_err(|e| std::io::Error::new(std::io::ErrorKind::Other, e))?;
+                libc::ioctl(slave_raw, libc::TIOCSCTTY, 0);
+                libc::dup2(slave_raw, 0);
+                libc::dup2(slave_raw, 1);
+                libc::dup2(slave_raw, 2);
+                if slave_raw > 2 {
+                    libc::close(slave_raw);
+                }
+                switch_user(uid, gid)?;
+                Ok(())
+            });
+        }
+
+        command.stdin(Stdio::null());
+        command.stdout(Stdio::null());
+        command.stderr(Stdio::null());
+
+        let child = command.spawn().map_err(|e| {
+            ConnectError::new(
+                ErrorCode::Internal,
+                format!("error starting pty process: {e}"),
+            )
+        })?;
+
+        drop(slave_fd);
+
+        let pid = child.id();
+        let master_file: std::fs::File = master_fd.into();
+        // O_NONBLOCK is per file description, so it covers the write path and
+        // the reader clone alike; coalesce_read_loop handles the resulting
+        // WouldBlock by polling. Without it a write would block an OS thread,
+        // so treat failure as a failed spawn.
+        if let Err(e) = set_nonblocking(master_file.as_raw_fd()) {
+            let mut child = child;
+            let _ = signal::kill(Pid::from_raw(-(pid as i32)), Signal::SIGKILL);
+            let _ = child.wait();
+            return Err(ConnectError::new(
+                ErrorCode::Internal,
+                format!("set pty master non-blocking: {e}"),
+            ));
+        }
+        let master_clone = master_file.try_clone().unwrap();
+
+        let handle = Arc::new(ProcessHandle {
+            config,
+            tag,
+            pid,
+            data_tx: data_tx.clone(),
+            end_tx: end_tx.clone(),
+            ended: Mutex::new(None),
+            output_log: Mutex::new(OutputLog::default()),
+            stdin: Mutex::new(None),
+            pty_master: Mutex::new(Some(master_file)),
+            input_gate: tokio::sync::Mutex::new(()),
+        });
+
+        let data_rx = handle.subscribe_data();
+        let end_rx = handle.subscribe_end();
+
+        let handle_for_reader = Arc::clone(&handle);
+        let pty_reader = std::thread::spawn(move || {
+            coalesce_read_loop(master_clone, PTY_CHUNK_SIZE, |chunk| {
+                handle_for_reader.publish_data(DataEvent::Pty(chunk));
+            });
+        });
+
+        let end_tx_clone = end_tx.clone();
+        let handle_for_waiter = Arc::clone(&handle);
+        std::thread::spawn(move || {
+            let mut child = child;
+            let status = child.wait();
+            // Drain the pty to EOF before publishing the end event so trailing
+            // output is never lost to a process-exit/pty-read race.
+            let _ = pty_reader.join();
+            let end_event = match status {
+                Ok(s) => EndEvent {
+                    exit_code: s.code().unwrap_or(-1),
+                    exited: s.code().is_some(),
+                    status: format!("{s}"),
+                    error: None,
+                },
+                Err(e) => EndEvent {
+                    exit_code: -1,
+                    exited: false,
+                    status: "error".into(),
+                    error: Some(e.to_string()),
+                },
+            };
+            *handle_for_waiter.ended.lock().unwrap() = Some(end_event.clone());
+            let _ = end_tx_clone.send(end_event);
+        });
+
+        tracing::info!(pid, cmd = cmd_str, "process started (pty)");
+        Ok(SpawnedProcess {
+            handle,
+            data_rx,
+            end_rx,
+        })
+    } else {
+        let mut command = std::process::Command::new(&shell);
+        command
+            .args(&wrapper_args)
+            .env_clear()
+            .envs(env.iter().map(|(k, v)| (k.as_str(), v.as_str())))
+            .current_dir(cwd)
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped());
+
+        if enable_stdin {
+            command.stdin(Stdio::piped());
+        } else {
+            command.stdin(Stdio::null());
+        }
+
+        unsafe {
+            command.pre_exec(move || {
+                // Become a process-group leader so SendSignal can kill the
+                // whole group, not just this wrapper. The pty path gets this
+                // for free via setsid().
+                nix::unistd::setpgid(Pid::from_raw(0), Pid::from_raw(0))
+                    .map_err(|e| std::io::Error::new(std::io::ErrorKind::Other, e))?;
+                switch_user(uid, gid)?;
+                Ok(())
+            });
+        }
+
+        let mut child = command.spawn().map_err(|e| {
+            ConnectError::new(ErrorCode::Internal, format!("error starting process: {e}"))
+        })?;
+
+        let pid = child.id();
+        let stdin = child.stdin.take();
+        let stdout = child.stdout.take();
+        let stderr = child.stderr.take();
+
+        // Non-blocking stdin is what lets write_stdin fail fast instead of
+        // pinning an OS thread when the process stops draining its input.
+        // Only the pipe's write end is affected — the child's read end is a
+        // separate file description.
+        if let Some(s) = stdin.as_ref() {
+            if let Err(e) = set_nonblocking(s.as_raw_fd()) {
+                let _ = signal::kill(Pid::from_raw(-(pid as i32)), Signal::SIGKILL);
+                let _ = child.wait();
+                return Err(ConnectError::new(
+                    ErrorCode::Internal,
+                    format!("set stdin non-blocking: {e}"),
+                ));
+            }
+        }
+
+        let handle = Arc::new(ProcessHandle {
+            config,
+            tag,
+            pid,
+            data_tx: data_tx.clone(),
+            end_tx: end_tx.clone(),
+            ended: Mutex::new(None),
+            output_log: Mutex::new(OutputLog::default()),
+            stdin: Mutex::new(stdin),
+            pty_master: Mutex::new(None),
+            input_gate: tokio::sync::Mutex::new(()),
+        });
+
+        let data_rx = handle.subscribe_data();
+        let end_rx = handle.subscribe_end();
+
+        let mut output_readers: Vec<std::thread::JoinHandle<()>> = Vec::new();
+
+        if let Some(out) = stdout {
+            let handle_for_reader = Arc::clone(&handle);
+            output_readers.push(std::thread::spawn(move || {
+                coalesce_read_loop(out, STD_CHUNK_SIZE, |chunk| {
+                    handle_for_reader.publish_data(DataEvent::Stdout(chunk));
+                });
+            }));
+        }
+
+        if let Some(err_pipe) = stderr {
+            let handle_for_reader = Arc::clone(&handle);
+            output_readers.push(std::thread::spawn(move || {
+                coalesce_read_loop(err_pipe, STD_CHUNK_SIZE, |chunk| {
+                    handle_for_reader.publish_data(DataEvent::Stderr(chunk));
+                });
+            }));
+        }
+
+        let end_tx_clone = end_tx.clone();
+        let handle_for_waiter = Arc::clone(&handle);
+        std::thread::spawn(move || {
+            let status = child.wait();
+            // Drain stdout/stderr to EOF before publishing the end event so
+            // trailing output is never lost to a process-exit/pipe-read race.
+            for reader in output_readers {
+                let _ = reader.join();
+            }
+            let end_event = match status {
+                Ok(s) => EndEvent {
+                    exit_code: s.code().unwrap_or(-1),
+                    exited: s.code().is_some(),
+                    status: format!("{s}"),
+                    error: None,
+                },
+                Err(e) => EndEvent {
+                    exit_code: -1,
+                    exited: false,
+                    status: "error".into(),
+                    error: Some(e.to_string()),
+                },
+            };
+            *handle_for_waiter.ended.lock().unwrap() = Some(end_event.clone());
+            let _ = end_tx_clone.send(end_event);
+        });
+
+        tracing::info!(pid, cmd = cmd_str, "process started (pipe)");
+        Ok(SpawnedProcess {
+            handle,
+            data_rx,
+            end_rx,
+        })
+    }
+}
+
+fn current_nice() -> i32 {
+    unsafe {
+        *libc::__errno_location() = 0;
+        let prio = libc::getpriority(libc::PRIO_PROCESS, 0);
+        if *libc::__errno_location() != 0 {
+            return 0;
+        }
+        // getpriority(PRIO_PROCESS, 0) returns the nice value directly,
+        // in the range [-20, 19]; the normal default is 0.
+        prio
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::HashMap;
+
+    fn spawn(cmd: &str, enable_stdin: bool, pty: Option<(u16, u16)>) -> SpawnedProcess {
+        let user = nix::unistd::User::from_uid(nix::unistd::getuid())
+            .unwrap()
+            .unwrap();
+        spawn_process(
+            cmd,
+            &[],
+            &HashMap::new(),
+            "/tmp",
+            pty,
+            enable_stdin,
+            None,
+            &user,
+            &dashmap::DashMap::new(),
+        )
+        .unwrap()
+    }
+
+    /// Wait until the accumulated bytes from `recv` contain `needle`.
+    async fn recv_until_contains(
+        rx: &mut broadcast::Receiver<DataEvent>,
+        needle: &[u8],
+        what: &str,
+    ) -> Vec<u8> {
+        let mut acc: Vec<u8> = Vec::new();
+        tokio::time::timeout(Duration::from_secs(10), async {
+            loop {
+                match rx.recv().await {
+                    Ok(DataEvent::Stdout(d)) | Ok(DataEvent::Pty(d)) => {
+                        acc.extend_from_slice(&d);
+                        if acc.windows(needle.len()).any(|w| w == needle) {
+                            break;
+                        }
+                    }
+                    Ok(DataEvent::Stderr(_)) => {}
+                    Err(broadcast::error::RecvError::Lagged(_)) => {}
+                    Err(e) => panic!("{what}: data stream closed early: {e}"),
+                }
+            }
+        })
+        .await
+        .unwrap_or_else(|_| panic!("{what}: output never contained expected bytes"));
+        acc
+    }
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn write_to_stuck_stdin_errors_instead_of_hanging() {
+        // sleep never reads stdin: the 64K pipe buffer fills and the write
+        // must fail with ResourceExhausted after the bounded wait — the old
+        // write_all here blocked a pool thread forever.
+        let spawned = spawn("sleep 60", true, None);
+        let handle = Arc::clone(&spawned.handle);
+        let big = vec![b'x'; 1024 * 1024];
+        let writer = tokio::spawn(async move { handle.write_stdin(&big).await });
+
+        // While that write is parked, the agent must stay fully responsive:
+        // a fresh process spawns, runs, and reports its exit.
+        let mut quick = spawn("true", false, None);
+        let end = tokio::time::timeout(Duration::from_secs(10), quick.end_rx.recv())
+            .await
+            .expect("agent unresponsive while stdin write pending")
+            .expect("end event");
+        assert!(end.exited);
+
+        let err = tokio::time::timeout(INPUT_WRITE_TIMEOUT + Duration::from_secs(10), writer)
+            .await
+            .expect("stdin write hung past its deadline")
+            .expect("writer task panicked")
+            .expect_err("write into a full pipe nobody reads must error");
+        assert!(
+            matches!(err.code, ErrorCode::ResourceExhausted),
+            "expected ResourceExhausted, got {:?}",
+            err.code
+        );
+
+        let _ = spawned.handle.send_signal(Signal::SIGKILL);
+    }
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn stdin_write_and_eof_still_work() {
+        let mut spawned = spawn("cat", true, None);
+        spawned.handle.write_stdin(b"hello\n").await.unwrap();
+        recv_until_contains(&mut spawned.data_rx, b"hello\n", "cat stdout").await;
+
+        // close_stdin must still deliver EOF with the non-blocking pipe.
+        spawned.handle.close_stdin().unwrap();
+        let end = tokio::time::timeout(Duration::from_secs(10), spawned.end_rx.recv())
+            .await
+            .expect("cat did not exit after stdin EOF")
+            .expect("end event");
+        assert_eq!(end.exit_code, 0);
+    }
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn pty_write_and_echo_still_work() {
+        // O_NONBLOCK on the pty master is shared with the output reader;
+        // this covers both directions surviving it.
+        let mut spawned = spawn("cat", false, Some((80, 24)));
+        spawned.handle.write_pty(b"hello\r").await.unwrap();
+        recv_until_contains(&mut spawned.data_rx, b"hello", "pty echo").await;
+        let _ = spawned.handle.send_signal(Signal::SIGKILL);
+    }
+}

envd-rs/src/rpc/process_service.rs

@@ -0,0 +1,653 @@
+use std::collections::HashMap;
+use std::pin::Pin;
+use std::sync::Arc;
+
+use connectrpc::{ConnectError, Context, ErrorCode};
+use dashmap::DashMap;
+use futures::{Stream, StreamExt};
+use tokio::sync::broadcast;
+
+use crate::permissions::path::{expand_and_resolve, expand_tilde};
+use crate::permissions::user::lookup_user;
+use crate::rpc::pb::process::*;
+use crate::rpc::process_handler::{self, DataEvent, ProcessHandle};
+use crate::state::AppState;
+
+pub struct ProcessServiceImpl {
+    state: Arc<AppState>,
+    processes: Arc<DashMap<u32, Arc<ProcessHandle>>>,
+}
+
+impl ProcessServiceImpl {
+    pub fn new(state: Arc<AppState>) -> Self {
+        Self {
+            state,
+            processes: Arc::new(DashMap::new()),
+        }
+    }
+
+    fn get_process_by_selector(
+        &self,
+        selector: &ProcessSelectorView,
+    ) -> Result<Arc<ProcessHandle>, ConnectError> {
+        match &selector.selector {
+            Some(process_selector::SelectorView::Pid(pid)) => {
+                let pid_val = *pid;
+                self.processes
+                    .get(&pid_val)
+                    .map(|entry| Arc::clone(entry.value()))
+                    .ok_or_else(|| {
+                        ConnectError::new(
+                            ErrorCode::NotFound,
+                            format!("process with pid {pid_val} not found"),
+                        )
+                    })
+            }
+            Some(process_selector::SelectorView::Tag(tag)) => {
+                let tag_str: &str = tag;
+                for entry in self.processes.iter() {
+                    if let Some(ref t) = entry.value().tag {
+                        if t == tag_str {
+                            return Ok(Arc::clone(entry.value()));
+                        }
+                    }
+                }
+                Err(ConnectError::new(
+                    ErrorCode::NotFound,
+                    format!("process with tag {tag_str} not found"),
+                ))
+            }
+            None => Err(ConnectError::new(
+                ErrorCode::InvalidArgument,
+                "process selector required",
+            )),
+        }
+    }
+
+    fn spawn_from_request(
+        &self,
+        request: &StartRequestView<'_>,
+    ) -> Result<process_handler::SpawnedProcess, ConnectError> {
+        let proc_config = request.process.as_option().ok_or_else(|| {
+            ConnectError::new(ErrorCode::InvalidArgument, "process config required")
+        })?;
+
+        // Per-request user overrides the sandbox default when provided.
+        let username = if proc_config.user.is_empty() {
+            self.state.defaults.user()
+        } else {
+            proc_config.user.to_string()
+        };
+        let user = lookup_user(&username).map_err(|e| ConnectError::new(ErrorCode::Internal, e))?;
+
+        let cmd_raw: &str = proc_config.cmd;
+        let args_raw: Vec<String> = proc_config.args.iter().map(|s| s.to_string()).collect();
+        let envs: HashMap<String, String> = proc_config
+            .envs
+            .iter()
+            .map(|(k, v)| (k.to_string(), v.to_string()))
+            .collect();
+
+        let home_dir = user.dir.to_string_lossy().to_string();
+
+        let cmd = expand_tilde(cmd_raw, &home_dir)
+            .map_err(|e| ConnectError::new(ErrorCode::InvalidArgument, e))?;
+        let args: Vec<String> = args_raw
+            .into_iter()
+            .map(|a| expand_tilde(&a, &home_dir).unwrap_or(a))
+            .collect();
+
+        let cwd_str: &str = proc_config.cwd.unwrap_or("");
+        let default_workdir = self.state.defaults.workdir();
+        let cwd = expand_and_resolve(cwd_str, &home_dir, default_workdir.as_deref())
+            .map_err(|e| ConnectError::new(ErrorCode::InvalidArgument, e))?;
+
+        let effective_cwd = if cwd.is_empty() { "/" } else { &cwd };
+        if let Err(_) = std::fs::metadata(effective_cwd) {
+            return Err(ConnectError::new(
+                ErrorCode::InvalidArgument,
+                format!("cwd '{effective_cwd}' does not exist"),
+            ));
+        }
+
+        let pty_opts = request.pty.as_option().and_then(|pty| {
+            pty.size
+                .as_option()
+                .map(|sz| (sz.cols as u16, sz.rows as u16))
+        });
+
+        let enable_stdin = request.stdin.unwrap_or(true);
+        let tag = request.tag.map(|s| s.to_string());
+
+        tracing::info!(
+            cmd = cmd,
+            has_pty = pty_opts.is_some(),
+            pty_size = ?pty_opts,
+            tag = ?tag,
+            stdin = enable_stdin,
+            cwd = effective_cwd,
+            user = %username,
+            "process.Start request"
+        );
+
+        let spawned = process_handler::spawn_process(
+            &cmd,
+            &args,
+            &envs,
+            effective_cwd,
+            pty_opts,
+            enable_stdin,
+            tag,
+            &user,
+            &self.state.defaults.env_vars,
+        )?;
+
+        self.processes
+            .insert(spawned.handle.pid, Arc::clone(&spawned.handle));
+
+        let processes = Arc::clone(&self.processes);
+        let pid = spawned.handle.pid;
+        // Subscribe before checking cached_end so the prune cannot be lost to a
+        // race: a short-lived process can exit and broadcast its end event
+        // before this task runs. A broadcast receiver only sees messages sent
+        // after subscribe(), so a late subscribe would miss the event forever
+        // (recv() never returns Closed either — the handle keeps end_tx alive
+        // until it leaves the map, which only this task does). The waiter sets
+        // ended before sending end_tx, so cached_end() is a reliable fallback.
+        let mut cleanup_end_rx = spawned.handle.subscribe_end();
+        let already_ended = spawned.handle.cached_end().is_some();
+        tokio::spawn(async move {
+            if !already_ended {
+                let _ = cleanup_end_rx.recv().await;
+            }
+            processes.remove(&pid);
+        });
+
+        Ok(spawned)
+    }
+}
+
+impl Process for ProcessServiceImpl {
+    async fn list(
+        &self,
+        ctx: Context,
+        _request: buffa::view::OwnedView<ListRequestView<'static>>,
+    ) -> Result<(ListResponse, Context), ConnectError> {
+        let processes: Vec<ProcessInfo> = self
+            .processes
+            .iter()
+            .map(|entry| {
+                let h = entry.value();
+                ProcessInfo {
+                    config: buffa::MessageField::some(h.config.clone()),
+                    pid: h.pid,
+                    tag: h.tag.clone(),
+                    ..Default::default()
+                }
+            })
+            .collect();
+
+        Ok((
+            ListResponse {
+                processes,
+                ..Default::default()
+            },
+            ctx,
+        ))
+    }
+
+    async fn start(
+        &self,
+        ctx: Context,
+        request: buffa::view::OwnedView<StartRequestView<'static>>,
+    ) -> Result<
+        (
+            Pin<Box<dyn Stream<Item = Result<StartResponse, ConnectError>> + Send>>,
+            Context,
+        ),
+        ConnectError,
+    > {
+        let spawned = self.spawn_from_request(&request)?;
+        let pid = spawned.handle.pid;
+
+        // Start subscribes before any output is produced, so there is nothing to
+        // replay and the process cannot have ended yet.
+        let stream = process_event_stream(pid, Vec::new(), spawned.data_rx, spawned.end_rx, None)
+            .map(|r| r.map(wrap_start_response));
+
+        Ok((Box::pin(stream), ctx))
+    }
+
+    async fn connect(
+        &self,
+        ctx: Context,
+        request: buffa::view::OwnedView<ConnectRequestView<'static>>,
+    ) -> Result<
+        (
+            Pin<Box<dyn Stream<Item = Result<ConnectResponse, ConnectError>> + Send>>,
+            Context,
+        ),
+        ConnectError,
+    > {
+        let selector = request.process.as_option().ok_or_else(|| {
+            ConnectError::new(ErrorCode::InvalidArgument, "process selector required")
+        })?;
+        let handle = self.get_process_by_selector(selector)?;
+        let pid = handle.pid;
+
+        // Snapshot buffered output + subscribe live atomically, then read the
+        // exit state. Ordering matters: end_rx must be subscribed before
+        // cached_end is read so a process that exits in the window is still
+        // observed (via the channel if subscribed in time, via cached_end
+        // otherwise).
+        let (replay, data_rx) = handle.subscribe_data_replay();
+        let end_rx = handle.subscribe_end();
+        let cached_end = handle.cached_end();
+
+        let stream = process_event_stream(pid, replay, data_rx, end_rx, cached_end)
+            .map(|r| r.map(wrap_connect_response));
+
+        Ok((Box::pin(stream), ctx))
+    }
+
+    async fn update(
+        &self,
+        ctx: Context,
+        request: buffa::view::OwnedView<UpdateRequestView<'static>>,
+    ) -> Result<(UpdateResponse, Context), ConnectError> {
+        let selector = request.process.as_option().ok_or_else(|| {
+            ConnectError::new(ErrorCode::InvalidArgument, "process selector required")
+        })?;
+        let handle = self.get_process_by_selector(selector)?;
+
+        if let Some(pty) = request.pty.as_option() {
+            if let Some(size) = pty.size.as_option() {
+                handle.resize_pty(size.cols as u16, size.rows as u16)?;
+            }
+        }
+
+        Ok((
+            UpdateResponse {
+                ..Default::default()
+            },
+            ctx,
+        ))
+    }
+
+    async fn stream_input(
+        &self,
+        ctx: Context,
+        mut requests: Pin<
+            Box<
+                dyn Stream<
+                        Item = Result<
+                            buffa::view::OwnedView<StreamInputRequestView<'static>>,
+                            ConnectError,
+                        >,
+                    > + Send,
+            >,
+        >,
+    ) -> Result<(StreamInputResponse, Context), ConnectError> {
+        use futures::StreamExt;
+
+        let mut handle: Option<Arc<ProcessHandle>> = None;
+
+        while let Some(result) = requests.next().await {
+            let req = result?;
+            match &req.event {
+                Some(stream_input_request::EventView::Start(start)) => {
+                    if let Some(selector) = start.process.as_option() {
+                        handle = Some(self.get_process_by_selector(selector)?);
+                    }
+                }
+                Some(stream_input_request::EventView::Data(data)) => {
+                    let h = handle.as_ref().ok_or_else(|| {
+                        ConnectError::new(ErrorCode::FailedPrecondition, "no start event received")
+                    })?;
+                    if let Some(input) = data.input.as_option() {
+                        write_input(h, input).await?;
+                    }
+                }
+                Some(stream_input_request::EventView::Keepalive(_)) => {}
+                None => {}
+            }
+        }
+
+        Ok((
+            StreamInputResponse {
+                ..Default::default()
+            },
+            ctx,
+        ))
+    }
+
+    async fn send_input(
+        &self,
+        ctx: Context,
+        request: buffa::view::OwnedView<SendInputRequestView<'static>>,
+    ) -> Result<(SendInputResponse, Context), ConnectError> {
+        let selector = request.process.as_option().ok_or_else(|| {
+            ConnectError::new(ErrorCode::InvalidArgument, "process selector required")
+        })?;
+        let handle = self.get_process_by_selector(selector)?;
+
+        if let Some(input) = request.input.as_option() {
+            write_input(&handle, input).await?;
+        }
+
+        Ok((
+            SendInputResponse {
+                ..Default::default()
+            },
+            ctx,
+        ))
+    }
+
+    async fn send_signal(
+        &self,
+        ctx: Context,
+        request: buffa::view::OwnedView<SendSignalRequestView<'static>>,
+    ) -> Result<(SendSignalResponse, Context), ConnectError> {
+        let selector = request.process.as_option().ok_or_else(|| {
+            ConnectError::new(ErrorCode::InvalidArgument, "process selector required")
+        })?;
+        let handle = self.get_process_by_selector(selector)?;
+
+        let sig = match request.signal.as_known() {
+            Some(Signal::SIGNAL_SIGKILL) => nix::sys::signal::Signal::SIGKILL,
+            Some(Signal::SIGNAL_SIGTERM) => nix::sys::signal::Signal::SIGTERM,
+            _ => {
+                return Err(ConnectError::new(
+                    ErrorCode::InvalidArgument,
+                    "invalid or unspecified signal",
+                ));
+            }
+        };
+
+        handle.send_signal(sig)?;
+        Ok((
+            SendSignalResponse {
+                ..Default::default()
+            },
+            ctx,
+        ))
+    }
+
+    async fn close_stdin(
+        &self,
+        ctx: Context,
+        request: buffa::view::OwnedView<CloseStdinRequestView<'static>>,
+    ) -> Result<(CloseStdinResponse, Context), ConnectError> {
+        let selector = request.process.as_option().ok_or_else(|| {
+            ConnectError::new(ErrorCode::InvalidArgument, "process selector required")
+        })?;
+        let handle = self.get_process_by_selector(selector)?;
+        handle.close_stdin()?;
+        Ok((
+            CloseStdinResponse {
+                ..Default::default()
+            },
+            ctx,
+        ))
+    }
+}
+
+// Input writes go straight to the fd, which is O_NONBLOCK (set at spawn):
+// small interactive writes complete inline on the async worker, and a full
+// buffer parks the task awaiting writability with a bounded deadline inside
+// write_stdin / write_pty — no blocking-pool thread is ever pinned by a
+// process that stopped reading its input.
+async fn write_input(
+    handle: &Arc<ProcessHandle>,
+    input: &ProcessInputView<'_>,
+) -> Result<(), ConnectError> {
+    match &input.input {
+        Some(process_input::InputView::Pty(d)) => handle.write_pty(d).await,
+        Some(process_input::InputView::Stdin(d)) => handle.write_stdin(d).await,
+        None => Ok(()),
+    }
+}
+
+/// Shared event pump for `Start` and `Connect`. Yields a leading start event,
+/// replays any buffered output (empty for `Start`), then forwards live output
+/// and the final exit event. The caller wraps each `ProcessEvent` into its own
+/// response envelope, so the streaming logic lives in exactly one place.
+fn process_event_stream(
+    pid: u32,
+    replay: Vec<DataEvent>,
+    mut data_rx: broadcast::Receiver<DataEvent>,
+    mut end_rx: broadcast::Receiver<process_handler::EndEvent>,
+    cached_end: Option<process_handler::EndEvent>,
+) -> impl Stream<Item = Result<ProcessEvent, ConnectError>> {
+    use broadcast::error::{RecvError, TryRecvError};
+
+    async_stream::stream! {
+        yield Ok(make_start_event(pid));
+
+        for ev in replay {
+            yield Ok(make_data_event(ev));
+        }
+
+        // Process already exited before we attached. The snapshot above covers
+        // output up to the attach point; drain anything the live receiver
+        // buffered after the snapshot, then emit the cached exit. end_rx may
+        // never deliver here — a broadcast receiver only sees events sent after
+        // it subscribed, and the exit can predate that — so cached_end is the
+        // source of truth.
+        if let Some(end) = cached_end {
+            loop {
+                match data_rx.try_recv() {
+                    Ok(ev) => yield Ok(make_data_event(ev)),
+                    Err(TryRecvError::Lagged(_)) => continue,
+                    Err(_) => break,
+                }
+            }
+            yield Ok(make_end_event(end));
+            return;
+        }
+
+        loop {
+            tokio::select! {
+                biased;
+                data = data_rx.recv() => {
+                    match data {
+                        Ok(ev) => yield Ok(make_data_event(ev)),
+                        Err(RecvError::Lagged(_)) => continue,
+                        Err(RecvError::Closed) => {
+                            // Data channel closed: the process ended and its
+                            // handle was dropped. The end event is published
+                            // before the handle drop, so it is still buffered —
+                            // emit it rather than losing the exit code.
+                            if let Ok(end) = end_rx.try_recv() {
+                                yield Ok(make_end_event(end));
+                            }
+                            break;
+                        }
+                    }
+                }
+                end = end_rx.recv() => {
+                    // Process ended. The waiter joins the output readers before
+                    // sending this event, so every byte is already in the data
+                    // channel — drain it fully before the end.
+                    loop {
+                        match data_rx.try_recv() {
+                            Ok(ev) => yield Ok(make_data_event(ev)),
+                            Err(TryRecvError::Lagged(_)) => continue,
+                            Err(_) => break,
+                        }
+                    }
+                    if let Ok(end) = end {
+                        yield Ok(make_end_event(end));
+                    }
+                    break;
+                }
+            }
+        }
+    }
+}
+
+fn wrap_start_response(event: ProcessEvent) -> StartResponse {
+    StartResponse {
+        event: buffa::MessageField::some(event),
+        ..Default::default()
+    }
+}
+
+fn wrap_connect_response(event: ProcessEvent) -> ConnectResponse {
+    ConnectResponse {
+        event: buffa::MessageField::some(event),
+        ..Default::default()
+    }
+}
+
+fn make_start_event(pid: u32) -> ProcessEvent {
+    ProcessEvent {
+        event: Some(process_event::Event::Start(Box::new(
+            process_event::StartEvent {
+                pid,
+                ..Default::default()
+            },
+        ))),
+        ..Default::default()
+    }
+}
+
+fn make_data_event(ev: DataEvent) -> ProcessEvent {
+    let output = match ev {
+        DataEvent::Stdout(d) => Some(process_event::data_event::Output::Stdout(d.into())),
+        DataEvent::Stderr(d) => Some(process_event::data_event::Output::Stderr(d.into())),
+        DataEvent::Pty(d) => Some(process_event::data_event::Output::Pty(d.into())),
+    };
+    ProcessEvent {
+        event: Some(process_event::Event::Data(Box::new(
+            process_event::DataEvent {
+                output,
+                ..Default::default()
+            },
+        ))),
+        ..Default::default()
+    }
+}
+
+fn make_end_event(end: process_handler::EndEvent) -> ProcessEvent {
+    ProcessEvent {
+        event: Some(process_event::Event::End(Box::new(
+            process_event::EndEvent {
+                exit_code: end.exit_code,
+                exited: end.exited,
+                status: end.status,
+                error: end.error,
+                ..Default::default()
+            },
+        ))),
+        ..Default::default()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn cmd_expands_tilde_slash() {
+        let home_dir = "/home/testuser";
+        let result = expand_tilde("~/bin/mytool", home_dir).unwrap();
+        assert_eq!(result, "/home/testuser/bin/mytool");
+    }
+
+    #[test]
+    fn cmd_expands_bare_tilde() {
+        let home_dir = "/home/testuser";
+        let result = expand_tilde("~", home_dir).unwrap();
+        assert_eq!(result, "/home/testuser");
+    }
+
+    #[test]
+    fn cmd_passthrough_absolute() {
+        let home_dir = "/home/testuser";
+        let result = expand_tilde("/usr/bin/env", home_dir).unwrap();
+        assert_eq!(result, "/usr/bin/env");
+    }
+
+    #[test]
+    fn cmd_passthrough_relative_no_tilde() {
+        let home_dir = "/home/testuser";
+        let result = expand_tilde("bin/tool", home_dir).unwrap();
+        assert_eq!(result, "bin/tool");
+    }
+
+    #[test]
+    fn cmd_errors_on_other_user() {
+        let home_dir = "/home/testuser";
+        assert!(expand_tilde("~other/bin/tool", home_dir).is_err());
+    }
+
+    #[test]
+    fn args_expands_tilde_slash() {
+        let home_dir = "/home/testuser";
+        let result = expand_tilde("~/hi", home_dir).unwrap();
+        assert_eq!(result, "/home/testuser/hi");
+    }
+
+    #[test]
+    fn args_expands_bare_tilde() {
+        let home_dir = "/home/testuser";
+        let result = expand_tilde("~", home_dir).unwrap();
+        assert_eq!(result, "/home/testuser");
+    }
+
+    #[test]
+    fn args_other_user_left_literal() {
+        let home_dir = "/home/testuser";
+        let args_raw = vec!["~other".to_string(), "~other/path".to_string()];
+        let args: Vec<String> = args_raw
+            .into_iter()
+            .map(|a| expand_tilde(&a, home_dir).unwrap_or(a))
+            .collect();
+        assert_eq!(args, vec!["~other", "~other/path"]);
+    }
+
+    #[test]
+    fn args_passthrough_absolute() {
+        let home_dir = "/home/testuser";
+        let result = expand_tilde("/tmp/file", home_dir).unwrap();
+        assert_eq!(result, "/tmp/file");
+    }
+
+    #[test]
+    fn args_passthrough_relative_no_tilde() {
+        let home_dir = "/home/testuser";
+        let result = expand_tilde("relative/path", home_dir).unwrap();
+        assert_eq!(result, "relative/path");
+    }
+
+    #[test]
+    fn args_mixed_expands_tilde_keeps_rest() {
+        let home_dir = "/home/testuser";
+        let args_raw = vec![
+            "-p".to_string(),
+            "~/data".to_string(),
+            "/tmp/out".to_string(),
+            "~other".to_string(),
+        ];
+        let args: Vec<String> = args_raw
+            .into_iter()
+            .map(|a| expand_tilde(&a, home_dir).unwrap_or(a))
+            .collect();
+        assert_eq!(
+            args,
+            vec!["-p", "/home/testuser/data", "/tmp/out", "~other"]
+        );
+    }
+
+    #[test]
+    fn args_empty_passthrough() {
+        let home_dir = "/home/testuser";
+        let args_raw: Vec<String> = vec![];
+        let args: Vec<String> = args_raw
+            .into_iter()
+            .map(|a| expand_tilde(&a, home_dir).unwrap_or(a))
+            .collect();
+        assert!(args.is_empty());
+    }
+}

envd-rs/src/state.rs

@@ -0,0 +1,242 @@
+use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU32, AtomicU64, Ordering};
+use std::sync::{Arc, Mutex};
+
+use crate::auth::token::SecureToken;
+use crate::conntracker::ConnTracker;
+use crate::execcontext::Defaults;
+use crate::port::subsystem::PortSubsystem;
+use crate::util::AtomicMax;
+
+pub struct AppState {
+    pub defaults: Defaults,
+    pub version: String,
+    pub commit: String,
+    pub last_set_time: AtomicMax,
+    pub access_token: SecureToken,
+    pub conn_tracker: ConnTracker,
+    pub port_subsystem: Option<Arc<PortSubsystem>>,
+    pub cpu_used_pct: AtomicU32,
+    pub cpu_count: AtomicU32,
+    /// Whole-VM IO throughput, bytes/sec, sampled over the last 1s tick. Used
+    /// by the host activity sampler to keep IO-bound-but-CPU-idle workloads
+    /// (e.g. a long download) from being mistaken for inactive.
+    pub net_bps: AtomicU64,
+    pub disk_bps: AtomicU64,
+
+    /// Memory preload coordination. The host agent POSTs /memory/preload after
+    /// a snapshot restore to materialise every physical page (so the next
+    /// ch.snapshot writes a self-contained memory-ranges). `mem_preload_started`
+    /// ensures only one loader runs; `mem_preload_done` lets concurrent callers
+    /// rendezvous; `mem_preload_cancel` lets a teardown abort the loader.
+    pub mem_preload_started: AtomicBool,
+    pub mem_preload_done: AtomicBool,
+    pub mem_preload_cancel: AtomicBool,
+    /// See `reset_preload_run` for the per-run reset shared by /init and the
+    /// POST /memory/preload start/retry paths.
+    ///
+    /// Bumped by every /init lifecycle change. A loader thread captures the
+    /// value at spawn and refuses to run — or to publish results — once it no
+    /// longer matches, so a thread that survived a pause/resume (the VM can be
+    /// frozen mid-walk) cannot store a stale `done=true` for the NEXT
+    /// lifecycle's preload. Publication happens under `mem_preload_error`'s
+    /// mutex, which /init also holds while bumping, closing the
+    /// freeze-between-check-and-store window.
+    pub mem_preload_generation: AtomicU64,
+    pub mem_preload_regions: AtomicU64,
+    pub mem_preload_pages: AtomicU64,
+    pub mem_preload_bytes: AtomicU64,
+    pub mem_preload_elapsed_us: AtomicU64,
+    /// 0 = unset, 1 = /dev/mem, 2 = /proc/kcore.
+    pub mem_preload_source: AtomicU8,
+    pub mem_preload_error: Mutex<Option<String>>,
+
+    /// Last lifecycle ID seen on /init. Used to detect post-resume calls so
+    /// envd can refresh port forwarders and remount NFS volumes.
+    lifecycle_id: Mutex<Option<String>>,
+}
+
+impl AppState {
+    pub fn new(
+        defaults: Defaults,
+        version: String,
+        commit: String,
+        port_subsystem: Option<Arc<PortSubsystem>>,
+    ) -> Arc<Self> {
+        let state = Arc::new(Self {
+            defaults,
+            version,
+            commit,
+            last_set_time: AtomicMax::new(),
+            access_token: SecureToken::new(),
+            conn_tracker: ConnTracker::new(),
+            port_subsystem,
+            cpu_used_pct: AtomicU32::new(0),
+            cpu_count: AtomicU32::new(0),
+            net_bps: AtomicU64::new(0),
+            disk_bps: AtomicU64::new(0),
+            mem_preload_started: AtomicBool::new(false),
+            mem_preload_done: AtomicBool::new(false),
+            mem_preload_cancel: AtomicBool::new(false),
+            mem_preload_generation: AtomicU64::new(0),
+            mem_preload_regions: AtomicU64::new(0),
+            mem_preload_pages: AtomicU64::new(0),
+            mem_preload_bytes: AtomicU64::new(0),
+            mem_preload_elapsed_us: AtomicU64::new(0),
+            mem_preload_source: AtomicU8::new(0),
+            mem_preload_error: Mutex::new(None),
+            lifecycle_id: Mutex::new(None),
+        });
+
+        let state_clone = Arc::clone(&state);
+        std::thread::spawn(move || {
+            activity_sampler(state_clone);
+        });
+
+        state
+    }
+
+    pub fn cpu_used_pct(&self) -> f32 {
+        f32::from_bits(self.cpu_used_pct.load(Ordering::Relaxed))
+    }
+
+    pub fn cpu_count(&self) -> u32 {
+        self.cpu_count.load(Ordering::Relaxed)
+    }
+
+    pub fn net_bps(&self) -> u64 {
+        self.net_bps.load(Ordering::Relaxed)
+    }
+
+    pub fn disk_bps(&self) -> u64 {
+        self.disk_bps.load(Ordering::Relaxed)
+    }
+
+    /// Records a new lifecycle ID, returning true if it changed (i.e. this
+    /// is the first /init since a resume). First-ever call returns false:
+    /// Clears the per-run memory-preload result fields (done flag, counters,
+    /// source, error). Shared by /init's lifecycle reset and POST
+    /// /memory/preload's start/retry paths so the two field lists cannot
+    /// drift. The caller MUST hold the `mem_preload_error` mutex and pass its
+    /// guard's contents in — that mutex is the critical section that also
+    /// serializes the loader thread's result publication.
+    pub fn reset_preload_run(&self, err: &mut Option<String>) {
+        *err = None;
+        self.mem_preload_done.store(false, Ordering::SeqCst);
+        self.mem_preload_regions.store(0, Ordering::SeqCst);
+        self.mem_preload_pages.store(0, Ordering::SeqCst);
+        self.mem_preload_bytes.store(0, Ordering::SeqCst);
+        self.mem_preload_elapsed_us.store(0, Ordering::SeqCst);
+        self.mem_preload_source.store(0, Ordering::SeqCst);
+    }
+
+    /// boot-time /init doesn't need port-subsystem restart since the
+    /// subsystem hasn't been started yet by anything else.
+    pub fn bump_lifecycle(&self, new_id: &str) -> bool {
+        let mut guard = self.lifecycle_id.lock().unwrap();
+        let changed = match guard.as_deref() {
+            Some(existing) => existing != new_id,
+            None => false,
+        };
+        *guard = Some(new_id.to_owned());
+        changed
+    }
+}
+
+fn activity_sampler(state: Arc<AppState>) {
+    use sysinfo::System;
+
+    let mut sys = System::new();
+    sys.refresh_cpu_all();
+
+    // Cumulative IO counters from the previous tick. None until the first read.
+    let mut prev_net: Option<u64> = read_net_bytes();
+    let mut prev_disk: Option<u64> = read_disk_bytes();
+
+    loop {
+        std::thread::sleep(std::time::Duration::from_secs(1));
+
+        sys.refresh_cpu_all();
+
+        let pct = sys.global_cpu_usage();
+        let rounded = if pct > 0.0 {
+            (pct * 100.0).round() / 100.0
+        } else {
+            0.0
+        };
+
+        state
+            .cpu_used_pct
+            .store(rounded.to_bits(), Ordering::Relaxed);
+        state
+            .cpu_count
+            .store(sys.cpus().len() as u32, Ordering::Relaxed);
+
+        // Throughput = cumulative-counter delta over the ~1s tick. Counters can
+        // reset across a snapshot restore; a wrapped/negative delta reads as 0.
+        let cur_net = read_net_bytes();
+        let net_bps = match (prev_net, cur_net) {
+            (Some(p), Some(c)) => c.saturating_sub(p),
+            _ => 0,
+        };
+        prev_net = cur_net;
+
+        let cur_disk = read_disk_bytes();
+        let disk_bps = match (prev_disk, cur_disk) {
+            (Some(p), Some(c)) => c.saturating_sub(p),
+            _ => 0,
+        };
+        prev_disk = cur_disk;
+
+        state.net_bps.store(net_bps, Ordering::Relaxed);
+        state.disk_bps.store(disk_bps, Ordering::Relaxed);
+    }
+}
+
+/// Sum of rx+tx bytes across all non-loopback interfaces, from /proc/net/dev.
+/// Returns None if the file can't be read/parsed.
+fn read_net_bytes() -> Option<u64> {
+    let content = std::fs::read_to_string("/proc/net/dev").ok()?;
+    let mut total: u64 = 0;
+    // First two lines are headers.
+    for line in content.lines().skip(2) {
+        let Some((iface, rest)) = line.split_once(':') else {
+            continue;
+        };
+        if iface.trim() == "lo" {
+            continue;
+        }
+        let fields: Vec<&str> = rest.split_whitespace().collect();
+        // Column 0 = rx bytes, column 8 = tx bytes.
+        if let Some(rx) = fields.first().and_then(|v| v.parse::<u64>().ok()) {
+            total = total.saturating_add(rx);
+        }
+        if let Some(tx) = fields.get(8).and_then(|v| v.parse::<u64>().ok()) {
+            total = total.saturating_add(tx);
+        }
+    }
+    Some(total)
+}
+
+/// Sum of sectors read+written across all block devices, ×512, from
+/// /proc/diskstats. Skips partitions and loop/ram devices to avoid double
+/// counting. Returns None if the file can't be read/parsed.
+fn read_disk_bytes() -> Option<u64> {
+    let content = std::fs::read_to_string("/proc/diskstats").ok()?;
+    let mut sectors: u64 = 0;
+    for line in content.lines() {
+        let fields: Vec<&str> = line.split_whitespace().collect();
+        // 0=major 1=minor 2=name ... 5=sectors read ... 9=sectors written.
+        if fields.len() < 10 {
+            continue;
+        }
+        let name = fields[2];
+        if name.starts_with("loop") || name.starts_with("ram") {
+            continue;
+        }
+        let read = fields[5].parse::<u64>().unwrap_or(0);
+        let written = fields[9].parse::<u64>().unwrap_or(0);
+        sectors = sectors.saturating_add(read).saturating_add(written);
+    }
+    // Linux reports diskstats sectors in fixed 512-byte units.
+    Some(sectors.saturating_mul(512))
+}

envd-rs/src/util.rs

@@ -0,0 +1,100 @@
+use std::sync::atomic::{AtomicI64, Ordering};
+
+pub struct AtomicMax {
+    val: AtomicI64,
+}
+
+impl AtomicMax {
+    pub fn new() -> Self {
+        Self {
+            val: AtomicI64::new(i64::MIN),
+        }
+    }
+
+    pub fn get(&self) -> i64 {
+        self.val.load(Ordering::Acquire)
+    }
+
+    /// Sets the stored value to `new` if `new` is strictly greater than
+    /// the current value. Returns `true` if the value was updated.
+    pub fn set_to_greater(&self, new: i64) -> bool {
+        loop {
+            let current = self.val.load(Ordering::Acquire);
+            if new <= current {
+                return false;
+            }
+            match self
+                .val
+                .compare_exchange_weak(current, new, Ordering::Release, Ordering::Relaxed)
+            {
+                Ok(_) => return true,
+                Err(_) => continue,
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Arc;
+
+    #[test]
+    fn initial_value_is_i64_min() {
+        let m = AtomicMax::new();
+        assert_eq!(m.get(), i64::MIN);
+    }
+
+    #[test]
+    fn updates_when_larger() {
+        let m = AtomicMax::new();
+        assert!(m.set_to_greater(0));
+        assert_eq!(m.get(), 0);
+        assert!(m.set_to_greater(100));
+        assert_eq!(m.get(), 100);
+    }
+
+    #[test]
+    fn returns_false_when_equal() {
+        let m = AtomicMax::new();
+        m.set_to_greater(42);
+        assert!(!m.set_to_greater(42));
+        assert_eq!(m.get(), 42);
+    }
+
+    #[test]
+    fn returns_false_when_smaller() {
+        let m = AtomicMax::new();
+        m.set_to_greater(100);
+        assert!(!m.set_to_greater(50));
+        assert_eq!(m.get(), 100);
+    }
+
+    #[test]
+    fn concurrent_convergence() {
+        let m = Arc::new(AtomicMax::new());
+        let threads: Vec<_> = (0..8)
+            .map(|t| {
+                let m = Arc::clone(&m);
+                std::thread::spawn(move || {
+                    for i in (t * 100)..((t + 1) * 100) {
+                        m.set_to_greater(i);
+                    }
+                })
+            })
+            .collect();
+        for t in threads {
+            t.join().unwrap();
+        }
+        assert_eq!(m.get(), 799);
+    }
+
+    #[test]
+    fn i64_max_boundary() {
+        let m = AtomicMax::new();
+        assert!(m.set_to_greater(i64::MAX));
+        assert!(!m.set_to_greater(i64::MAX));
+        assert!(!m.set_to_greater(0));
+        assert_eq!(m.get(), i64::MAX);
+    }
+}

envd/LICENSE

@@ -1,202 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2023 FoundryLabs, Inc.
-   Modifications Copyright (c) 2026 M/S Omukk, Bangladesh
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.

envd/Makefile

@@ -1,62 +0,0 @@
-BUILD     := $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
-LDFLAGS   := -s -w -X=main.commitSHA=$(BUILD)
-BUILDS    := ../builds
-
-# ═══════════════════════════════════════════════════
-#  Build
-# ═══════════════════════════════════════════════════
-.PHONY: build build-debug
-
-build:
-	CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="$(LDFLAGS)" -o $(BUILDS)/envd .
-	@file $(BUILDS)/envd | grep -q "statically linked" || \
-		(echo "ERROR: envd is not statically linked!" && exit 1)
-
-build-debug:
-	CGO_ENABLED=1 go build -race -gcflags=all="-N -l" -ldflags="-X=main.commitSHA=$(BUILD)" -o $(BUILDS)/debug/envd .
-
-# ═══════════════════════════════════════════════════
-#  Run (debug mode, not inside a VM)
-# ═══════════════════════════════════════════════════
-.PHONY: run-debug
-
-run-debug: build-debug
-	$(BUILDS)/debug/envd -isnotfc -port 49983
-
-# ═══════════════════════════════════════════════════
-#  Code Generation
-# ═══════════════════════════════════════════════════
-.PHONY: generate proto openapi
-
-generate: proto openapi
-
-proto:
-	cd spec && buf generate --template buf.gen.yaml
-
-openapi:
-	go generate ./internal/api/...
-
-# ═══════════════════════════════════════════════════
-#  Quality
-# ═══════════════════════════════════════════════════
-.PHONY: fmt vet test tidy
-
-fmt:
-	gofmt -w .
-
-vet:
-	go vet ./...
-
-test:
-	go test -race -v ./...
-
-tidy:
-	go mod tidy
-
-# ═══════════════════════════════════════════════════
-#  Clean
-# ═══════════════════════════════════════════════════
-.PHONY: clean
-
-clean:
-	rm -f $(BUILDS)/envd $(BUILDS)/debug/envd