easy-sandbox 0.1.0__tar.gz

easy_sandbox-0.1.0/.agents/notes/README.md

@@ -0,0 +1,95 @@
+# Module Specifications & Architecture Decisions
+
+This directory contains Architecture Decision Records (ADRs) and module specifications
+following a structured review process.
+
+## Directory Structure
+
+```
+notes/
+├── proposed/          # Under review
+│   ├── architecture/  # System-wide architecture decisions
+│   ├── feature/       # Feature module specifications
+│   └── process/       # Engineering process decisions
+├── implemented/       # Accepted and implemented
+│   ├── architecture/
+│   ├── feature/
+│   └── process/
+└── rejected/          # Considered but rejected
+```
+
+## Lifecycle
+
+1. **Proposed** → Create in `proposed/<category>/`
+2. **Implemented** → Move to `implemented/<category>/`, update Status field
+3. **Rejected** → Move to `rejected/`, document reasoning
+
+The `Status:` field value **must** match the state directory the file lives in
+(`proposed` / `implemented` / `rejected`). When work is completed, move the file
+and update the field together.
+
+## Language
+
+All ADRs **must** be written in English. This keeps the `.agents/` engineering
+record internally consistent and reviewable by all contributors and tooling.
+(Go-forward convention: every document under `.agents/notes/` is English. Existing
+snapshots under `.agents/evidence/` are historical artifacts and are left as-is.)
+
+## Naming & Location
+
+- **File name:** `YYYY-MM-DD-<topic-slug>.md` — ISO date of the decision plus a
+  lowercase, hyphenated topic slug (e.g. `2026-09-09-layer-violation-fix.md`).
+- **Location:** `<state>/<category>/` where `<state>` is `proposed`,
+  `implemented`, or `rejected`, and `<category>` is one of:
+  - `architecture/` — system-wide architecture decisions
+  - `feature/` — feature module specifications
+  - `process/` — engineering process decisions
+- **Exception:** `rejected/` is a **flat** directory (no category subfolders).
+
+## Template
+
+Each ADR file follows this format. The title line is always `# Decision: <Title>`,
+immediately followed by the `Status:` line.
+
+### Required sections
+
+Every ADR must contain all seven sections below, in this order:
+
+```markdown
+# Decision: <Title>
+
+Status: proposed | implemented | rejected
+
+## Problem
+<Motivation, independent of solution>
+
+## Decision
+<Technical approach, interfaces, file paths>
+
+## API Design
+<Core class/function signatures, input/output types.
+For decisions that do not involve APIs, state:
+"N/A — this decision does not involve API changes.">
+
+## Alternatives considered
+- **<Option A>** — <Why rejected>
+
+## Dependencies
+<Required modules/packages>
+
+## Test Strategy
+<Testing approach and coverage>
+
+## Acceptance criteria
+<Measurable acceptance conditions>
+```
+
+### Optional sections
+
+The following sections **may** appear after the required sections when useful.
+They are registered as recognised optional sections and are not mandatory:
+
+- `## Consequences` — trade-offs and follow-on effects of the decision
+- `## Implementation` — implementation notes, phases, or status detail
+- `## Evidence` — links to tests, PRs, or captured verification artifacts
+- `## Files changed` — the concrete files touched by the decision

easy_sandbox-0.1.0/.gitignore

