---
title: "carried"
description: "Carried mounts: content of another world, mounted read-only for this session at /zero/runtime/carried/<key>/ without installing it."
section: "API Reference"
slug: "api-carried"
canonical: "https://origozero.ai/docs/api-carried"
updated: "2026-10-25T22:44:44.730993403+00:00"
tags: ["api", "reference"]
---

# carried

Carried mounts: content of another world, mounted read-only for this session at `/zero/runtime/carried/<key>/` without installing it. A closure is named by the address of its manifest (`closureSha`, the sha-256 ZeroMind serves the manifest at); the engine reads the manifest and every file it names through the device's content cache, lays the files out the way their world places them, and states where the mount stands in `<key>/status`. Nothing a mount holds is content of the open world: it is in no listing of its assets, no dependency table, no push and no `zm status`, and the open world's code cannot `require` from it. A mount lives while some caller holds it and the session lasts.

`carried.mount(closureSha, { key = "ada.avatar" })` holds a mount and
starts filling it; `carried.wait(key)` yields until it settles;
`carried.status(key)` reads where it stands; `carried.release(key)`
lets go of it. `carried.mountDraft(assetPath)` mounts the closure of an
asset of the open world's working tree the same way, for a preview on
this engine. `carried.resolve(key, reference)` answers what a reference
written inside the closure names. `guides { path: "core/carried" }`
covers the whole surface.

```lua
require("@builtin::modules.api.engine.carried") -- carried (also available as global 'carried')
```

The `carried` namespace: 27 functions.

## globals/carried/heldBytes {#globals-carried-heldbytes}

```lua
carried.heldBytes() -> number
```

The bytes every carried mount holds in this engine's memory.

**Returns** `number` — Bytes.

```lua
print(carried.heldBytes())
```

## globals/carried/list {#globals-carried-list}

```lua
carried.list() -> { Status }
```

The status of every carried mount of this session.

**Returns** `{ Status }` — One status per mount.

```lua
for _, m in carried.list() do print(m.key, m.state) end
```

## globals/carried/manifest {#globals-carried-manifest}

```lua
carried.manifest(key: string) -> string?
```

The manifest of the ready mount at `key`: the JSON bytes the
content store served (`$schema` `zero/closure/v1`, `root`, and `entries`,
one per file and folder with its world `path`, `asset_guid`, `checksum`,
`size_bytes`, `kind` and `origin`, plus one `engine` entry per builtin it
was built against). Their sha-256 is the mount's `closureSha`. Nil until
the mount is ready.

**Parameters**

- `key` `string` — The mount's key.

**Returns** `string?` — The manifest's bytes, or nil.

```lua
local entries = require("@builtin::modules.json").decode(carried.manifest("ada.avatar")).entries
```

## globals/carried/mount {#globals-carried-mount}

```lua
carried.mount(closureSha: string, options: MountOptions?) -> Status
```

Hold the carried mount of the closure whose manifest address is
`closureSha` and start filling it, unless it is already held. The mount
stands at `/zero/runtime/carried/<key>/`; a key holds one closure for as
long as anyone uses it, and every `mount` of the same closure at the same
key holds it once more. Answers at once with the mount's status (`state`
`resolving` while it fills); `carried.wait` yields until it settles.
Raises when the key is malformed, `closureSha` is no sha-256, or the key
holds another closure.

**Parameters**

- `closureSha` `string` — The sha-256 hex digest of the closure's manifest.
- `options` `MountOptions` _(optional)_ — `key`: the mount's folder name (one path segment of letters,
digits, `.`, `_`, `-`), default `closure-<first 16 hex digits>`;
`commit`: the commit the closure was published at, stated in the status.

**Returns** `Status` — The mount's status.

```lua
local m = carried.mount(sha, { key = "ada.avatar" }); local s = carried.wait(m.key)
```

## globals/carried/mountDraft {#globals-carried-mountdraft}

```lua
carried.mountDraft(assetPath: string, options: MountOptions?) -> Status
```

