Skip to content

docs: exclude internal-only envd endpoints (fixes mintlify dev ENAMETOOLONG) #331

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
beran-t wants to merge 2 commits into from
Closed

docs: exclude internal-only envd endpoints (fixes mintlify dev ENAMETOOLONG) #331

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8a30206
docs: exclude internal-only envd endpoints from public API reference
beran-t Aug 5, 2026
dd16c9f
chore(ci): trigger Mintlify preview redeploy
beran-t Aug 6, 2026
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
227 changes: 0 additions & 227 deletions openapi-public.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1467,183 +1467,6 @@ paths:
- Envd
servers:
- *id004
/freeze:
post:
summary: Freeze user/pty cgroups before pause. Written directly by envd to avoid
Process.Start / shell overhead under load.
security:
- *id005
responses:
'204':
description: Cgroups frozen
'500':
$ref: '#/components/responses/InternalServerError'
'503':
description: Freeze lock is held by another operation
'502': *id003
parameters:
- name: E2b-Sandbox-Id
in: header
required: true
description: Identifier of the target sandbox. Routes the request to that
sandbox's envd over the shared sandbox host.
schema:
type: string
- name: E2b-Sandbox-Port
in: header
required: true
description: Port envd listens on inside the sandbox (default 49983).
schema:
type: integer
default: 49983
operationId: postFreeze
tags:
- Envd
servers:
- *id004
/unfreeze:
post:
summary: Unfreeze user/pty cgroups. Intended ONLY for the orchestrator's pause-failure
rollback path; the normal resume thaw happens via /init's deferred unfreeze,
not here.
security:
- *id005
responses:
'204':
description: Cgroups unfrozen
'500':
$ref: '#/components/responses/InternalServerError'
'503':
description: Freeze lock is held by another operation
'502': *id003
parameters:
- name: E2b-Sandbox-Id
in: header
required: true
description: Identifier of the target sandbox. Routes the request to that
sandbox's envd over the shared sandbox host.
schema:
type: string
- name: E2b-Sandbox-Port
in: header
required: true
description: Port envd listens on inside the sandbox (default 49983).
schema:
type: integer
default: 49983
operationId: postUnfreeze
tags:
- Envd
servers:
- *id004
/collapse:
post:
summary: Collapse envd's own anonymous heap into 2 MiB transparent hugepages
before pause, so on resume envd touches fewer distinct guest-physical frames
(each a cold fault). Best-effort.
security:
- *id005
responses:
'200':
description: Heap collapsed
content:
application/json:
schema:
$ref: '#/components/schemas/CollapseResult'
'500':
$ref: '#/components/responses/InternalServerError'
'502': *id003
parameters:
- name: E2b-Sandbox-Id
in: header
required: true
description: Identifier of the target sandbox. Routes the request to that
sandbox's envd over the shared sandbox host.
schema:
type: string
- name: E2b-Sandbox-Port
in: header
required: true
description: Port envd listens on inside the sandbox (default 49983).
schema:
type: integer
default: 49983
operationId: postCollapse
tags:
- Envd
servers:
- *id004
/fsfreeze:
post:
summary: Freeze the guest rootfs (FIFREEZE) before a filesystem-only pause so
it is flushed to a consistent on-disk state, closing the sync->pause race.
Idempotent. On a successful filesystem-only pause the VM is rebooted, so no
thaw is needed; the orchestrator thaws only on the pause-failure path.
security:
- *id005
responses:
'204':
description: Rootfs frozen
'500':
$ref: '#/components/responses/InternalServerError'
'503':
description: Freeze lock is held by another operation
'502': *id003
parameters:
- name: E2b-Sandbox-Id
in: header
required: true
description: Identifier of the target sandbox. Routes the request to that
sandbox's envd over the shared sandbox host.
schema:
type: string
- name: E2b-Sandbox-Port
in: header
required: true
description: Port envd listens on inside the sandbox (default 49983).
schema:
type: integer
default: 49983
operationId: postFsfreeze
tags:
- Envd
servers:
- *id004
/fsthaw:
post:
summary: Thaw the guest rootfs (FITHAW). Intended ONLY for the orchestrator's
pause-failure rollback path, so a frozen filesystem cannot leave the live
VM deadlocked. Idempotent.
security:
- *id005
responses:
'204':
description: Rootfs thawed
'500':
$ref: '#/components/responses/InternalServerError'
'503':
description: Freeze lock is held by another operation
'502': *id003
parameters:
- name: E2b-Sandbox-Id
in: header
required: true
description: Identifier of the target sandbox. Routes the request to that
sandbox's envd over the shared sandbox host.
schema:
type: string
- name: E2b-Sandbox-Port
in: header
required: true
description: Port envd listens on inside the sandbox (default 49983).
schema:
type: integer
default: 49983
operationId: postFsthaw
tags:
- Envd
servers:
- *id004
/envs:
get:
summary: Environment variables
Expand Down Expand Up @@ -1882,56 +1705,6 @@ paths:
operationId: uploadFile
servers:
- *id004
/files/compose:
post:
summary: Compose multiple files into a single file using zero-copy concatenation.
Source files are deleted after successful composition.
tags:
- Filesystem
security:
- *id005
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ComposeRequest'
responses:
'200':
description: Files composed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/EntryInfo'
'400':
$ref: '#/components/responses/InvalidPath'
'401':
$ref: '#/components/responses/InvalidUser'
'404':
$ref: '#/components/responses/FileNotFound'
'500':
$ref: '#/components/responses/InternalServerError'
'507':
$ref: '#/components/responses/NotEnoughDiskSpace'
'502': *id003
parameters:
- name: E2b-Sandbox-Id
in: header
required: true
description: Identifier of the target sandbox. Routes the request to that
sandbox's envd over the shared sandbox host.
schema:
type: string
- name: E2b-Sandbox-Port
in: header
required: true
description: Port envd listens on inside the sandbox (default 49983).
schema:
type: integer
default: 49983
operationId: postFilesCompose
servers:
- *id004
/filesystem.Filesystem/CreateWatcher:
post:
tags:
Expand Down
17 changes: 16 additions & 1 deletion scripts/generate_openapi_reference.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1389,7 +1389,22 @@ def filter_paths(spec: dict[str, Any]) -> None:
"""
# Remove explicitly excluded paths
excluded_prefixes = ("/access-tokens", "/api-keys")
excluded_exact = {"/init"}
# Internal-only envd endpoints. These are orchestrator/internal operations the
# SDKs never call, so they must not appear in the public docs. They are excluded
# by path here because they do not use an admin/internal auth scheme (so the
# admin-only filter below does not catch them), and the curated upstream envd
# spec has at times still carried them. Their "summaries" are multi-sentence
# engineering notes, which also make Mintlify generate filenames that exceed the
# OS limit (ENAMETOOLONG) and break `mintlify dev`.
excluded_exact = {
"/init",
"/freeze",
"/unfreeze",
"/collapse",
"/fsfreeze",
"/fsthaw",
"/files/compose",
}
to_remove = [
p for p in spec["paths"]
if p.startswith(excluded_prefixes) or p in excluded_exact
Expand Down