A drop of
JavaScript, sandboxed.

A sandbox-first ECMAScript runtime and toolchain for AI agents. The host defines the available capabilities, runtime surface, and execution limits.

Open the Playground Read the docs

bash
curl -fsSL https://www.gocciascript.dev/install | sh

Latest version 0.13.0 released August 19, 2026

View install script Other install options →

Pre-1.0: the API is still in motion — expect breaking changes between any two releases until 1.0.

coffee-typed.ts

// Types, enums, private fields.
type Currency = "USD" | "EUR" | "GBP";

enum DrinkSize {
  Small = "small",
  Medium = "medium",
  Large = "large",
}

interface MenuItem {
  name: string;
  basePrice: number;
}

class CoffeeShop {
  #name: string = "Goccia Coffee";
  #menu: MenuItem[] = [
    { name: "Espresso", basePrice: 2.5 },
    { name: "Latte", basePrice: 4.0 },
  ];

  total(
    items: string[],
    size: DrinkSize,
    currency: Currency,
  ): string {
    const m =
      size === DrinkSize.Large ? 1.3 :
      size === DrinkSize.Medium ? 1.1 : 1.0;
    const sub = items.reduce((s, it) => {
      const f = this.#menu
        .find((x) => x.name === it);
      return s + (f ? f.basePrice * m : 0);
    }, 0);
    const sym: Record<Currency, string> = {
      USD: "$", EUR: "€", GBP: "£",
    };
    return `${sym[currency]}${sub.toFixed(2)}`;
  }

  get name(): string {
    return this.#name;
  }
}

const shop = new CoffeeShop();
const total = shop.total(
  ["Espresso", "Latte"],
  DrinkSize.Medium,
  "EUR",
);
console.log(`Welcome to ${shop.name}!`);
console.log(`Your total: ${total}`);

// Types, enums, private fields.
type Currency = "USD" | "EUR" | "GBP";

enum DrinkSize {
  Small = "small",
  Medium = "medium",
  Large = "large",
}

interface MenuItem {
  name: string;
  basePrice: number;
}

class CoffeeShop {
  #name: string = "Goccia Coffee";
  #menu: MenuItem[] = [
    { name: "Espresso", basePrice: 2.5 },
    { name: "Latte", basePrice: 4.0 },
  ];

total(
    items: string[],
    size: DrinkSize,
    currency: Currency,
  ): string {
    const m =
      size === DrinkSize.Large ? 1.3 :
      size === DrinkSize.Medium ? 1.1 : 1.0;
    const sub = items.reduce((s, it) => {
      const f = this.#menu
        .find((x) => x.name === it);
      return s + (f ? f.basePrice * m : 0);
    }, 0);
    const sym: Record<Currency, string> = {
      USD: "$", EUR: "€", GBP: "£",
    };
    return `${sym[currency]}${sub.toFixed(2)}`;
  }

get name(): string {
    return this.#name;
  }
}

const shop = new CoffeeShop();
const total = shop.total(
  ["Espresso", "Latte"],
  DrinkSize.Medium,
  "EUR",
);
console.log(`Welcome to ${shop.name}!`);
console.log(`Your total: ${total}`);

press Run or ⌘+Enter

ECMAScript compatibility

The implementation is broader than the recommended profile.#

GocciaScript implements core ECMAScript. Modern, explicit forms are enabled by default; every standard core form disabled by the recommended profile has an explicit compatibility path. Normal hosts do not install eval, which is exposed only by the private test262 conformance host.

Current generated evidence: 52,281 of 52,492 cases pass in the latest published non-Annex-B test262 run. Open the live compatibility dashboard.

Modern by default

Modern ECMAScript forms first — let/const, arrow functions, classes, modules, async/await.

Sandbox-first

AI-agent execution with seeded VFS snapshots, explicit modules and capabilities, structured results, and host-owned limits.

Explicit over clever

Strict equality and explicit imports by default; compatibility flags are reserved for conformance and legacy semantics.

A modern standard library, batteries included

Temporal for dates, and direct module imports of JSON, JSON5, TOML, YAML, CSV, TSV, JSONL and Markdown.

