Edgeone Makers Env Adaption

Runtime Environment Adaptation Guide

This document describes the special constraints and adaptation rules for EdgeOne Makers Skills across different AI coding environments. Currently covered: WorkBuddy (Tencent sandboxed IDE)

🚦 Quick Reference: Preview Decision Tree

When you reach the "display / preview" step, read this first before deciding how to call present_files:

            ┌─ Delivering finished work? ── Yes ──→ present_files(deployed EdgeOne URL) ✅
            │
Enter       ┤
preview     │                      ┌─ dev server running? ─ Yes ──→ present_files(http://127.0.0.1:8088/) ✅
            └─ Still iterating? ───┤
                                    └─ No ──→ start edgeone makers dev → present_files(...)

Core iron rule: inside a Makers project, any HTML / URL preview MUST go through the HTTP protocol. file:// looks convenient, but fetch / SSE / Blob / KV all break under it.

Violation symptoms self-check (if you see these, go back up immediately)

• Browser Console: TypeError: Failed to fetch / CORS policy errors
• Page HTML loads fine but all JS requests 404
• SSE / EventSource disconnects immediately on connect
• Works locally but breaks once deployed (or vice versa)

WorkBuddy Sandbox Environment

WorkBuddy is a sandboxed remote IDE environment. When running AI coding tasks, it has the following constraints that differ from local development.

⚠️ Common misread: WorkBuddy is a desktop IDE sandbox, NOT a headless environment.

• CLI interactive prompts (site picker, confirmations) hang inside the sandbox → use the non-interactive flags in this section.
• BUT browser login (edgeone login --site <x>) works fully — WorkBuddy launches the host OS browser AND routes the OAuth callback back into the sandbox.

Deploy/link login should default to browser login and only fall back to -t <token> after browser login is confirmed to fail. Do NOT jump to token login just because the caller is an "Agent".

1. Non-interactive mode (all CLI commands must avoid interactive prompts)

Inside the WorkBuddy sandbox, CLI interactive prompts cause the process to hang forever. All edgeone CLI commands must carry non-interactive flags:

# Correct: local development
edgeone makers dev --name my-project --skip-env-sync

# Correct: deploy
edgeone makers deploy -n my-project --json

# Wrong: will hang
edgeone makers dev

2. Login authentication

Token resolution priority (the CLI checks in this order automatically):

1. -t <token> command-line argument
2. EDGEONE_PAGES_API_TOKEN environment variable
3. <cwd>/.edgeone/auth.json (written by edgeone login --local)
4. ~/.edgeone/ global credentials

Recommended approach: browser login + the --local flag:

edgeone login --site china --local

--local writes credentials to the project directory at <cwd>/.edgeone/auth.json, bypassing home-directory write restrictions.

Login status detection:

edgeone whoami  # exit 0 = logged in, exit 1 = not logged in (does not hang)

When is login actually required? Login is only needed when the project uses Blob or other credentialed backends — and strictly because of the dependency chain: Blob requires the project to be linked, and linking requires a logged-in account first. So edgeone makers dev for a pure-static site runs fine without login — do NOT force a login prompt for static-only previews. Login (or -t <token>) becomes mandatory the moment dev/deploy must touch Blob storage. (The trigger condition and the link chain live in makers-storage.)

CLI version requirement: >= 1.6.7 (older versions lack the non-interactive fixes; whoami will hang)

3. Network isolation (dev server reachability from Bash)

The Bash tool and edgeone makers dev run in the same sandbox (same machine), so the loopback dev server IS reachable from Bash. The earlier claim that "Bash curl is isolated and returns 404" is wrong — the failures are caused by the proxy (§5) and the IPv6 localhost (§4), not by network isolation.

Practical rule:

• Use curl --noproxy '*' http://127.0.0.1:8088/... from Bash to agent-side verify API endpoints during testing — this works (it was used to validate a full create→upload→like flow).
• Do NOT rely on Bash curl to show the page to the user. The user's browser cannot reach 127.0.0.1:8088 inside the sandbox; for a user-facing preview, pass the dev URL to present_files (platform tunnel) or deploy and share the live URL.

4. Force IPv4 (127.0.0.1, not localhost)

The dev server listens on the IPv6 dual stack (::), but in the sandbox localhost resolves to ::1, causing false 404s.

# Correct
curl http://127.0.0.1:8088/

# Wrong (404 in the sandbox)
curl http://localhost:8088/

The preview URL must also use 127.0.0.1:

present_files: http://127.0.0.1:8088/

5. Proxy hijacking (curl needs --noproxy)

The sandbox injects an http_proxy environment variable; curl goes through the proxy by default, which swallows the SSE streaming response.

# Correct
curl --noproxy '*' http://127.0.0.1:8088/api/chat

# Wrong (returns "Empty reply" / status 000)
curl http://127.0.0.1:8088/api/chat

The built-in browser preview is not affected by the proxy.

6. Home directory write restriction

The sandbox blocks writes to ~/.edgeone/, but allows writes to the project directory.

A setLocalData EPERM does not affect the running service; it only affects the CLI's local state persistence.

7. Command execution mode (sync vs async)

7.2 Deploy in background — why, and what the kill really means

• Foreground kill = wall-clock budget, not a hang. A foreground Bash command in this sandbox has a fixed ~100s wall-clock budget; at the limit the whole process tree gets SIGKILL (exit 137 = 128 + 9), regardless of whether it keeps printing. During a deploy the CLI prints Deployment in progress... elapsed: ~XXs every ~10s — those heartbeat lines do NOT reset or extend the budget. So "still printing → killed at ~100s" is expected, not a stall.
• Killing the CLI does NOT usually fail the deploy. The deployment itself runs server-side. A foreground CLI killed at Created deployment / Process has very likely continued on the server and gone live (confirmed in practice: a deploy killed at ~100s was later verified live, took ~674s end-to-end). Re-running deploy (same -n <project>) reuses the project and returns the URL.
• Always use run_in_background: true for deploy so the CLI survives past the foreground budget and emits the final --json line with the live URL. Do not poll the task across turns — rely on the <task-notification> completion event. (Cross-turn TaskOutput may report the handle as "not found"; the process still finished.)
• --json still prints progress heartbeats to stdout/stderr, not a single clean JSON line. Parse the last line for the result object; treat the progress lines as noise. (This is a CLI cleanliness issue, unrelated to the kill behavior — do not assume "no output = process ended"; the sandbox judges liveness by OS process state, not by stdout bytes.)
• Clean up background processes after use: a edgeone makers dev left running keeps holding port 8088 and may collide with the next dev/deploy. Stop it with TaskStop or kill it when the session moves on.

7.1 Preview & Dev Server full flow (MUST use HTTP, file:// forbidden)

After finishing development, start the dev server and preview directly — do not ask "do you want to preview?". Full flow:

⚠️ WorkBuddy default behavior: when you create an HTML file the platform may auto-open a preview via file:// — ignore it, that is not a valid preview. You must wait until edgeone makers dev is up, then re-open via the HTTP URL to override it.

1. Start edgeone makers dev --name <project> --skip-env-sync (background async, see §7)
2. Wait 2-3 seconds for the dev server to be ready
3. Pass http://127.0.0.1:8088/ to present_files (note it is 127.0.0.1, not localhost — see §4)
4. Tell the user: "The project's local preview is running, please check it out. If everything looks good, I can deploy it live for you directly."

Only after the user confirms, run edgeone makers deploy -n <project> --json (background async, see §7 and §7.2 — it exceeds the foreground wall-clock budget).