Hold a draft carried mount of the asset at `assetPath`, an asset of
the open world's working tree (or of your home folder): the engine walks
the asset and every asset its files reference, writes that closure and
its manifest into the device's content cache, and mounts it from there
the way a published closure mounts, labelled `draft = true`. It is this
engine's alone. Mounting it again rebuilds it from the tree as it stands.
A draft holding a home folder's content is that folder's: it is made for
code that reaches the folder, and its files, listing, status and
manifest answer that code alone. Raises, naming the folder, when the
asset or anything it reaches is in a home folder the calling code does
not reach.

**Parameters**

- `assetPath` `string` — The asset, e.g. `/zero/source/chars/ada.avatar`.
- `options` `MountOptions` _(optional)_ — `key`: the mount's folder name, default `draft-<asset name>`.

**Returns** `Status` — The mount's status.

```lua
local d = carried.mountDraft("/zero/source/props/lamp.model"); carried.wait(d.key)
```

## globals/carried/release {#globals-carried-release}

```lua
carried.release(key: string) -> number
```

Let one holder of the mount at `key` go. The last one takes it
down: its folder leaves `/zero/runtime/carried/` and its bytes leave this
engine's memory, while the device's content cache keeps them for the
next mount. Raises when no mount is held at `key`.

**Parameters**

- `key` `string` — The mount's key.

**Returns** `number` — How many holders still hold it.

```lua
carried.release("ada.avatar")
```

## globals/carried/resolve {#globals-carried-resolve}

```lua
carried.resolve(key: string, reference: string) -> string?
```

What `reference`, written by content of the closure at `key`,
names: a guid the closure carries, a path of its world
(`props/lamp.model`, `/zero/source/props/lamp.model`) or an identity of
its world (`props.lamp`) answers the file inside the mount; a reference
to the engine library answers the library asset, taken to the version of
an engine builtin the closure was built against when the mount holds that
version. The open world's own content answers none of it. Nil when
nothing answers.

**Parameters**

- `key` `string` — The mount's key.
- `reference` `string` — A guid, path, identity or library reference.

**Returns** `string?` — A VFS path, or nil.

```lua
local tex = carried.resolve("ada.avatar", "chars.ada_albedo")
```

## globals/carried/status {#globals-carried-status}

```lua
carried.status(key: string) -> Status?
```

Where the mount at `key` stands, as `<key>/status` states it:
`state` is `resolving`, `fetching`, `measuring`, `ready`, `refused` or
`none`; `reason` is a word saying why nothing is mounted (`unreachable`,
`notFound`, `incomplete`) or why the closure was refused, with `detail`
the sentence; `bytesFetched` / `bytesTotal` count the files read;
`measured` counts files, folders and bytes per kind once ready;
`builtin` names how each engine builtin the closure was built against
resolves (`host`, `mount`, or `hostOtherVersion` with `why`). Nil when
no mount is held at `key`, and when the mount holds a home folder's
content the calling code does not reach.

**Parameters**

- `key` `string` — The mount's key.

**Returns** `Status?` — The status, or nil.

```lua
print(carried.status("ada.avatar").state)
```

## globals/carried/wait {#globals-carried-wait}

```lua
carried.wait(key: string, seconds: number?) -> Status
```

Yield until the mount at `key` settles (`ready`, `refused` or
`none`) or `seconds` pass, and answer its status then. Raises when no
mount is held at `key`, or when it holds a home folder's content the
calling code does not reach.

**Parameters**

- `key` `string` — The mount's key.
- `seconds` `number` _(optional)_ — How long to wait, default 120.

**Returns** `Status` — The status.

```lua
local s = carried.wait("ada.avatar", 30); assert(s.state == "ready", s.detail)
```

## modules/carried/heldBytes {#modules-carried-heldbytes}

```lua
heldBytes(): number
```

The bytes every carried mount holds in this engine's memory.

```lua
print(carried.heldBytes())
```

## modules/carried/list {#modules-carried-list}

```lua
list(): { Status }
```

The status of every carried mount of this session.

```lua
for _, m in carried.list() do print(m.key, m.state) end
```