Vitest-compatible testing

Write tests the way you already do — describe/test/expect, lifecycle hooks, and mocks — with semantics probed against a pinned Vitest release, in a single native binary.

Recommended language profile

Implemented, with explicit defaults#

The profile is host policy, not a list of missing language features. The table distinguishes implemented semantics from their default exposure. See Language for the per-feature rationale.

Form	Implemented	Default	Enablement / exposure	Source
var	Yes	Disabled	`--compat-var`	ECMA-262 core
function	Yes	Disabled	`--compat-function`	ECMA-262 core
== / !=	Yes	Disabled	`--compat-loose-equality`	ECMA-262 core
ASI	Yes	Disabled	`--compat-asi`	ECMA-262 core
labels	Yes	Disabled	`--compat-label`	ECMA-262 core
for (;;)	Yes	Disabled	`--compat-traditional-for-loop`	ECMA-262 core
for...in	Yes	Disabled	`--compat-for-in-loop`	ECMA-262 core
while / do...while	Yes	Disabled	`--compat-while-loops`	ECMA-262 core
arguments	Yes	Disabled	`--compat-arguments-object`	ECMA-262 core
non-strict Script	Yes	Strict	`--compat-non-strict-mode`	ECMA-262 core
with	Yes	Disabled	`--compat-non-strict-mode`	ECMA-262 core
eval	Yes	Not installed	`private --test262-host`	ECMA-262 core
Function()	Yes	Disabled	`--unsafe-function-constructor`	ECMA-262 core
ShadowRealm	Yes	Not installed	`--unsafe-shadowrealm`	TC39 Stage 2.7

Compatibility flags primarily serve ECMAScript conformance and existing code. Dynamic source exposure is separate: normal hosts do not install eval, and Function() requires the explicit --unsafe-function-constructor opt-in.

Runtime surface

Beyond the language: runtime and sandbox APIs#

A broad ECMAScript surface, plus first-class structured-data formats — direct module imports of .json, .json5, .toml, .yaml, .csv, .tsv, .jsonl, and .md; runtime parsers for each (markdown imports return the raw text); import maps; console output; SemVer helpers; and a built-in test runner with a Vitest/Jest-compatible test/describe/expect API. In GocciaSandboxRunner, the sandbox surface adds import-only fs and goccia modules backed by a seeded virtual filesystem, sandbox shell commands, nested execution, and explicit diffs.

The sandbox fs module provides Node-compatible synchronous, callback, and promise methods over that virtual filesystem, including Stats objects and Node-shaped errors. GocciaScript is not a complete Node.js host: it does not provide CommonJS, npm package resolution, process, Buffer, or the general node: module set.

Native platform

Portable by design, embeddable by choice.#

FreePascal is the cross-platform toolchain. Delphi support covers the complete shipped Win32 and Win64 application matrix under the same runtime semantics. Native application embedding remains an important secondary goal.

FreePascal

Builds the cross-platform command-line toolchain and provides the documented native embedding path.

Delphi 12

Repository projects cover every shipped application on Win32 and Win64; the support contract includes all applicable Pascal and JavaScript tests.

Native embedding

Hosts can embed portable JavaScript and define application globals, modules, capabilities, limits, and result handling.

FAQ

GocciaScript questions, answered.#

Short answers to the questions people usually ask before trying or integrating the runtime.

GocciaScript is a JavaScript engine: a sandbox-first ECMAScript runtime and toolchain for AI agents. Hosts define the available capabilities, runtime surface, and execution limits. It uses modern recommended defaults while tracking ECMAScript compatibility through generated test262 reports. GocciaScript is implemented in FreePascal, supports Delphi, and can also be embedded in native applications.

Its primary goal is JavaScript execution for AI agents under an explicit, host-defined capability model. The same runtime and toolchain also serve sandboxed automation, portable native applications, plugins, and desktop scripting; native embedding is an important secondary goal.

GocciaScript implements core ECMAScript and publishes generated test262 results. Its recommended profile keeps var, traditional function syntax, loose equality, labels, traditional for loops, for...in, while/do...while, ASI, arguments, and non-strict Script semantics disabled by default, but each has an explicit compatibility path. Those defaults are product policy, not the implementation ceiling. Normal hosts do not install eval; the private test262 host exposes it for conformance. Broad Annex B browser compatibility is not a pre-1.0 target.

