Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions .agents/skills/layerfs-js-sdk/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ description: Use when building, editing, testing or inspecting a project through
> Workspace API and idle close are #373's (section 8 of
> [its design](../../../core/docs/issues/373/README.md)). The `@layerfs/agent`
> package, its client factories and the `sandbox` methods are #428's
> ([its design](../../../core/docs/issues/428/layerfs-agent.md)). There is no
> placement since 2026-10-23 (owner): a mount names its Sandbox.
> ([its design](../../../core/docs/issues/428/layerfs-agent.md)). A mount names its
> Sandbox, and a Sandbox names its platform (#529); the home decides where Stores live.

Your project lives in LayerFS, not on your local disk. You read and change it through
the SDK, from small Node scripts you run with `node`.
Expand Down Expand Up @@ -101,8 +101,9 @@ Commit, so for one small read or edit prefer `fs.*`.
pass it to `exec`, `commit` and `unmount`. Two mounts of one Branch are two
separate Workspaces, and a Workspace is never valid after its unmount.
- **You name the Sandbox.** A project's Sandboxes are numbered `1`, `2`, …, each a
container holding up to 16 Workspaces on one image (`LAYERFS_IMAGE`, or
`sandbox.create({ image })`). `sandbox.create()` starts one and returns its number;
container (or daemon process) holding up to 16 Workspaces on one image
(`LAYERFS_IMAGE`, or `sandbox.create({ image })`) and one platform (the home's
default, or `sandbox.create({ platform })`). `sandbox.create()` starts one and returns its number;
`workspace.mount(sandbox, branch)` mounts there and never starts one. When a mount
is refused `NoSuchSandbox` (it closed itself) or `Capacity` (16 Workspaces), do what
its message says: `sandbox.create()` a new one, or `sandbox.list_workspaces(sandbox)`
Expand Down Expand Up @@ -153,7 +154,7 @@ overwrite it.
| Branch | A named line of Commits. `main` changes only through `branch.publish`; work on your own Branch | `branch` |
| Files | Read and change files on a Branch directly. Every write is one immutable Commit; `fs.apply` makes many changes as one | `fs` |
| Workspace | A complete, writable view of a Branch where ordinary commands run, `{ sandbox, path }`. `workspace.commit` saves **everything** in it: `node_modules`, `.git`, build output, caches | `workspace` |
| Sandbox | A numbered container running one LayerFS daemon, holding up to 16 Workspaces. LayerFS starts one when a mount needs it, or you `create` one; it closes itself when idle | `sandbox`, `project.list_sandboxes` |
| Sandbox | A numbered container (or daemon process, by its platform) running one LayerFS daemon, holding up to 16 Workspaces. You `create` one; a mount never starts one; it closes itself when idle | `sandbox`, `project.list_sandboxes` |

## Import the SDK

Expand Down Expand Up @@ -373,7 +374,7 @@ method, its arguments, result fields, refusals with what to do, limits and examp
| [fs writes](references/methods/fs-write.md) | `write(branch, path, content, message?)`, `edit(branch, path, oldText, newText, message?)`, `apply(branch, changes, message?)`, `mkdir(branch, path, message?)`, `rm(branch, path, message?)`, `cp(branch, from, to, message?)`, `mv(branch, from, to, message?)` |
| [branch](references/methods/branch.md) | `fork(name, fromRef?)`, `list_commits(branch, pageSize?, pagePos?)`, `diff_commits(from, to, pageSize?, pagePos?)`, `diff_branches(from, to, pageSize?, pagePos?)`, `merge(a, b, name, message?)`, `publish(branch, commit?)` |
| [sandbox](references/methods/sandbox.md) | `create(options?)`, `list_workspaces(sandbox, pageSize?, pagePos?)`, `close(sandbox)` |
| [workspace](references/methods/workspace.md) | `mount(sandbox, branch)` → `{ sandbox, path, image }`, `exec(ws, command, message?)`, `commit(ws, message?, force?)`, `unmount(ws, discard?, force?)` |
| [workspace](references/methods/workspace.md) | `mount(sandbox, branch)` → `{ sandbox, path, image, platform }`, `exec(ws, command, message?)`, `commit(ws, message?, force?)`, `unmount(ws, discard?, force?)` |

A `ref` is `main`, a Branch name, a Commit id or a Layer id. Paths are absolute in the
view (`/src/index.js`). Pages are `{ items, hasMore }`; advance with
Expand Down
6 changes: 4 additions & 2 deletions .agents/skills/layerfs-js-sdk/references/methods/project.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,8 +147,10 @@ that closed itself or whose container is gone is left out (the runtime reclaims
| `pagePos` | number | no | Offset, default 0 |

**Returns:** a page `{ items, hasMore, nextPagePos }`. Each item is
`{ sandbox, name, image, workspaces }`: its number, its container name, the image digest
it runs (one project's Sandboxes may differ) and how many Workspaces it holds.
`{ sandbox, name, image, platform, workspaces }`: its number, its container name, the
image digest it runs (`null` for a `mac` or native `linux` one; one project's Sandboxes
may differ), its platform and how many Workspaces it holds. Every platform's running
Sandboxes are listed.

```js
const { items } = await layerfs.project.list_sandboxes();
Expand Down
19 changes: 11 additions & 8 deletions .agents/skills/layerfs-js-sdk/references/methods/sandbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@

Examples use `layerfs` as connected in [SKILL.md](../../SKILL.md#connect-to-a-project).

**A mount names its Sandbox.** There is no placement: `sandbox.create()` is the only call
that starts a Sandbox, and `workspace.mount(sandbox, branch)` mounts in the one it
names. A Sandbox holds up to 16 Workspaces of any Branches; reuse one with room (see
**A mount names its Sandbox.** `sandbox.create()` is the only call that starts a
Sandbox, and `workspace.mount(sandbox, branch)` mounts in the one it names. A Sandbox
names its platform (#529); every later call on it follows that, not your settings. A Sandbox holds up to 16 Workspaces of any Branches; reuse one with room (see
`project.list_sandboxes()`), or create one, and close it when you're done.

```js
const own = await layerfs.sandbox.create(); // { sandbox: "2", image }
const own = await layerfs.sandbox.create(); // { sandbox: "2", image, platform }
try {
const ws = await layerfs.workspace.mount(own.sandbox, "work");
try {
Expand All @@ -37,10 +37,12 @@ numbers are used again.

| Arg | Type | Required | Meaning |
| --- | --- | --- | --- |
| `options.image` | string | no | Exact local image digest `sha256:<64 hex>`; default `LAYERFS_IMAGE`. Every Workspace mounted there runs on it |
| `options.image` | string | no | Exact local image digest `sha256:<64 hex>`. Default: `LAYERFS_IMAGE` for `docker`; for `linux` and the VM platforms, the image `LAYERFS_IMAGE_ARCHIVE` holds (its config digest). Every Workspace mounted there runs on it |
| `options.platform` | string | no | `docker`, `mac`, `linux`, `apple-container`, `microsandbox`, `lima`, `firecracker` or `ssh`; default your home's. Your home allows only some (a Linux home `docker` and `linux`; a `vm:` home its provider; macOS and Windows `docker`, or `mac` with `LAYERFS_SANDBOX=native`) |

**Returns:** `{ sandbox, image }`: its number (pass it to `workspace.mount`) and its
image. Its container is named `<prefix><project>-<n>`.
**Returns:** `{ sandbox, image, platform }`: its number (pass it to `workspace.mount`),
its image (`null` for a `mac` or native `linux` one) and its platform. Its container,
or daemon folder, is named `<prefix><project>-<n>`.

**Refusals**

Expand All @@ -49,7 +51,8 @@ image. Its container is named `<prefix><project>-<n>`.
| `Failed` | Starting it failed. With `detail.removed: true` its container is already removed and nothing of it is left, and `detail.log` holds its daemon's last log lines (also in the message); otherwise it names what stays | Stop and report the message |
| `Unknown` | An earlier Sandbox start of this project has an unknown outcome; every start is refused until it is resolved | Stop and report the message, which says what a person must remove; don't remove or retry anything yourself |
| `Busy` | Another call held the project's lock for 60 seconds | Stop and report |
| `InvalidInput` | A missing `LAYERFS_*` deployment variable or an image that isn't a digest | Check the environment ([SKILL.md](../../SKILL.md#connect-to-a-project)) |
| `InvalidInput` | A missing `LAYERFS_*` deployment variable, an image that isn't a digest, or a platform that is not one of the eight names (`windows`, `native` and `namespaces` are not platforms) | Check the environment ([SKILL.md](../../SKILL.md#connect-to-a-project)) |
| `Unsupported` | Your home does not allow that platform; the message names what it allows | Leave `platform` out, or pick one it names |

**Notes:** like any Sandbox, it closes itself two minutes after its last Workspace is
unmounted, with no call in flight.
Expand Down
9 changes: 5 additions & 4 deletions .agents/skills/layerfs-js-sdk/references/methods/workspace.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,11 @@ a mounted Workspace of the Branch `"work"`, as `mount` returned it.

- A Workspace is `{ sandbox, path }`: the number of the Sandbox that holds it and its
path there. It persists: any later process with the same `LAYERFS_HOME` can use it.
- **A mount names its Sandbox; there is no placement.** A project's Sandboxes are
numbered `1`, `2`, …; each is a container with one LayerFS daemon and holds up to 16
Workspaces, of any Branches of the project. Each runs one image, set when
`sandbox.create()` starts it; one project's Sandboxes may run different images.
- **A mount names its Sandbox.** A project's Sandboxes are numbered `1`, `2`, …; each
is a container (or daemon process) with one LayerFS daemon and holds up to 16
Workspaces, of any Branches of the project. Each runs one image and one platform,
set when `sandbox.create()` starts it; one project's Sandboxes may differ in both, and
`mount` returns `{ sandbox, path, image, platform }`.
`sandbox.create()` is the only call that starts a Sandbox; `mount(sandbox, branch)`
never does ([sandbox](sandbox.md)).
- **A Sandbox closes itself when idle:** its daemon ends two minutes after its last
Expand Down
28 changes: 14 additions & 14 deletions api/agent/src/client.js
Original file line number Diff line number Diff line change
Expand Up @@ -69,12 +69,14 @@ export function sandboxArg(sandbox) {
* `sandboxBackend` (LAYERFS_SANDBOX_BACKEND), kept for one release, and
* refuses an unknown value or a conflicting pair, so this only checks that
* each value's fields are present and passes both settings on. `host` is
* the platform the Sandbox runs on (`sandboxHost`): native and namespaces are
* the OS the Sandbox runs on (Linux for a worker, see platform.js): native and namespaces are
* refused where they cannot run before anything is read. */
export function deployment(options = {}, postgresql = false, host = process.platform) {
const env = (name) => process.env[`LAYERFS_${name}`] || undefined;
const sandbox = options.sandbox ?? env("SANDBOX");
const backend = options.sandboxBackend ?? env("SANDBOX_BACKEND");
// a field the options name (even as undefined, for a platform's own
// runtime, #529) is not read from the environment
const sandbox = "sandbox" in options ? options.sandbox : env("SANDBOX");
const backend = "sandboxBackend" in options ? options.sandboxBackend : env("SANDBOX_BACKEND");
const named = { ...(sandbox !== undefined ? { sandbox } : {}), ...(backend !== undefined ? { sandboxBackend: backend } : {}) };
if (sandbox === "native" || sandbox === "namespaces") return localDeployment(options, env, named, host);
// another value is the binding's to refuse, naming the values it takes
Expand Down Expand Up @@ -102,12 +104,13 @@ export function deployment(options = {}, postgresql = false, host = process.plat
* daemon, the directory its Sandboxes live in and the optional name prefix.
* Native on Linux uses FUSE with a root daemon and nonroot commands (501:20);
* on macOS loopback NFS and this user. Namespaces (Linux) gives each Sandbox
* a root filesystem from an image, so it also needs `image` (LAYERFS_IMAGE,
* the same digest Docker deploys) and `imageArchive` (LAYERFS_IMAGE_ARCHIVE,
* the docker-archive the bundle carries). The former `native` with
* a root filesystem from an image, so it also needs `imageArchive`
* (LAYERFS_IMAGE_ARCHIVE, the docker-archive the bundle carries); its image
* is `image` when given, else the one image that archive holds (#529), which
* the binding reads; LAYERFS_IMAGE stays Docker's. The former `native` with
* `sandboxBackend` `namespaces` needs the same. `host` is the platform the
* Sandbox runs on: this process's, or Linux when a worker makes it (see
* `sandboxHost`). */
* platform.js). */
function localDeployment(options, env, named, host) {
const namespaces = named.sandbox === "namespaces" || named.sandboxBackend === "namespaces";
const setting = named.sandbox === "namespaces" ? "deploy.sandbox (LAYERFS_SANDBOX) namespaces"
Expand All @@ -129,9 +132,11 @@ function localDeployment(options, env, named, host) {
};
const required = [["daemon", "DAEMON"], ["localDir", "LOCAL_DIR"]];
if (namespaces) {
deploy.image = options.image ?? env("IMAGE");
deploy.imageArchive = options.imageArchive ?? env("IMAGE_ARCHIVE");
required.push(["image", "IMAGE"], ["imageArchive", "IMAGE_ARCHIVE"]);
// a field the options name (even as undefined, see platform.js) is not read from the environment
deploy.image = "image" in options ? options.image : deploy.imageArchive ? undefined : env("IMAGE");
if (!deploy.image) delete deploy.image;
required.push(["imageArchive", "IMAGE_ARCHIVE"]);
}
for (const [name, setting] of required) {
if (!deploy[name]) throw new LayerFSError("InvalidInput", `deploy.${name} is not configured (LAYERFS_${setting})`, null);
Expand All @@ -140,11 +145,6 @@ function localDeployment(options, env, named, host) {
return deploy;
}

/** The platform a client's Sandboxes run on: a worker (the macOS and
* Windows routes, or a `vm:` placement's VM) runs them on its Linux host;
* the addon in this process runs them here. */
export const sandboxHost = (client) => (transportOf(client).worker ? "linux" : process.platform);

/** Refuses every call on a closed client (or one no factory opened). */
export function live(client) {
if (client?.[STATE]?.closed !== false) {
Expand Down
15 changes: 9 additions & 6 deletions api/agent/src/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@
// constructor and no options argument: settings come from the environment.
// Calls name their Branch. `sandbox.create()` starts a Sandbox (the only
// call that does) and `sandbox.close` stops it; `workspace.mount(sandbox,
// branch)` returns a Workspace, `{ sandbox, path }`, in the Sandbox it names
// (there is no placement); the other Workspace calls take it. Store calls
// branch)` returns a Workspace, `{ sandbox, path }`, in the Sandbox it names;
// the other Workspace calls take it. A Sandbox names its platform (#529);
// the home still decides where Stores live. Store calls
// (fs, branch, project) run against the project's Store, opened in this
// process on Linux (#352 F-020) or in the LayerFS home's worker on macOS and
// Windows (transport/).
Expand Down Expand Up @@ -112,16 +113,18 @@ export class LayerFS {
* Sandbox this client starts runs _IMAGE
* on _VOLUME. LAYERFS_CONTAINER_PREFIX (default `layerfs-`) names every
* container it starts `<prefix><project>-<n>`. LAYERFS_SANDBOX picks the
* backend: `docker` (unset), `native` (Linux or macOS) or `namespaces`
* (Linux). Native starts each Sandbox as a host daemon in a directory
* home's default Sandbox backend: `docker` (unset), `native` (Linux or
* macOS) or `namespaces` (Linux); `sandbox.create({ platform })` may name
* another platform the home allows (#529, platform.js). Native starts each Sandbox as a host daemon in a directory
* under LAYERFS_LOCAL_DIR. Linux requires root for FUSE and runs commands
* as 501:20; macOS uses loopback NFS and the caller's identity. No Docker
* setting is read; native provides no isolation from the host. Namespaces
* adds Linux namespaces, a cgroup and an image root (LAYERFS_IMAGE,
* LAYERFS_IMAGE_ARCHIVE). The former LAYERFS_SANDBOX_BACKEND=namespaces
* beside LAYERFS_SANDBOX=native still means namespaces, for one release.
* The backend is read for every call, so a Sandbox made with one backend
* is never reopened as another.
* These settings are read once, when the client is made, and decide only
* what a new Sandbox starts with: every later call on a Sandbox follows
* its record (its platform and runtime), whatever the caller's settings.
* LAYERFS_DAEMON_HOST is the host this process
* dials for a daemon's port, published on the Docker host's 127.0.0.1 only;
* set it when the client runs in a container (`host.docker.internal` on
Expand Down
2 changes: 2 additions & 0 deletions api/agent/src/internal.js
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,10 @@
// from transport/worker_client.js: connection, endpointOf
// from transport/inprocess.js: addonPath
// from transport/index.js: useWorker
// from platform.js: PLATFORMS
export { STATE, invokeBackend, invokeClient, invokeClientBackend, live, outcome, page, pageOf, projectArgs, sandboxArg, storeArgs, workspaceArgs, deployment } from "./client.js";
export { decode, encode, frame, readFrames } from "./transport/frames.js";
export { connection, endpointOf } from "./transport/worker_client.js";
export { addonPath } from "./transport/inprocess.js";
export { useWorker } from "./transport/index.js";
export { PLATFORMS } from "./platform.js";
Loading
Loading