## modules/carried/manifest {#modules-carried-manifest}

```lua
manifest(key: string): string?
```

The manifest of the ready mount at `key`: the JSON bytes the
content store served (`$schema` `zero/closure/v1`, `root`, and `entries`,
one per file and folder with its world `path`, `asset_guid`, `checksum`,
`size_bytes`, `kind` and `origin`, plus one `engine` entry per builtin it
was built against). Their sha-256 is the mount's `closureSha`. Nil until
the mount is ready.

**Parameters**

- `key` `string` — The mount's key.

```lua
local entries = require("@builtin::modules.json").decode(carried.manifest("ada.avatar")).entries
```

## modules/carried/mount {#modules-carried-mount}

```lua
mount(closureSha: string, options: MountOptions?): Status
```

Hold the carried mount of the closure whose manifest address is
`closureSha` and start filling it, unless it is already held. The mount
stands at `/zero/runtime/carried/<key>/`; a key holds one closure for as
long as anyone uses it, and every `mount` of the same closure at the same
key holds it once more. Answers at once with the mount's status (`state`
`resolving` while it fills); `carried.wait` yields until it settles.
Raises when the key is malformed, `closureSha` is no sha-256, or the key
holds another closure.

**Parameters**

- `closureSha` `string` — The sha-256 hex digest of the closure's manifest.
- `options` `MountOptions?` _(optional)_ — `key`: the mount's folder name (one path segment of letters,
digits, `.`, `_`, `-`), default `closure-<first 16 hex digits>`;
`commit`: the commit the closure was published at, stated in the status.

```lua
local m = carried.mount(sha, { key = "ada.avatar" }); local s = carried.wait(m.key)
```

## modules/carried/mountDraft {#modules-carried-mountdraft}

```lua
mountDraft(assetPath: string, options: MountOptions?): Status
```

Hold a draft carried mount of the asset at `assetPath`, an asset of
the open world's working tree (or of your home folder): the engine walks
the asset and every asset its files reference, writes that closure and
its manifest into the device's content cache, and mounts it from there
the way a published closure mounts, labelled `draft = true`. It is this
engine's alone. Mounting it again rebuilds it from the tree as it stands.
A draft holding a home folder's content is that folder's: it is made for
code that reaches the folder, and its files, listing, status and
manifest answer that code alone. Raises, naming the folder, when the
asset or anything it reaches is in a home folder the calling code does
not reach.

**Parameters**

- `assetPath` `string` — The asset, e.g. `/zero/source/chars/ada.avatar`.
- `options` `MountOptions?` _(optional)_ — `key`: the mount's folder name, default `draft-<asset name>`.

```lua
local d = carried.mountDraft("/zero/source/props/lamp.model"); carried.wait(d.key)
```

## modules/carried/release {#modules-carried-release}

```lua
release(key: string): number
```

Let one holder of the mount at `key` go. The last one takes it
down: its folder leaves `/zero/runtime/carried/` and its bytes leave this
engine's memory, while the device's content cache keeps them for the
next mount. Raises when no mount is held at `key`.

**Parameters**

- `key` `string` — The mount's key.

```lua
carried.release("ada.avatar")
```

## modules/carried/resolve {#modules-carried-resolve}

```lua
resolve(key: string, reference: string): string?
```

What `reference`, written by content of the closure at `key`,
names: a guid the closure carries, a path of its world
(`props/lamp.model`, `/zero/source/props/lamp.model`) or an identity of
its world (`props.lamp`) answers the file inside the mount; a reference
to the engine library answers the library asset, taken to the version of
an engine builtin the closure was built against when the mount holds that
version. The open world's own content answers none of it. Nil when
nothing answers.

**Parameters**

- `key` `string` — The mount's key.
- `reference` `string` — A guid, path, identity or library reference.

```lua
local tex = carried.resolve("ada.avatar", "chars.ada_albedo")
```

## modules/carried/status {#modules-carried-status}

```lua
status(key: string): Status?
```