GocciaScript implements the TC39 Type Annotations proposal and its types-as-comments runtime model: supported annotations have no runtime effect by default. The optional --strict-types GocciaScript extension adds runtime enforcement for supported annotations and inferred primitive contracts in interpreter and bytecode modes. It is not a replacement for a static structural type checker such as tsc.

GocciaScript is not a complete Node.js host: it does not provide CommonJS, npm package resolution, process, Buffer, or the general node: module set. GocciaSandboxRunner does provide a Node-compatible fs API over its virtual filesystem, with synchronous, callback, and promise-based methods, Stats objects, and Node-shaped errors. The documented method set stays inside the sandbox and does not expose the ambient host filesystem.

GocciaScript's built-in runner uses the Vitest and Jest test API: describe, test, expect, lifecycle hooks, and mocks. Matcher and comparison semantics — equality, Set and Map, errors, and toThrow — are probed against a pinned Vitest release and reconciled against it, and shared differential suites run in CI against whichever runtime is the semantics oracle for each one: Vitest for the testing-API suites, Bun for the language suites, with Bun advisory on matcher and lifecycle behaviour rather than deciding it. Being a drop-in replacement is the direction, not a finished claim: importing vi from "vitest" resolves to a bundled compatibility shim that covers vi.fn, vi.spyOn, factory-form vi.mock (a synchronous arrow factory returning an object literal, with no automock and no spread-based partial mock), vi.unmock, vi.mocked, the global stubs (vi.stubGlobal, vi.unstubAllGlobals), and the bulk mock helpers (vi.clearAllMocks, vi.resetAllMocks, vi.restoreAllMocks), so suites built on those run unchanged; vi.stubEnv and vi.unstubAllEnvs work over a host-injected process.env, since the engine has no process of its own, and members the shim does not implement — the fake-timer family, vi.waitFor, vi.waitUntil, vi.hoisted, vi.doMock, vi.doUnmock, vi.resetModules, vi.importActual, vi.importMock, vi.setConfig, and vi.resetConfig — throw a named error instead of failing quietly; vi is reached through that import rather than as an ambient global, and a few divergences are deliberate. Suites run as a single native binary with no Node.js installation or transform step in front of them, which is a statement about what a run has to do rather than about raw engine throughput.

No. It implements selected web-standard APIs where they fit the sandboxed runtime and embeddable-platform goals, but it does not provide a DOM, Web Workers, storage APIs, or a full browser event loop.

FreePascal is GocciaScript's cross-platform toolchain. The repository also includes Delphi 12 Community Edition projects for the complete shipped Win32 and Win64 application matrix. The Delphi support contract covers every shipped application and all applicable Pascal and JavaScript tests, with shared runtime semantics across both compilers.

GocciaScript is still pre-1.0, so APIs and compatibility behavior can change between releases. Its current test262 results already make it suitable for serious experiments and bounded production use where the supported surface matches your needs.

Scripts have no ambient host filesystem, process, native FFI, or network authority by default. GocciaSandboxRunner imports explicit seed baselines into a virtual filesystem, exposes fs/goccia as import-only modules, and reports sandbox writes as diffs instead of writing back to host paths.

GocciaScript tracks ECMAScript compatibility through generated test262 reports. The compatibility dashboard shows the current main-branch result set.

Use the playground in the browser, or install the command-line tools from the installation guide.

Compiler pipeline

From source to result.#

One pipeline, five stages. Click a stage to jump into the matching docs chapter — start with Architecture.

Step 1 of 5

Source

Every supported extension enters the same source pipeline. GocciaScript implements the TC39 Type Annotations proposal, so supported annotations have no runtime effect by default; --strict-types optionally adds runtime contracts. JSX is rewritten to function calls in a preprocessing pass before lexing.

example.js

1
2
3
4
const price = 2.5;
const qty = 3;
const total = price * qty;
console.log("total:", total);

A drop ofJavaScript, sandboxed.