Skip to content

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

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

Merged
beran-t merged 1 commit into from
Aug 6, 2026
+17 −270
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
269 changes: 0 additions & 269 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 Expand Up @@ -3225,48 +2998,6 @@ components:
type: integer
description: Total disk space in bytes
format: int64
CollapseResult:
type: object
description: Per-call statistics from a heap collapse
properties:
regions:
type: integer
description: Anonymous read-write regions scanned
chunks:
type: integer
description: 2 MiB chunks attempted
collapsed:
type: integer
description: Chunks whose base pages were actually migrated into a new hugepage
(real work)
alreadyHuge:
type: integer
description: Chunks MADV_COLLAPSE accepted but were already hugepages (no
work)
skipped:
type: integer
description: Chunks that could not be collapsed (empty or ineligible)
elapsedMs:
type: integer
format: int64
description: Wall-clock time spent collapsing, in milliseconds
ComposeRequest:
type: object
required:
- source_paths
- destination
properties:
source_paths:
type: array
items:
type: string
description: Ordered list of source file paths to concatenate
destination:
type: string
description: Destination file path for the composed file
username:
type: string
description: User for setting ownership and resolving relative paths
connect-protocol-version:
type: number
title: Connect-Protocol-Version
Expand Down
18 changes: 17 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,23 @@ 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 that leak in from the upstream spec. The SDKs
# never call these - they are envd/orchestrator internals for the pause and
# resume path (cgroup + filesystem freeze/thaw, heap collapse, zero-copy file
# compose). They must not appear in the developer-facing docs, and their
# multi-sentence summaries also blow past the macOS 255-byte filename limit
# Mintlify derives from `summary` (e.g. /fsfreeze), which aborts the whole
# API-reference build. Exclude them here so a re-add upstream cannot re-leak
# them into openapi-public.yml.
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