Where the mount at `key` stands, as `<key>/status` states it:
`state` is `resolving`, `fetching`, `measuring`, `ready`, `refused` or
`none`; `reason` is a word saying why nothing is mounted (`unreachable`,
`notFound`, `incomplete`) or why the closure was refused, with `detail`
the sentence; `bytesFetched` / `bytesTotal` count the files read;
`measured` counts files, folders and bytes per kind once ready;
`builtin` names how each engine builtin the closure was built against
resolves (`host`, `mount`, or `hostOtherVersion` with `why`). Nil when
no mount is held at `key`, and when the mount holds a home folder's
content the calling code does not reach.

**Parameters**

- `key` `string` — The mount's key.

```lua
print(carried.status("ada.avatar").state)
```

## modules/carried/wait {#modules-carried-wait}

```lua
wait(key: string, seconds: number?): Status
```

Yield until the mount at `key` settles (`ready`, `refused` or
`none`) or `seconds` pass, and answer its status then. Raises when no
mount is held at `key`, or when it holds a home folder's content the
calling code does not reach.

**Parameters**

- `key` `string` — The mount's key.
- `seconds` `number?` _(optional)_ — How long to wait, default 120.

```lua
local s = carried.wait("ada.avatar", 30); assert(s.state == "ready", s.detail)
```

## typed/builtin//modules/api/engine/carried/carried/heldBytes {#typed-builtin-modules-api-engine-carried-carried-heldbytes}

```lua
carried.heldBytes() -> number
```

The bytes every carried mount holds in this engine's memory.

**Returns** `number` — Bytes.

```lua
print(carried.heldBytes())
```

## typed/builtin//modules/api/engine/carried/carried/list {#typed-builtin-modules-api-engine-carried-carried-list}

```lua
carried.list() -> { Status }
```

The status of every carried mount of this session.

**Returns** `{ Status }` — One status per mount.

```lua
for _, m in carried.list() do print(m.key, m.state) end
```

## typed/builtin//modules/api/engine/carried/carried/manifest {#typed-builtin-modules-api-engine-carried-carried-manifest}

```lua
carried.manifest(key: string) -> string?
```

The manifest of the ready mount at `key`: the JSON bytes the
content store served (`$schema` `zero/closure/v1`, `root`, and `entries`,
one per file and folder with its world `path`, `asset_guid`, `checksum`,
`size_bytes`, `kind` and `origin`, plus one `engine` entry per builtin it
was built against). Their sha-256 is the mount's `closureSha`. Nil until
the mount is ready.

**Parameters**

- `key` `string` — The mount's key.

**Returns** `string?` — The manifest's bytes, or nil.

```lua
local entries = require("@builtin::modules.json").decode(carried.manifest("ada.avatar")).entries
```

## typed/builtin//modules/api/engine/carried/carried/mount {#typed-builtin-modules-api-engine-carried-carried-mount}

```lua
carried.mount(closureSha: string, options: MountOptions?) -> Status
```

Hold the carried mount of the closure whose manifest address is
`closureSha` and start filling it, unless it is already held. The mount
stands at `/zero/runtime/carried/<key>/`; a key holds one closure for as
long as anyone uses it, and every `mount` of the same closure at the same
key holds it once more. Answers at once with the mount's status (`state`
`resolving` while it fills); `carried.wait` yields until it settles.
Raises when the key is malformed, `closureSha` is no sha-256, or the key
holds another closure.

**Parameters**

- `closureSha` `string` — The sha-256 hex digest of the closure's manifest.
- `options` `MountOptions` _(optional)_ — `key`: the mount's folder name (one path segment of letters,
digits, `.`, `_`, `-`), default `closure-<first 16 hex digits>`;
`commit`: the commit the closure was published at, stated in the status.

**Returns** `Status` — The mount's status.

```lua
local m = carried.mount(sha, { key = "ada.avatar" }); local s = carried.wait(m.key)
```

## typed/builtin//modules/api/engine/carried/carried/mountDraft {#typed-builtin-modules-api-engine-carried-carried-mountdraft}

```lua
carried.mountDraft(assetPath: string, options: MountOptions?) -> Status
```