@@ -0,0 +1,76 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+coverage.json
+htmlcov/
+.tox/
+
+# Linting / Type-checking caches
+.mypy_cache/
+.ruff_cache/
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Secrets
+*.pem
+*.key
+secrets.json
+# NOTE: .secrets.baseline is intentionally tracked — it is referenced by the
+# detect-secrets hook in .pre-commit-config.yaml and must ship with the repo.
+# Do not add it back to .gitignore.
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build
+*.so
+*.dylib
+*.whl
+
+# Temporary diff/patch files
+*.diff
+current_diff.patch
+diff-code.txt
+
+# Local scratch/verification workspaces
+.scratch-*/
+
+# Sandbox config (may contain API keys)
+~/.sbox/
+
+# Benchmarks output
+benchmarks/*.log
+
+# Process artifacts (evidence snapshots & research notes)
+# NOTE: .agents/notes/ (ADR decisions) is NOT ignored — it stays tracked.
+# NOTE: .agents/design/ is deprecated (historical artifacts tracked, no new content).
+/.agents/evidence/
+/.agents/research/
+
+# awesome-templates sub-repo (has its own git)
+awesome-templates/

easy_sandbox-0.1.0/CHANGELOG.md

@@ -0,0 +1,182 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+_Nothing yet._
+
+## [0.1.0] - 2026-09-29
+
+First stable release. Includes all changes below (formerly tracked as `0.1.0-dev`) plus the current cycle:
+
+### Breaking Changes (Task 201 — config Reset Removal & Value Semantics)
+
+1. **Removed `ebx config reset`**.
+   Clearing is now per key via `ebx config set KEY ""`: the stored value is removed and the key returns to its business default or to not set. An empty string is never stored as a credential or as an override. When an environment variable still overrides the key at runtime, the command says so explicitly without printing its value.
+   *Migration*: replace `ebx config reset --yes` with one `ebx config set KEY ""` per key you want to clear (e.g. `ebx config set region ""`).
+
+2. **`ebx config list` shows effective values and their sources**.
+   Sources are annotated as `(env)`, `(user)`, `(default)` or `(not set)`. Keys with a real business default (`qwen_code_base_url`, `qwen_code_model`) show the concrete default; keys without one (`llm_api_key`, `llm_base_url`, `llm_model`) show `(not set)` instead of a blank `(default)`. Secrets stay masked.
+   *Migration*: consumers parsing `config list` output now see source suffixes and `(not set)` where the old output showed blank defaults.
+
+3. **`ebx config init` secret prompts echo one `*` per character**.
+   Previously typed secrets were completely invisible; now every typed or pasted character shows a single `*` (never the plaintext), with Backspace / Ctrl-C / EOF / Unicode handled correctly. Terminals that cannot render it fall back to the previous no-echo behaviour with an explicit notice.
+   *Migration*: no action required — the plaintext is never displayed in either mode.
+
+### Breaking Changes (ADR 2026-09-23 — Overdesign Cleanup)
+
+1. **`ebx template install` default behaviour changed: download → download+build+deploy**.
+   `install` now fetches the template sources and then builds the Docker image, pushes to ACR, and registers the template via the official API by default — cloud-side operations that can incur Alibaba Cloud costs (ACR storage/traffic, template resources). The previous download-only behaviour is available via `--download-only`.
+   *Migration*: add `--download-only` to `ebx template install` / `ebx install` invocations that should not build and deploy.
+
+2. **Removed `SerializerType.PICKLE` / `SerializerType.MSGPACK`**.
+   The `@sandbox` decorator now only supports `serializer="json"`. Non-JSON serializable return values must be converted to `dict`/`list`/`str` before returning.
+   *Migration*: change `@sandbox(serializer="pickle")` → `@sandbox(serializer="json")` and ensure return values are JSON-compatible.
+
+3. **Removed runtime `check_capability()` gate from most modules**.
+   `CommandsModule`, `FilesModule`, and `NetworkModule` no longer raise `CapabilityNotSupportedError` (E3004) at call time. **Exception: `CodeContextModule` retains the `code` capability gate** — all its methods (`run`, `create_context`, `list_contexts`, `restart_context`, `remove_context`) still raise E3004 when the `code` capability is missing (fail-closed). E3004 is also still raised during template resolution / model validation via `resolve_capabilities()`.
+   *Migration*: remove `try/except CapabilityNotSupportedError` around `commands.*`, `files.*`, and `network.*` calls; declare required capabilities in `template.yaml` instead. **Keep** `try/except CapabilityNotSupportedError` around `run_code()` / `code.*` calls if your template may lack the `code` capability.
+
+4. **Removed `easy_sandbox.integrations` sub-module**.
+   The LangChain/CrewAI/AutoGen adapter module was an empty abstract placeholder and has been deleted.
+   *Migration*: use `agent.tools` or MCP integration directly.
+
+5. **Removed `SessionStore` abstract base class**.
+   Only `LocalSessionStore` remains. The `session/base.py` ABC has been deleted.
+   *Migration*: if you were subclassing `SessionStore`, switch to `LocalSessionStore` or implement your own storage directly.
+
+6. **`SecretStore` changed from macOS Keychain to file-based storage**.
+   Secrets are now stored in `~/.ebx/secrets.json` (plaintext, chmod 600). Old Keychain entries are **not** automatically migrated.
+   *Migration*: re-add secrets via environment variables (`E2B_API_KEY`, `SANDBOX_API_KEY`) or `~/.ebx/.env` file. Use `ebx config set api_key <value>` to persist API keys.
+
+7. **Removed `ebx auth` CLI command group**.
+   The `ebx auth login/logout/status/switch` commands have been removed.
+   *Migration*: use `ebx config set api_key <value>` to persist credentials, or set `E2B_API_KEY` / `SANDBOX_API_KEY` environment variables directly.
+
+8. **Removed `ebx secret` CLI command group**.
+   The `ebx secret create/list/delete/inject` commands have been removed.
+   *Migration*: use environment variables or `.env` files to manage credentials and secrets. For sandbox environment injection, use `ebx create --env KEY=VALUE`.
+
+9. **Removed `ebx session` / `ebx sessions` CLI command group**.
+   The `ebx sessions list/info/rename/export/import/clean` and `ebx start/connect` commands have been removed.
+   *Migration*: session data is still stored locally in `~/.ebx/sessions/` by `LocalSessionStore`. Use the SDK's `Sandbox.connect()` API programmatically.
+
+10. **Removed `ebx skill` CLI command group**.
+   The `ebx skill search/install/list/create/publish` commands have been removed.
+   *Migration*: Skills system is a future planned feature. Use templates as the current capability distribution mechanism.
+
+11. **`Sandbox.run()` is now a bare-shell shortcut** (was named-command dispatcher).
+    `Sandbox.run(cmd)` now delegates to `sandbox.commands.run(cmd)` and returns `ProcessResult | StreamReader`. It no longer dispatches named custom commands.
+    *Migration*: replace `sandbox.run("name", **kwargs)` with `sandbox.custom("name", **kwargs)`.
+
+### Breaking Changes (ADR 2026-09-29 — init/create Semantics, partially superseded)
+
+> **Update (2026-09-29, ADR `2026-09-29-init-restore-and-create-explicit-error`):** item 1 below is **superseded** — the top-level `ebx init` shortcut has been **restored** as an exact alias of `ebx template init` (same click command object, option surface unchanged). Items 2–3 stand, and item 3 replaces the earlier "`ebx create` (no arguments) uses the `base` template" routing.
+
+1. ~~**Removed the top-level `ebx init` shortcut**.~~ **Superseded: restored.** The top-level `ebx init` shortcut is back and delegates to the exact same command object as `ebx template init` (options unchanged). Guided credentials setup remains `ebx config init`; cloud sandbox creation remains `ebx create`.
+   *Migration*: `ebx init [DIRECTORY]` and `ebx template init [DIRECTORY]` are interchangeable again.
+
+2. **`ebx create "DESCRIPTION" --template NAME` is now rejected**.
+   Previously `--template` silently won and the description was ignored. Passing both now raises a usage error (exit code 1) before any AI generation or network call — neither input is silently dropped.
+   *Migration*: keep DESCRIPTION for the Qwen Code AI path, or `--template` for a direct launch, but not both.
+
+3. **`ebx create` with no arguments is now an explicit usage error** (exit code 2).
+   Previously bare `ebx create` silently launched the `base` template. It now prints a routing hint (`--template base`, `--template <NAME>`, or `"DESCRIPTION"` for the AI path) so the choice is always explicit.
+   *Migration*: use `ebx create --template base` to launch the base template.
+
+### Changed (CLI UX)
+
+- **Unknown top-level commands now get targeted hints.** A close spelling candidate (e.g. `ebx crate`) gets a `Did you mean 'create'?` suggestion; with no plausible candidate the error points to template `custom_commands` (declared in `template.yaml`) and running them via `ebx run COMMAND`. Exit code 2 and stderr-only output are preserved; only the root group is affected.
+- **Top-level shortcut registration is explicit.** Built-in top-level shortcuts (`create`, `list`, `init`, `install`, `deploy`, `run`, …) are registered in the `LazyGroup(lazy_subcommands=...)` map in `src/easy_sandbox/cli/main.py` — a maintainer-facing registration point, not a user-facing extension mechanism. User-defined commands stay in `template.yaml` `custom_commands` (or the SandboxServer `@registry.command` registry) and are invoked through `ebx run`. The `config.toml [shortcuts]` section from the original CLI design draft was **never implemented** and is not a current capability.
+
+### Breaking Changes (ADR 2026-09-29 — qwen-code Session-Turns Parameter Unification)
+
+1. **Renamed the qwen-code session-turns parameter to `max_session_turns` / `--max-session-turns` everywhere** (SDK, CLI, qwen-code template `template.yaml`/`commands.py`, docs).
+   The old names were misleading: `Sandbox.deploy(max_tool_calls=...)`, `DeployModule.deploy_project(max_tool_calls=...)`, and `ebx deploy --max-tool-calls` all forwarded the value to qwen-code's official `--max-session-turns` flag (user/model/tool turn cap, exit code 53), not to the semantically different upstream `--max-tool-calls` budget (cumulative tool calls, exit code 55). The pre-existing template arg `max_turns` is renamed for the same reason and its default is unified to `100`.
+   *Migration*: rename `max_tool_calls=` → `max_session_turns=`, `--max-tool-calls` → `--max-session-turns`, and template arg `max_turns` → `max_session_turns`. Old names fail loudly (CLI usage error / SDK `TypeError`); no aliases are kept, matching the pre-release no-compat-shim policy.
+2. **`run_qwen_code_headless()` / `_build_headless_command()` accept an optional `max_session_turns` keyword** (`None` by default adds no flag). This is the stable naming contract for the natural-language `ebx create` pipeline and future headless callers.
+
+### Breaking Changes (Task 187 — Template Catalog Single Source of Truth)
+
+1. **The template catalog moved to the dedicated repository [`Easy-Sandbox/awesome-templates`](https://github.com/Easy-Sandbox/awesome-templates)**.
+   Template content, the machine-readable index (`awesome-templates.yaml`), releases and CI now live there — it is the single source of truth for official & community templates. This repository no longer bundles the template collection: `examples/templates/` keeps only a minimal `python-hello` **offline fixture**, explicitly marked as a fixture (not a publishing source). The repository-root `awesome-templates.yaml` has been removed.
+   *Migration*: instead of deploying a bundled folder (e.g. `ebx template deploy ./examples/templates/node-web`), install from the index (`ebx template install node-web`) or reference the source repo directly (`ebx template install Easy-Sandbox/awesome-templates//node-web@v1.0.0`).
+2. **`ebx template search` / `ebx template install <bare-name>` now resolve against the remote index** (cached under `~/.ebx/index/`). Bare names that are not builtins are looked up in the index; a miss triggers one forced refresh, and the resolved `owner/repo//subdir[@ref]` is printed (`Resolved '<name>' via the template index: ...`).
+   *Migration*: no action needed for direct `owner/repo` references; bare names must exist in the index. Use `--index-url` / `EBX_TEMPLATE_INDEX_URL` for private mirrors.
+
+### Added
+- **Remote template index client (`easy_sandbox.utils.template_index`)**: fetches `awesome-templates.yaml` from the SSOT repository via `raw.githubusercontent.com` (CDN — not subject to the API 60 req/hour anonymous limit), with a `~/.ebx/index/` cache, 1-hour TTL, `If-None-Match` revalidation, and explicit degraded modes (stale-cache fallback with a warning on network failures / rate limits / 5xx; loud errors with remediation when no cache exists; `schema_version` newer than supported fails with an upgrade hint). `--index-url` / `EBX_TEMPLATE_INDEX_URL` and `--token` / `GITHUB_TOKEN` are supported.
+- **`SKILL.md`**: Static Agent Skills–style usage guide at the repository root for AI coding tools and agents in other projects — covers when to use, install, credential safety (including never-leak rules), MCP vs SDK selection, sandbox create/execute/files/destroy workflows, and common error diagnosis. Referenced from `llms.txt`. Documentation only: the removed `ebx skill` command group, Skills registry, and runtime are **not** restored (ADR 2026-09-29). Shipped in the sdist but not the wheel (evidence: `tests/test_packaging.py`; guide/code consistency: `tests/test_agent_guide.py`).
+- **`Sandbox.custom(name, *, server_port=9000, **kwargs) -> CommandResult`**: New method for named custom-command dispatch. Uses A→B resolution: first tries template `custom_commands` (mechanism A), then falls back to `@registry.command` on SandboxServer (mechanism B). Returns `CommandResult` with `value`, `stdout`, `stderr`, `exit_code`, `execution_time`, `source` (`"template"` | `"server"`), and `success` property.
+- **`CommandResult` data model**: Structured return type for `custom()` replacing the bare `Any` that `run_command()` returned.
+- **`ebx template init`**: New scaffold command that generates a complete template project from built-in cases (`python`, `node`, `minimal`) or an existing registry reference (`--from`). Includes interactive case selection on TTY.
+- **`github_token` config key (`ebx config set github_token`)**: persistent GitHub token for template downloads, mapped to the `GITHUB_TOKEN` environment variable and stored in `~/.ebx/.env` (chmod 600). In an interactive terminal the value may be omitted — the token is read through the existing masked (asterisk) input and never echoed; `ebx config get` / `ebx config list` show it masked, and `ebx config set github_token ""` removes it. Resolution order: `--token` > process `GITHUB_TOKEN` > stored `github_token` > no token.
+- **One-shot GitHub rate-limit onboarding (E5000)**: `ebx template search` / `ebx template install` (`ebx install`) now print the officially documented fine-grained PAT prefill URL when the anonymous limit (60/hour) is hit — public repositories need no extra permissions and a 90-day expiry is recommended. In an interactive terminal only, the CLI offers to store the token with masked input and retries the failed operation **exactly once**; declining, cancelling, or a retry that fails again surfaces the original error. CI / non-interactive sessions are told to inject `GITHUB_TOKEN` as a secret or to run `ebx config set github_token` in a terminal. The CLI never runs `gh auth token`, never opens a browser, and never prints or logs a token.
+- **Unified rate-limit guidance (`easy_sandbox.utils.github_token`)**: shared headline + remediation used by the registry tarball client and the template-index client; `owner/repo//subdir@ref` references are preserved verbatim in download errors (e.g. `Easy-Sandbox/awesome-templates//codex-agent-api@v1.0`).
+
+### Deprecated
+- **`Sandbox.run_command()` / `Sandbox.run_command_sync()`**: Deprecated in favour of `Sandbox.custom()` / `Sandbox.custom_sync()`. Both deprecated methods wrap `custom()` internally but only return `result.value` (type `Any`) for backward compatibility — the full `CommandResult` (with `stdout`, `stderr`, `exit_code`, `execution_time`, `source`, `success`) is discarded. If you were treating the old return value as a `ProcessResult`, migrate to `custom()` / `custom_sync()` which return the complete `CommandResult`. Will be removed in a future release.
+
+### Breaking Changes (Official CreateTemplate API convergence)
+
+1. **`ebx template build-local` was removed and replaced by `ebx template build`**.
+   The old `build-local` command name no longer exists (invoking it fails with `No such command 'build-local'`). `ebx template build` runs the full pipeline: local Docker build → ACR push → template registration, and `ebx template deploy` remains an alias invoking the same pipeline.
+   *Migration*: replace `ebx template build-local <DIR>` with `ebx template build <DIR>` (same option surface).
+
+2. **`ebx template build` / `template deploy` default to the official CreateTemplate API**.
+   The legacy v3/v2 platform API is no longer the default; it remains available behind the explicit `--legacy-api` flag (the approved convergence decision — the default switched to the official API while the legacy code path stays behind a flag). The ACR push and the remote template registration are cloud-side operations that can incur Alibaba Cloud costs (ACR storage/traffic, template resources).
+   *Migration*: scripts needing the legacy v3/v2 behaviour must pass `--legacy-api` explicitly.
+
+### Changed
+- **`--token` is documented as a temporary override**: `ebx template install` / `ebx template search` help now warns that `--token <value>` may leak into shell history and process listings, and recommends the persistent `ebx config set github_token` as the default fix.
+- `commands.run()`, `commands.stream()`, and `commands.start()` now auto-wrap commands containing unquoted shell operators (`|`, `;`, `&&`, `||`, `>`, `<`, `(...)`, `$(...)`) in `sh -c`. Variable expansion (`$VAR`), backticks, and globs still require explicit `sh -c '...'`.
+- **`ebx template build` (renamed from `build-local`)**: default mode switched to the **official CreateTemplate API** (`--official-api`). Legacy v3/v2 behaviour now requires an explicit `--legacy-api` flag.
+- **Official template path prerequisites**: `ebx template create` and `ebx template build` (default mode) now require the `alicloud` extra (`pip install "easy-sandbox[cli,alicloud]"` or `pip install "easy-sandbox[alicloud]"`) and Alibaba Cloud AK/SK credentials.
+- When `envdInject` is enabled and `--target-image` is omitted, `copy.image` is now auto-derived with a `-fcsandbox-<hex>` random suffix to satisfy the platform requirement that `copy.image` must differ from `sandboxConfig.image`. For a stable tag, pass `--target-image` explicitly.
+
+### Migration
+- Replace `ebx template build-local <DIR>` with `ebx template build <DIR>` — the old command name was removed.
+- Existing automation scripts invoking the build pipeline without `--legacy-api` now hit the official CreateTemplate API. To preserve the legacy v3/v2 behaviour, add `--legacy-api` to the command.
+- **Automation / CI hardening**: pass `--acr-namespace` and the template directory explicitly on the command line instead of relying on `ACR_NAMESPACE` / `EBX_TEMPLATE_DIR` environment variables or `.env` files, so builds cannot silently drift with the surrounding environment. For `ebx template install` / `ebx install`, either pass `--acr-namespace` explicitly or use `--download-only` when the pipeline must not touch the cloud at all.
+
+
+### Added
+- **Server Module**: Container-side HTTP server (`easy_sandbox.server`) expanded from 6 to 42 endpoints across 8 capability groups (CORE, COMMANDS, FILE_OPS, PROCESS, SYSTEM, TERMINAL, DEV_TOOLS, BROWSER)
+- **Server CapabilityGroup.BROWSER**: New browser automation capability group with 8 Playwright-backed endpoints (navigate, screenshot, content, click, type, evaluate, pdf, console)
+- **Server PTY Terminal**: WebSocket-based interactive PTY terminal system with session management (REST create/list/delete + WebSocket I/O)
+- **Server SSE Shell**: Streaming shell execution via Server-Sent Events (`POST /shell/stream`) for real-time command output
+- **Server RouteTable**: Declarative route registry replacing if/elif dispatch; capability groups can be toggled at runtime or via `EBX_SERVER_DISABLED_GROUPS` env var
+- **CLI `ebx sandbox files`**: 6 file-operation subcommands — `list`, `stat`, `mkdir`, `rm`, `mv`, `search`
+- **CLI `ebx sandbox process`**: 4 process-management subcommands — `list`, `start`, `info`, `signal`
+- **CLI `ebx sandbox system`**: 5 system-info subcommands — `info`, `env`, `ports`, `packages`, `metrics`
+- **CLI `ebx sandbox capabilities`**: Show supported capability groups of a sandbox
+- **CLI `ebx sandbox shell-stream`**: Real-time streaming command execution (SSE-backed)
+- **CLI Global Options**: Added `--ci` (CI/CD mode: quiet + no-color + json), `--log-level` (explicit DEBUG/INFO/WARNING/ERROR)
+- **CLI OutputManager**: Unified output manager (`cli/output.py`) with TTY/CI auto-detection, replacing ad-hoc click.echo calls
+- **Template Migration**: All 10 templates migrated to new `CapabilityGroup` API
+- **Core SDK**: `Sandbox` class with `create()`, `connect()`, `kill()`, `run_code()` and async context manager
+- **Commands Module**: `run()`, `stream()`, `start()` for executing commands in sandboxes
+- **Files Module**: `read()`, `write()`, `list()`, `upload()`, `download()`, `exists()`, `remove()`, `make_dir()`
+- **Network Module**: Port URL and access headers calculation (`get_host()`, `get_url()`, `get_access_headers()`).
+- **Code Interpreter**: `run()` for code execution with multi-language support
+- **CLI (`ebx`)**: `create`, `list`, `info`, `kill`, `exec`, `shell`, `auth`, `config` commands
+- **Dual Authentication**: API Key (`SANDBOX_API_KEY`) and AK/SK (`ALICLOUD_ACCESS_KEY_ID/SECRET`)
+- **Connect Protocol**: Full `application/connect+json` implementation with Server-Streaming support
+- **Transport Layer**: HTTP/2 connection pooling, WebSocket with heartbeat/reconnect, layered configuration
+- **Error System**: Structured exceptions with error codes (E1001-E5002), suggestions, and docs URLs
+- **E2B Compatibility**: Drop-in compatible `compat.Sandbox` wrapper
+- **Output Formats**: Table (rich), JSON, and quiet modes for CLI
+- **Sync Support**: All async methods have synchronous variants via `run_sync()`
+- **Community Template Index**: `awesome-templates.yaml` — curated index of official and community sandbox templates
+
+### Changed
+- **Network Module**: Removed experimental `expose()` and `list_ports()` APIs in favor of a simpler local URL calculation interface based on official documentation. Port URL is now computed client-side as `https://{port}-sbx-{sandbox_id}.{domain}`.
+
+### Architecture
+- Six-layer architecture: Transport → Protocol → Extensions → API → Declarative → Agent Integration (+ CLI + Server)
+- Async-first design with sync wrappers
+- Lazy imports for fast CLI startup (< 200ms)
+- Domain-partitioned HTTP connection pools (Platform API vs envd API)

easy_sandbox-0.1.0/LICENSE

@@ -0,0 +1,200 @@
+
+                                 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 the 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 the 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 any 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. Please also get an overview of
+      how to use the license at http://www.apache.org/foundation/license-faq.html.
+
+   Copyright 2026 Anycodes
+
+   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.

easy_sandbox-0.1.0/NOTICE

@@ -0,0 +1,14 @@
+Easy Sandbox
+Copyright 2026 Anycodes
+
+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.