amberjs 1.17.0

中文文档

What is this?

amber runs .js / .ts / .tsx on V8. TypeScript is stripped by oxc — there is no project-wide tsc step.

Use it when you want one binary that can:

• run scripts and a REPL
• run Jest-style tests
• host agent tools behind a capability sandbox (--sandbox, --seed, --freeze-time)
• speak MCP / JSON-RPC over stdio
• do in-process tensors via amber:ai (no Python sidecar)

It is not a drop-in Node.js replacement. APIs land incrementally and are scored in tests/conformance/ (55/55 on Node.js Conformance 5.0). Closest cousins: Deno (V8 + Rust, permissioned) and Bun (all-in-one CLI). Amber keeps V8, adds an agent/MCP host, and labels every command Stable / Preview / Experimental.

The only user-facing capability map is Current Scope. Historical docs/STAGE_* numbers are not current facts.

Install

Prebuilt archives: macOS (arm64, x64), Linux gnu (x64, arm64), Windows (x64 zip).

# macOS / Linux
curl -fsSL https://get.amberjs.com/install.sh | sh

# pin a release
curl -fsSL https://get.amberjs.com/install.sh | AMBER_VERSION=v1.17.0 sh

Windows (PowerShell):

irm https://get.amberjs.com/install.ps1 | iex

Homebrew (formula in this repo; SHA256 is rewritten on each GitHub Release):

brew install zh30/tap/amber

crates.io (each GitHub v* tag publishes via Release Assets + CARGO_REGISTRY_TOKEN; install the amber binary):

cargo install amberjs

amber --version
amber eval "1 + 1"

Build from source

Needs Rust (1.97.1, pinned) and a C++ toolchain for V8.

git clone https://github.com/zh30/amberjs.git
cd amberjs
cargo build --release
./target/release/amber --version

60-second tour

// hello.ts
const runtime = "Amber";
console.log(`hello from ${runtime}`);

amber run hello.ts
# hello from Amber

amber eval "console.log(crypto.randomUUID())"
amber repl

Thrown stacks map back to .ts lines when a source map is present. There is still no tsc --noEmit in the runtime; use that in CI if you want typechecking.

Jest-style tests (Stable since v1.15.0):

// math.test.js
describe("math", () => {
  test("adds numbers", () => {
    expect(2 + 3).toBe(5);
  });
});

amber test
amber test examples/testing/math.test.js
amber test --watch

amber test --parallel is rejected (exit code 2): V8 isolates are not shared across threads.

WinterCG-style HTTP (Preview):

// app.js
module.exports = {
  fetch() {
    return new Response("ok");
  },
};

amber serve app.js --host 127.0.0.1 --port 3000

Agents, sandbox, MCP

Default-deny I/O for tool processes, deterministic clocks/PRNG, stdio MCP.

amber run --sandbox --permission-policy examples/agent/echo.policy.json \
  --export-tools examples/agent/echo_tool.ts

amber session --sandbox --permission-policy examples/agent/echo.policy.json \
  examples/agent/echo_tool.ts

amber mcp --inspect examples/agent/echo_tool.ts

amber:ai

Stable builtins — no native addon, no Python process:

import { Tensor, LLM, AgentPipeline } from "amber:ai";

const a = Tensor.from([1, 2, 3, 4], [2, 2]);
const b = Tensor.from([5, 6, 7, 8], [2, 2]);
const c = Tensor.matmul(a, b);

LLM (load, generate, generateStream, embed) and AgentPipeline are in the manual. Cargo feature = "ai" is empty and is not a product LLM.

CLI

Stable — everyday commands:

amber run <file> [args...]     Run JS (TS/TSX via oxc)
amber eval <code>              Evaluate an expression
amber test [files...] [--watch]
amber repl
amber snapshot [build|status|clean]
amber session <tool>           JSON-RPC over stdin
amber mcp [tool]               MCP stdio server
amber compile <file> [-o myapp]  Host SEA (linux/macos/windows). Contract: docs/COMPILE_CONTRACT.md
amber install [--frozen-lockfile]  Direct package.json deps. Not npm. Contract: docs/INSTALL_CONTRACT.md
amber --version | amber version
amber bundle <entry> [-o dist/bundle.js] [--minify]

Preview — present, contract still tightening:

amber serve [--https --cert --key]
amber run --inspect / --inspect-brk
TypeScript / TSX execution

Experimental — do not treat as product promises: amber debug, amber init / create / add / remove / prune / x / upgrade, N-API hello process.dlopen, fmt / lint / task / bench / profile / deploy. amber install is the Stable exception above; it is not a full npm install.

Full flags: CLI usage guide.

Compatibility

Node modules that exist today include fs, path, os, url, buffer, events, stream, crypto, http, http2, net, child_process (execSync / spawnSync), zlib, util, worker_threads. Web: fetch, Streams, Web Crypto, URL, Worker. Coverage is per-API, not “Node compatible.” WinterTC baseline: DOMException, URLPattern, ReadableStream.from, amber:sockets, import.meta.main.

On Apple M2 Max (2026-09-16), suite 2.0 URL / fetch / ReadableStream beat Node.js; Express on Amber was ~68k req/s vs Node ~19k. Numbers live in benchmarks/ with command, hardware, and a correctness check. This README does not reprint them as product SLAs.

Editors

• VS Code: extensions/vscode — amber lsp + inspector attach. Install the local .vsix; Marketplace is not shipped.
• Zed: extensions/zed — Install as a Dev Extension; amber must be on PATH.

amber lsp
amber run --inspect-brk app.ts

Documentation

Contributing

cargo test --lib
cargo test --test wintertc_compliance_tests -- --test-threads=1
cargo clippy --all-targets -- -D warnings
cargo fmt --all -- --check

See AGENTS.md for module boundaries (src/main.rs is the amber entry; do not treat every directory under src/ as a public API).

License

MIT