Hold a draft carried mount of the asset at `assetPath`, an asset of
the open world's working tree (or of your home folder): the engine walks
the asset and every asset its files reference, writes that closure and
its manifest into the device's content cache, and mounts it from there
the way a published closure mounts, labelled `draft = true`. It is this
engine's alone. Mounting it again rebuilds it from the tree as it stands.
A draft holding a home folder's content is that folder's: it is made for
code that reaches the folder, and its files, listing, status and
manifest answer that code alone. Raises, naming the folder, when the
asset or anything it reaches is in a home folder the calling code does
not reach.

**Parameters**

- `assetPath` `string` — The asset, e.g. `/zero/source/chars/ada.avatar`.
- `options` `MountOptions` _(optional)_ — `key`: the mount's folder name, default `draft-<asset name>`.

**Returns** `Status` — The mount's status.

```lua
local d = carried.mountDraft("/zero/source/props/lamp.model"); carried.wait(d.key)
```

## typed/builtin//modules/api/engine/carried/carried/release {#typed-builtin-modules-api-engine-carried-carried-release}

```lua
carried.release(key: string) -> number
```

Let one holder of the mount at `key` go. The last one takes it
down: its folder leaves `/zero/runtime/carried/` and its bytes leave this
engine's memory, while the device's content cache keeps them for the
next mount. Raises when no mount is held at `key`.

**Parameters**

- `key` `string` — The mount's key.

**Returns** `number` — How many holders still hold it.

```lua
carried.release("ada.avatar")
```

## typed/builtin//modules/api/engine/carried/carried/resolve {#typed-builtin-modules-api-engine-carried-carried-resolve}

```lua
carried.resolve(key: string, reference: string) -> string?
```

What `reference`, written by content of the closure at `key`,
names: a guid the closure carries, a path of its world
(`props/lamp.model`, `/zero/source/props/lamp.model`) or an identity of
its world (`props.lamp`) answers the file inside the mount; a reference
to the engine library answers the library asset, taken to the version of
an engine builtin the closure was built against when the mount holds that
version. The open world's own content answers none of it. Nil when
nothing answers.

**Parameters**

- `key` `string` — The mount's key.
- `reference` `string` — A guid, path, identity or library reference.

**Returns** `string?` — A VFS path, or nil.

```lua
local tex = carried.resolve("ada.avatar", "chars.ada_albedo")
```

## typed/builtin//modules/api/engine/carried/carried/status {#typed-builtin-modules-api-engine-carried-carried-status}

```lua
carried.status(key: string) -> Status?
```

Where the mount at `key` stands, as `<key>/status` states it:
`state` is `resolving`, `fetching`, `measuring`, `ready`, `refused` or
`none`; `reason` is a word saying why nothing is mounted (`unreachable`,
`notFound`, `incomplete`) or why the closure was refused, with `detail`
the sentence; `bytesFetched` / `bytesTotal` count the files read;
`measured` counts files, folders and bytes per kind once ready;
`builtin` names how each engine builtin the closure was built against
resolves (`host`, `mount`, or `hostOtherVersion` with `why`). Nil when
no mount is held at `key`, and when the mount holds a home folder's
content the calling code does not reach.

**Parameters**

- `key` `string` — The mount's key.

**Returns** `Status?` — The status, or nil.

```lua
print(carried.status("ada.avatar").state)
```

## typed/builtin//modules/api/engine/carried/carried/wait {#typed-builtin-modules-api-engine-carried-carried-wait}

```lua
carried.wait(key: string, seconds: number?) -> Status
```

Yield until the mount at `key` settles (`ready`, `refused` or
`none`) or `seconds` pass, and answer its status then. Raises when no
mount is held at `key`, or when it holds a home folder's content the
calling code does not reach.

**Parameters**

- `key` `string` — The mount's key.
- `seconds` `number` _(optional)_ — How long to wait, default 120.

**Returns** `Status` — The status.

```lua
local s = carried.wait("ada.avatar", 30); assert(s.state == "ready", s.detail)
```