TypeScript API reference¶

Generated from eve-iac OpenAPI/semantics. Do not edit manually.

Public methods on EveIacClient from createEveIacClient. Types are exported from @eve-iac/sdk.

How-to is the workflow guide. This page is the operation reference.

EVE IaC model¶

YAML is IaC intent: what you want the lab to be. The EVE UNL is the persisted native lab definition. Live observation is what EVE is doing right now, and it can differ from both. planProject asks what would have to change. reconcileProject with to_eve makes EVE match IaC intent. reconcileProject with from_eve turns the current UNL definition into new IaC intent. getProjectStatus is the lightweight live poll. inspectProject is the rich structural observation.

• IaC intent. The YAML project, and the public JSON of that YAML. It describes what you want the lab to be. It is not a live observation.
• EVE UNL definition. EVE's persisted lab file. It is not the same thing as transient runtime state.
• Live observation. What is happening in EVE right now: node run state, runtime link quality, and other operational facts that can differ from the UNL.
• Structural observation. The rich inspect snapshot: nodes, interfaces, networks, links, and presentation, with runtime metadata attached. It is not the lightweight poll.
• to_eve. Make EVE match IaC intent.
• from_eve. Turn the current EVE UNL definition into new IaC intent. It is not a capture of transient runtime state, and it is not importProject.

Omission rules:

• undefined is omitted from JSON
• null remains explicit null where the schema allows it
• false, 0, and "" remain explicit values

timeoutMs overrides the operation timeout. Omit it to use the semantics default.

Connection / Authentication¶

getHealth¶

Family: Session

Purpose¶

Tells you whether this eve-iac-agent process is reachable and which build is running. No project and no token are required.

Mental model¶

Is the agent up?

Use when¶

• checking connectivity before login
• reading the agent version

Do not use when¶

• you need lab or node state

Reads¶

• the agent process

Changes¶

Nothing. Read-only.

Signature¶

getHealth(timeoutMs?: number): Promise<HealthData>

• HTTP: GET /api/v1/health
• operationId: getHealth
• Authentication: none
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
timeoutMs	number	no	Override the 15000 ms default.

Returns¶

HealthData

Field	TypeScript type	Required	Semantics
status	string	no
tls	boolean	no
version	string	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "status": "ok",
  "tls": true,
  "version": "0.9.0-1"
}

Processing the result¶

Typical field access after a successful call:

const health = await client.getHealth();
if (health.status !== "ok") process.exit(1);

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const health = await client.getHealth();
console.log(health.status);

login¶

Family: Session

Purpose¶

Opens an agent session and returns the bearer token later calls send.

Mental model¶

Sign me in.

Use when¶

• starting a client session

Do not use when¶

• you already have a token; use getSession to check it

Reads¶

• the username and password you send

Changes¶

Creates an agent session.

Related¶

• getSession
• logout

Signature¶

login(body: LoginRequest, timeoutMs?: number): Promise<LoginData>

• HTTP: POST /api/v1/login
• operationId: login
• Authentication: none
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	LoginRequest	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: LoginRequest¶

This request type is the same wire shape as LoginRequest.

Field	TypeScript type	Required	Semantics
username	string	yes
password	string	yes

Returns¶

LoginData

Field	TypeScript type	Required	Semantics
token	string	no
username	string	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Human login omits token. --json includes token — store as EVE_IAC_TOKEN, never log stdout in CI.

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "admin"
}

Processing the result¶

Typical field access after a successful call:

const session = await client.login({ username: "admin", password: "secret" });
const token = session.token ?? "";

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
invalid_credentials	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport

Example¶

const session = await client.login({ username: "admin", password: "secret" });
const authed = createEveIacClient({ url, token: session.token ?? "", caPem });

logout¶

Family: Session

Purpose¶

Ends the agent session that belongs to the current bearer token.

Mental model¶

Sign me out.

Use when¶

• discarding a token you no longer want to use

Reads¶

• the current session

Changes¶

Deletes that agent session.

Related¶

• login

Signature¶

logout(body: LogoutRequest = {}, timeoutMs?: number): Promise<StatusOkData>

• HTTP: POST /api/v1/logout
• operationId: logout
• Authentication: Bearer token required
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	LogoutRequest	no	Optional; empty object is sent when omitted.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: LogoutRequest¶

This request type is the same wire shape as LogoutRequest.

No object fields (see type).

Returns¶

StatusOkData

Field	TypeScript type	Required	Semantics
status	string	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

await client.logout();

getSession¶

Family: Session

Purpose¶

Checks that the bearer token is still a live agent session.

Mental model¶

Am I still signed in?

Use when¶

• probing a stored token before other calls

Do not use when¶

• you need lab state

Reads¶

• the current agent session

Changes¶

Nothing. Read-only.

Related¶

• login
• logout

Signature¶

getSession(timeoutMs?: number): Promise<SessionData>

• HTTP: GET /api/v1/session
• operationId: getSession
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	number	no	Override the 15000 ms default.

Returns¶

SessionData

Field	TypeScript type	Required	Semantics
username	string	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "username": "admin"
}

Processing the result¶

Typical field access after a successful call:

const session = await client.getSession();
console.log(session.username);

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const session = await client.getSession();

getCapabilities¶

Family: Session

Purpose¶

Reports what this agent build can do for each project mode.

Mental model¶

What can this agent do?

Use when¶

• deciding which project operations the connected agent supports

Reads¶

• agent capability flags

Changes¶

Nothing. Read-only.

How-to¶

• Start, stop, and wipe lab nodes

Signature¶

getCapabilities(timeoutMs?: number): Promise<CapabilitiesData>

• HTTP: GET /api/v1/capabilities
• operationId: getCapabilities
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	number	no	Override the 15000 ms default.

Returns¶

CapabilitiesData

Field	TypeScript type	Required	Semantics
eveReachable	boolean	no
eveBaseUrl	string	no
features	Record	no
projectModes	RecordProjectModeCaps>	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "eveReachable": true,
  "eveBaseUrl": "https://127.0.0.1",
  "features": {
    "import": true,
    "inspect": true
  },
  "projectModes": {
    "create": {
      "topology_mutation": true,
      "reconcile": true
    },
    "load": {
      "topology_mutation": false,
      "lifecycle": {
        "start": true,
        "stop": true,
        "wipe": true
      }
    }
  }
}

Processing the result¶

Typical field access after a successful call:

const caps = await client.getCapabilities();

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const caps = await client.getCapabilities();

Templates / Metadata¶

getPublicSchema¶

Family: Metadata

Purpose¶

Returns selected fragments of the public IaC JSON Schema so an editor can validate YAML intent.

Mental model¶

What shape is IaC intent allowed to have?

Use when¶

• loading schema fragments for an editor

Do not use when¶

• you need a lab, a template list, or live EVE state

Reads¶

• the embedded public schema

Changes¶

Nothing. Read-only.

Important semantics¶

• Lazy public JSON Schema fragments from the canonical eve-iac-v1 embed. sections required minItems 1. Unknown or empty sections: 400 invalid_request, no partial map. Response sections preserves request order. revision is lowercase SHA-256 of exact embed bytes. Not lab YAML, not live template/network/interface capabilities. No all=true.

Signature¶

getPublicSchema(body: SchemaRequest, timeoutMs?: number): Promise<SchemaData>

• HTTP: POST /api/v1/schema
• operationId: getPublicSchema
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	SchemaRequest	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: SchemaRequest¶

This request type is the same wire shape as SchemaRequest.

Field	TypeScript type	Required	Semantics
sections	Array<"nodes"	"networks"	"links"

Returns¶

SchemaData

Field	TypeScript type	Required	Semantics
revision	string	yes	Lowercase hex SHA-256 of the exact embedded canonical schema bytes. Same value for every fragment in the response.
sections	Record	yes	Map keyed by requested section name, preserving request order. Values are JSON Schema documents, not a compact DTO.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "revision": "f7f8d72c113b156e85907c716d4cfcc934179ecde0a0101f6937d7b0376b2399",
  "sections": {
    "traffic_filters": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/trafficFilter"
      }
    }
  }
}

Processing the result¶

Typical field access after a successful call:

const schema = await client.getPublicSchema({ sections: ["traffic_filters", "tasks"] });
const rev = schema.revision ?? "";

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.getPublicSchema({ lab, manifest, yaml, files });

listTemplates¶

Family: Metadata

Purpose¶

Lists the node templates this EVE can place in a lab.

Mental model¶

Which node templates exist?

Use when¶

• building a template picker

Do not use when¶

• you need one template's images or attributes; use getTemplate, listTemplateImages, or listTemplateAttributes

Reads¶

• the EVE template catalog

Changes¶

Nothing. Read-only.

Related¶

• getTemplate
• getTemplateCatalog

Signature¶

listTemplates(query?: ListTemplatesQuery, timeoutMs?: number): Promise<TemplatesData>

• HTTP: GET /api/v1/templates
• operationId: listTemplates
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
query	ListTemplatesQuery (ListTemplatesQuery)	no	Query object. Omit the argument to send no query string.
timeoutMs	number	no	Override the 15000 ms default.

Query schema: ListTemplatesQuery¶

Field	TypeScript type	Required	Semantics
provisioned	string	no	Only the string true filters to provisioned templates. Omitted means all.

Returns¶

TemplatesData

Field	TypeScript type	Required	Semantics
templates	Array<Template>	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "templates": [
    {
      "id": "iol",
      "description": "IOL",
      "type": "qemu",
      "provisioned": true,
      "configSupported": true
    },
    {
      "id": "vpcs",
      "description": "VPCS",
      "type": "vpcs",
      "provisioned": true,
      "configSupported": true
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

const { templates } = await client.listTemplates();
const ids = (templates ?? []).map((t) => t.id).filter(Boolean);

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const all = await client.listTemplates();
const provisioned = await client.listTemplates({ provisioned: "true" });

getTemplateCatalog¶

Family: Presentation

Purpose¶

Maps each template name to its description and device family so a canvas can choose an icon. This is presentation metadata, not IaC intent and not a node.

Mental model¶

How should this template be drawn?

Use when¶

• choosing a device graphic

Do not use when¶

• you are writing topology YAML

Reads¶

• the presentation catalog

Changes¶

Nothing. Read-only.

Important semantics¶

• Presentation only. Not desired state. An unknown or empty device_family is normalized to other by the agent. The response is not a Project or a Node and must not be written back as topology.

Related¶

• listTemplates
• listIcons

Signature¶

getTemplateCatalog(timeoutMs?: number): Promise<TemplateCatalogData>

• HTTP: GET /api/v1/templates/catalog
• operationId: getTemplateCatalog
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	number	no	Override the 15000 ms default.

Returns¶

TemplateCatalogData

Field	TypeScript type	Required	Semantics
templates	RecordTemplateFamily>	yes

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.getTemplateCatalog();

getTemplate¶

Family: Metadata

Purpose¶

Returns one template's authoring detail, including the canonical template id.

Mental model¶

What is this template?

Use when¶

• inspecting one template before placing a node

Reads¶

• that EVE template

Changes¶

Nothing. Read-only.

Important semantics¶

• SUCCESS data.id is the canonical template. Unknown id: 404 unknown_template. Never success with an empty body for a missing template.

Related¶

• listTemplates
• listTemplateImages
• listTemplateAttributes

Signature¶

getTemplate(id: string, timeoutMs?: number): Promise<TemplateDetail>

• HTTP: GET /api/v1/templates/{id}
• operationId: getTemplate
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
id	string	yes	Path parameter
timeoutMs	number	no	Override the 15000 ms default.

Returns¶

TemplateDetail

Field	TypeScript type	Required	Semantics
id	string	no
description	string	no
type	string	no
provisioned	boolean	no
configSupported	boolean	no
icon	string	no
images	Array<TemplateImage>	no
default	string	no
image_requirement	"required"	"optional"	"not_applicable"
attributes	Array<TemplateAttribute>	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "id": "iol",
  "description": "IOL",
  "type": "qemu",
  "provisioned": true,
  "configSupported": true,
  "default": "iol-2024",
  "images": [
    {
      "id": "iol-2024",
      "available": true
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

const detail = await client.getTemplate("iol");

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
unknown_template	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const data = await client.getTemplate("iol");

listTemplateImages¶

Family: Metadata

Purpose¶

Lists the images available for one template.

Mental model¶

Which images can this template boot?

Use when¶

• offering an image choice for a node

Reads¶

• images for that template

Changes¶

Nothing. Read-only.

Important semantics¶

• SUCCESS data.template is the canonical template. Unknown id: 404 unknown_template. Never success with an empty body for a missing template.

Related¶

• getTemplate

Signature¶

listTemplateImages(id: string, timeoutMs?: number): Promise<TemplateImagesData>

• HTTP: GET /api/v1/templates/{id}/images
• operationId: listTemplateImages
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
id	string	yes	Path parameter
timeoutMs	number	no	Override the 15000 ms default.

Returns¶

TemplateImagesData

Field	TypeScript type	Required	Semantics
template	string	no
type	string	no
provisioned	boolean	no
default	string	no
images	Array<TemplateImage>	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
unknown_template	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const data = await client.listTemplateImages("iol");

listTemplateAttributes¶

Family: Metadata

Purpose¶

Lists the authoring attributes for one template.

Mental model¶

Which settings does this template expose?

Use when¶

• building a node form

Reads¶

• attributes for that template

Changes¶

Nothing. Read-only.

Important semantics¶

• SUCCESS data.template is the canonical template. Unknown id: 404 unknown_template. Never success with an empty body for a missing template.

Related¶

• getTemplate

Signature¶

listTemplateAttributes(id: string, timeoutMs?: number): Promise<TemplateAttributesData>

• HTTP: GET /api/v1/templates/{id}/attributes
• operationId: listTemplateAttributes
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
id	string	yes	Path parameter
timeoutMs	number	no	Override the 15000 ms default.

Returns¶

TemplateAttributesData

Field	TypeScript type	Required	Semantics
template	string	no
type	string	no
attributes	Array<TemplateAttribute>	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
unknown_template	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const data = await client.listTemplateAttributes("iol");

listNetworkTypes¶

Family: Metadata

Purpose¶

Lists the network types EVE can place in a lab.

Mental model¶

Which network types exist?

Use when¶

• building a network picker

Reads¶

• the EVE network-type catalog

Changes¶

Nothing. Read-only.

Related¶

• getNetworkAuthoring

Signature¶

listNetworkTypes(timeoutMs?: number): Promise<NetworkTypesData>

• HTTP: GET /api/v1/network-types
• operationId: listNetworkTypes
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	number	no	Override the 15000 ms default.

Returns¶

NetworkTypesData

Field	TypeScript type	Required	Semantics
types	Array<NetworkType>	no
natOnly	boolean	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.listNetworkTypes();

getNetworkAuthoring¶

Family: Metadata

Purpose¶

Returns the authoring detail for one network type.

Mental model¶

How do I author this network?

Use when¶

• building a form for one network type

Reads¶

• that network type

Changes¶

Nothing. Read-only.

Important semantics¶

• SUCCESS data.id is the canonical network type. Unknown id: 404 unknown_network_type.

Related¶

• listNetworkTypes

Signature¶

getNetworkAuthoring(id: string, timeoutMs?: number): Promise<NetworkAuthoring>

• HTTP: GET /api/v1/authoring/networks/{id}
• operationId: getNetworkAuthoring
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
id	string	yes	Path parameter
timeoutMs	number	no	Override the 15000 ms default.

Returns¶

NetworkAuthoring

Field	TypeScript type	Required	Semantics
id	string	no
label	string	no
icon	string	no
supported	boolean	no
attributes	Array<TemplateAttribute>	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "id": "bridge",
  "label": "bridge",
  "supported": true,
  "attributes": [
    {
      "name": "smart",
      "label": "Smart Bridge",
      "kind": "integer",
      "group": "manage",
      "values": [
        "0",
        "1"
      ]
    },
    {
      "name": "pnet_out",
      "label": "Uplink",
      "kind": "enum",
      "group": "manage",
      "values": [
        "",
        "pnet0",
        "nat0"
      ]
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

const data = await client.getNetworkAuthoring("bridge");

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
unknown_network_type	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const data = await client.getNetworkAuthoring("bridge");

listIcons¶

Family: Presentation

Purpose¶

Lists the node and network icon names the canvas can draw.

Mental model¶

Which icons exist?

Use when¶

• resolving an icon name

Do not use when¶

• you need the icon bytes; use getAuthoringIconsZip

Reads¶

• the icon index

Changes¶

Nothing. Read-only.

Related¶

• getAuthoringIconsZip
• getTemplateCatalog

Signature¶

listIcons(timeoutMs?: number): Promise<IconsData>

• HTTP: GET /api/v1/icons
• operationId: listIcons
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	number	no	Override the 15000 ms default.

Returns¶

IconsData

Field	TypeScript type	Required	Semantics
icons	Array<Icon>	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.listIcons();

listFolders¶

Family: Metadata

Purpose¶

Lists EVE lab folders under a path so a user can pick where a lab lives.

Mental model¶

Which lab folders are here?

Use when¶

• browsing the EVE lab tree

Do not use when¶

• the path is a .unl lab file

Reads¶

• EVE lab folders

Changes¶

Nothing. Read-only.

Signature¶

listFolders(query?: ListFoldersQuery, timeoutMs?: number): Promise<FoldersData>

• HTTP: GET /api/v1/folders
• operationId: listFolders
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
query	ListFoldersQuery (ListFoldersQuery)	no	Query object. Omit the argument to send no query string.
timeoutMs	number	no	Override the 15000 ms default.

Query schema: ListFoldersQuery¶

Field	TypeScript type	Required	Semantics
path	string	no	EVE folder path. Omitted or empty means labs root /. Not a .unl lab path.

Returns¶

FoldersData

Field	TypeScript type	Required	Semantics
path	string	no
parent	string	no	Parent folder path. Empty at labs root.
folders	Array<FolderEntry>	no
labs	Array<FolderEntry>	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "path": "/Customers",
  "parent": "/",
  "folders": [
    {
      "name": "ACME",
      "path": "/Customers/ACME",
      "lock": false
    }
  ],
  "labs": [
    {
      "name": "OSPF.unl",
      "path": "/Customers/OSPF.unl",
      "lock": false
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

const root = await client.listFolders();
const nested = await client.listFolders({ path: "/Customers" });

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const root = await client.listFolders();
const nested = await client.listFolders({ path: "/Customers" });

getAuthoringIconsZip¶

Family: Presentation

Purpose¶

Downloads one zip of the node and network icon files for the canvas.

Mental model¶

Give me the icon files.

Use when¶

• caching icon bytes for a canvas

Reads¶

• the process-memoized icon archive

Changes¶

Nothing. Read-only.

Performance¶

Built once per agent process. A later call returns that archive.

Important semantics¶

• Raw application/zip of node/ and network/. Not a JSON envelope. Built once per agent process, together with the authoring snapshot. A file EVE cannot serve is omitted. timeoutMs 0 waits until that pull finishes.

Related¶

• listIcons
• getAuthoringRevision

Signature¶

getAuthoringIconsZip(timeoutMs?: number): Promise<Buffer>

• HTTP: GET /api/v1/authoring/icons.zip
• operationId: getAuthoringIconsZip
• Authentication: Bearer token required
• Default timeout: 0 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	number	no	Override the 0 ms default.

Returns¶

Unnamed JSON object.

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.getAuthoringIconsZip();

getAuthoringRevision¶

Family: Metadata

Purpose¶

Returns the hash of the authoring catalog this agent process has memoized, so a client can skip a full snapshot.

Mental model¶

Has the authoring catalog changed?

Use when¶

• deciding whether to reload templates, networks, and icons

Reads¶

• the process-memoized authoring snapshot

Changes¶

Nothing. Read-only.

Important semantics¶

• Lowercase SHA-256 of the process-memoized authoring snapshot. iconsRevision is the SHA-256 of the icon zip and is present on success, because the snapshot and the zip are stored together. timeoutMs 0 waits until that pull finishes. Not the health version and not POST /api/v1/schema revision. A new EVE image is invisible until the agent process restarts.

Related¶

• getAuthoringSnapshot

Signature¶

getAuthoringRevision(timeoutMs?: number): Promise<AuthoringRevisionData>

• HTTP: GET /api/v1/authoring/revision
• operationId: getAuthoringRevision
• Authentication: Bearer token required
• Default timeout: 0 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	number	no	Override the 0 ms default.

Returns¶

AuthoringRevisionData

Field	TypeScript type	Required	Semantics
revision	string	yes
iconsRevision	string	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.getAuthoringRevision();

getAuthoringSnapshot¶

Family: Metadata

Purpose¶

Returns the static authoring catalog for this agent process: templates, families, network authoring, and icon indexes. Icon bytes are not included.

Mental model¶

Give me the authoring catalog.

Use when¶

• loading the canvas catalog once per agent process

Reads¶

• the process-memoized authoring snapshot

Changes¶

Nothing. Read-only.

Performance¶

Memoized for the agent process. A new EVE image is invisible until the agent restarts.

Important semantics¶

• Static templates, family catalog, network authoring, and icon indexes for one agent process. Icon bytes are omitted. timeoutMs 0 waits until the catalog pull finishes. Further revision calls return the same memo.

Related¶

• getAuthoringRevision
• getAuthoringIconsZip

Signature¶

getAuthoringSnapshot(timeoutMs?: number): Promise<AuthoringSnapshotData>

• HTTP: GET /api/v1/authoring/snapshot
• operationId: getAuthoringSnapshot
• Authentication: Bearer token required
• Default timeout: 0 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	number	no	Override the 0 ms default.

Returns¶

AuthoringSnapshotData

Field	TypeScript type	Required	Semantics
revision	string	yes
templates	Array<TemplateDetail>	yes
catalog	TemplateCatalogData	yes
networkTypes	NetworkTypesData	yes
networks	Array<NetworkAuthoring>	yes
icons	Array<Icon>	yes
netIcons	Array<Icon>	yes
cluster	Array<ClusterMember>	no	GET /api/cluster members loaded with the authoring snapshot. id is the sat key stored in topology.yml. name is the label shown in the node form. -1 any and 0 local are added by the form when absent.

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.getAuthoringSnapshot();

completeLinkInterfaces¶

Family: Metadata

Purpose¶

Lists the interfaces of a node that already exists in IaC intent, including which ones are already used.

Mental model¶

Which interfaces can I connect on this node?

Use when¶

• completing a link endpoint while editing intent

Do not use when¶

• the node is not in the project yet; use previewInterfaces for a template

Reads¶

• the packed project and the template interface map

Changes¶

Nothing. Read-only.

Important semantics¶

• SUCCESS is InterfacesData: source=node, canonical template, IaC node key, items[{name,type,used}]. Unknown node: 400 unknown_node. Unknown template: 404 unknown_template.

Related¶

• previewInterfaces

Signature¶

completeLinkInterfaces(body: AuthoringPayload, timeoutMs?: number): Promise<InterfacesData>

• HTTP: POST /api/v1/authoring/link-completions
• operationId: completeLinkInterfaces
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	AuthoringPayload	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: AuthoringPayload¶

This request type is the same wire shape as AuthoringPayload.

Field	TypeScript type	Required	Semantics
dir	string	no	Rejected when non-empty.
yaml	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
template	string	no
attributes	Record	no
excludeUsed	boolean	no
eth_format	string	no

Returns¶

InterfacesData

Field	TypeScript type	Required	Semantics
source	"template"	"node"	no
template	string	no	Canonical resolved template id.
node	string	no	IaC node key when source=node. omitted: all nodes. empty string: all nodes. named: that IaC node key
items	Array<Iface>	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "source": "node",
  "node": "core_r1",
  "template": "iol",
  "items": [
    {
      "name": "e0/0",
      "type": "ethernet",
      "used": true
    },
    {
      "name": "s0/0",
      "type": "serial",
      "used": false
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

const data = await client.completeLinkInterfaces({ yaml, node: "core_r1" });

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
unknown_node	Contractual/known for this call or its transport
unknown_template	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const data = await client.completeLinkInterfaces({ template: "iol" });

previewInterfaces¶

Family: Metadata

Purpose¶

Lists the interface names a template would have, before a node exists in the project.

Mental model¶

Which interfaces would this template have?

Use when¶

• previewing interfaces for a template

Do not use when¶

• the node already exists in intent; use completeLinkInterfaces

Reads¶

• the template interface map

Changes¶

Nothing. Read-only.

Important semantics¶

• SUCCESS is InterfacesData: source=template, canonical template, items[{name,type}] without used. Unknown template: 404 unknown_template.

Related¶

• completeLinkInterfaces

Signature¶

previewInterfaces(body: AuthoringPayload, timeoutMs?: number): Promise<InterfacesData>

• HTTP: POST /api/v1/authoring/interfaces
• operationId: previewInterfaces
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	AuthoringPayload	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: AuthoringPayload¶

This request type is the same wire shape as AuthoringPayload.

Field	TypeScript type	Required	Semantics
dir	string	no	Rejected when non-empty.
yaml	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
template	string	no
attributes	Record	no
excludeUsed	boolean	no
eth_format	string	no

Returns¶

InterfacesData

Field	TypeScript type	Required	Semantics
source	"template"	"node"	no
template	string	no	Canonical resolved template id.
node	string	no	IaC node key when source=node. omitted: all nodes. empty string: all nodes. named: that IaC node key
items	Array<Iface>	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "source": "template",
  "template": "ceos",
  "items": [
    {
      "name": "Ethernet1",
      "type": "ethernet"
    },
    {
      "name": "Ethernet2",
      "type": "ethernet"
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

const data = await client.previewInterfaces({ template: "ceos" });

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
unknown_template	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const data = await client.previewInterfaces({ template: "iol" });

Projects¶

validateProject¶

Family: Intent

Purpose¶

Checks the packed IaC intent and returns every public-path error. A failed check is still HTTP 200 with valid set to false.

Mental model¶

Is my IaC intent valid?

Use when¶

• checking topology YAML before plan or reconcile

Do not use when¶

• you want to compare intent with EVE; use planProject
• you want to change EVE

Reads¶

• the packed IaC intent

Changes¶

Nothing. Read-only.

Important semantics¶

• HTTP 200 data is {valid, errors[]}. valid=false is not an HTTP error. Errors use dotted public paths and stable codes. Global validation of the complete topology.

Related¶

• planProject
• editProject

Signature¶

validateProject(body: ProjectPayload, timeoutMs?: number): Promise<ValidateData>

• HTTP: POST /api/v1/projects/validate
• operationId: validateProject
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ValidateData

Field	TypeScript type	Required	Semantics
valid	boolean	yes
errors	Array<ValidationError>	yes

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "valid": true,
  "errors": []
}

Processing the result¶

Typical field access after a successful call:

const result = await client.validateProject(packed);
if (!result.valid) throw new Error("validate failed");

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.validateProject({ lab, manifest, yaml, files });

importProject¶

Family: Lifecycle

Purpose¶

Imports an existing EVE lab into IaC intent. The source lab is left unchanged. No managed lab is created; deploy is a separate step. This is not from_eve.

Mental model¶

Import this EVE lab as IaC intent. Do not deploy.

Use when¶

• adopting an existing EVE lab path as a new IaC project

Do not use when¶

• you want the current UNL definition to replace YAML intent of an existing project; use reconcileProject with from_eve
• you want to create the managed lab; use deployProject

Reads¶

• the source EVE lab

Changes¶

Returns IaC intent for the client to write. Does not modify source_lab and does not create a managed lab.

Important semantics¶

• Reads source_lab and returns IaC intent. Does not deploy, clone, or otherwise mutate EVE. Does not mutate source_lab. from_eve is not this operation. managed_lab is the later deploy target, not a lab that was created.

Related¶

• reconcileProject
• deployProject

Signature¶

importProject(body: ProjectPayload & {
  lab: string;
}, timeoutMs?: number): Promise<ImportData>

• HTTP: POST /api/v1/projects/import
• operationId: importProject
• Authentication: Bearer token required
• Default timeout: 300000 ms

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload & { lab: string; }	yes	Request body.
timeoutMs	number	no	Override the 300000 ms default.

Request schema¶

lab is required. Import reads source_lab into IaC intent. It does not deploy and it does not mutate source_lab. managed_lab is the later deploy target. It is not from_eve reconcile.

Field	TypeScript type	Required	Semantics
lab	string	yes
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ImportData

Field	TypeScript type	Required	Semantics
name	string	no
yaml	string	no
files	Record	no
mode	string	no
source_lab	string	no
managed_lab	string	no
lab	string	no
state	unknown	no
source	unknown	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Response includes yaml/files on first import. Never mutate source_lab.

{
  "mode": "import",
  "source_lab": "/Customers/OSPF.unl",
  "managed_lab": "/IaC/OSPF.unl",
  "lab": "/IaC/OSPF.unl",
  "name": "OSPF",
  "state": {
    "node_ids": {
      "n_1": 3,
      "n_2": 4
    }
  }
}

Processing the result¶

Typical field access after a successful call:

const imported = await client.importProject(packed);
const managed = imported.managed_lab ?? imported.lab;

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
lab_locked	Contractual/known for this call or its transport
lab_locked_mid_apply	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const imported = await client.importProject({
  lab: "/IaC/example.unl",
  manifest,
  yaml,
  files,
});
// Import writes IaC intent. It does not deploy. It is not reconcile from_eve.

planProject¶

Family: Planning

Purpose¶

Compares IaC intent with the EVE lab and returns the work that would be required. It never writes the project files and it never changes EVE.

Mental model¶

What would have to change?

Use when¶

• previewing a to_eve or from_eve change
• collecting the plan identity a later confirm must send

Do not use when¶

• you want the change applied; use reconcileProject
• you only need live node state; use getProjectStatus

Reads¶

• IaC intent and the current EVE lab

Changes¶

Nothing. Read-only.

Performance¶

A dry run. Heavier than getProjectStatus because it compares intent with the lab.

Important semantics¶

• Omitted direction is to_eve.
• The plan identity is direction-scoped. Do not reuse a to_eve identity for from_eve.
• Dry-run. Omitted direction is to_eve. Never writes Local files or EVE.

Related¶

• reconcileProject
• getPublicProject
• inspectProject

How-to¶

• Plan changes without applying them
• Make EVE match IaC intent

Signature¶

planProject(body: ProjectPayload, timeoutMs?: number): Promise<PlanData>

• HTTP: POST /api/v1/projects/plan
• operationId: planProject
• Authentication: Bearer token required
• Default timeout: 180000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 180000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

PlanData

Field	TypeScript type	Required	Semantics
lab	string	no
exists	boolean	no
summary	PlanSummary	no
operations	Array<PlanAction>	no
actions	Array<PlanAction>	no
applicable	boolean	no
blocked	Array<PlanAction>	no
text	string	no
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
locked	boolean	no
lock	number	no
direction	string	no	omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
unsupported	Array	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "lab": "/IaC/demo.unl",
  "exists": true,
  "direction": "to_eve",
  "applicable": true,
  "plan_identity": "abc123def456",
  "actions": [
    {
      "op": "update_node",
      "key": "n_1",
      "summary": "config changed"
    },
    {
      "op": "restart_node",
      "key": "n_1",
      "summary": "running node needs restart"
    }
  ],
  "summary": {
    "create": 0,
    "update": 1,
    "delete": 0,
    "restart": 1
  }
}

Processing the result¶

Typical field access after a successful call:

const plan = await client.planProject(packed);
const planIdentity = plan.plan_identity; // do not gate on plan.applicable

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
invalid_direction	Contractual/known for this call or its transport
plan_stale	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.planProject({ lab, manifest, yaml, files });

deployProject¶

Family: Lifecycle

Purpose¶

Creates the managed EVE lab from this project. If the managed lab already exists, the call fails unless replace is set, in which case the existing lab is removed and created again.

Mental model¶

Create the managed lab.

Use when¶

• the project does not yet have a managed lab

Do not use when¶

• the lab already exists and you only want to update it; use reconcileProject
• you only want a diff; use planProject

Reads¶

• the packed project

Changes¶

Creates the managed EVE lab. replace also stops, wipes, and deletes the previous one.

Related¶

• reconcileProject
• destroyProject

Signature¶

deployProject(body: ProjectPayload, timeoutMs?: number): Promise<DeployData>

• HTTP: POST /api/v1/projects/deploy
• operationId: deployProject
• Authentication: Bearer token required
• Default timeout: 300000 ms

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 300000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

DeployData

Field	TypeScript type	Required	Semantics
lab	string	no
nodes	number	no
links	number	no
state	unknown	no
unsupported	Array	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "lab": "/IaC/demo.unl",
  "state": {
    "node_ids": {
      "n_1": 3,
      "n_2": 4
    }
  }
}

Processing the result¶

Typical field access after a successful call:

const deployed = await client.deployProject(packed);
console.log(deployed.lab);

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
lab_exists	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
lab_locked	Contractual/known for this call or its transport
lab_locked_mid_apply	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.deployProject({ lab, manifest, yaml, files });

reconcileProject¶

Family: Reconciliation

Purpose¶

Applies one direction. to_eve makes the EVE lab match IaC intent. from_eve reads the current EVE UNL definition and returns it as the new IaC intent. from_eve does not capture transient runtime state and it is not importProject.

Mental model¶

to_eve: make EVE match my intent. from_eve: make the current UNL definition my new intent.

Use when¶

• pushing IaC intent into EVE
• adopting the current UNL definition as the new YAML intent

Do not use when¶

• you only want the diff; use planProject
• you want a live node poll; use getProjectStatus
• you want to adopt a source lab as new IaC intent; use importProject

Reads¶

• IaC intent and the current EVE UNL definition

Changes¶

to_eve can change EVE. from_eve returns new IaC intent and does not perform mutating EVE writes.

Important semantics¶

• An unsupported plan action means to_eve performs zero EVE mutations.
• confirm=true on to_eve may stop nodes classified requires_stop only after the live-safe work, and only with a matching plan identity.
• from_eve confirm does not authorize a stop.
• to_eve mutates EVE only when no PlanAction is unsupported; any unsupported action means zero EVE mutations and the plan stays inspectable. from_eve updates Local from the managed lab with no mutating EVE writes. from_eve is not Import. When the plan has no unsupported action, confirm=true on to_eve stops classified requires_stop nodes only after live-safe work. applicable is a summary and must not gate execution.

Related¶

• planProject
• importProject
• getPublicProject

How-to¶

• Make EVE match IaC intent
• Make the current EVE lab definition the new intent

Signature¶

reconcileProject(body: ProjectPayload, timeoutMs?: number): Promise<ReconcileData>

• HTTP: POST /api/v1/projects/reconcile
• operationId: reconcileProject
• Authentication: Bearer token required
• Default timeout: 300000 ms

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 300000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ReconcileData

Field	TypeScript type	Required	Semantics
lab	string	no
direction	string	no	omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
status	"converged"	"partial"	"pending_stop"
applied	number	no
skippedPrune	number	no
fullDeploy	boolean	no
applicable	boolean	no	Summary only: full immediate convergence is possible (no requires_stop, no unsupported, not locked). Must not gate execution.
desired_updated	boolean	no
live	({
applied?: number;
failed?: number;
} & Record)	no
requires_stop	({
nodes?: Array;
changes?: number;
} & Record)	no
unsupported	Record	no	Object {changes, messages} on reconcile. Plan still uses string[].
runtime	({
stopped?: Array;
restarted?: Array;
} & Record)	no
summary	PlanSummary	no
operations	Array<PlanAction>	no	The plan that was considered. Classification is not proof that a call was sent.
executed	Array<ReconcileStep>	no	Side effects this reconcile actually performed or refused. effect is applied, failed, skipped, or pending_stop.
text	string	no	Human-readable execution report. Same facts as executed.
blocked	Array<PlanAction>	no
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
state	unknown	no
yaml	string	no
files	Record	no
source	unknown	no
manifest	string	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "lab": "/IaC/demo.unl",
  "applied": 2,
  "direction": "to_eve",
  "applicable": true,
  "state": {
    "node_ids": {
      "n_1": 3
    }
  }
}

Processing the result¶

Typical field access after a successful call:

const result = await client.reconcileProject({ ...packed, plan_identity: identity });
console.log(result.status, result.applied);

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
invalid_direction	Contractual/known for this call or its transport
plan_stale	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
lab_locked	Contractual/known for this call or its transport
lab_locked_mid_apply	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

await client.reconcileProject({ lab, manifest, yaml, files, direction: "to_eve" });
const pulled = await client.reconcileProject({ lab, manifest, yaml, files, direction: "from_eve" });
// to_eve makes EVE match IaC intent. from_eve makes the UNL definition the new intent.

destroyProject¶

Family: Lifecycle

Purpose¶

Deletes the managed EVE lab. Omitted wipe still wipes the nodes first.

Mental model¶

Delete the managed lab.

Use when¶

• removing the managed lab this project owns

Do not use when¶

• you want to stop nodes and keep the lab; use execProject with stop

Reads¶

• the managed lab path

Changes¶

Deletes the managed EVE lab. Omitted wipe wipes nodes; explicit wipe false deletes the lab without that wipe.

Related¶

• deployProject
• execProject

Signature¶

destroyProject(body: ProjectPayload, timeoutMs?: number): Promise<DestroyData>

• HTTP: POST /api/v1/projects/destroy
• operationId: destroyProject
• Authentication: Bearer token required
• Default timeout: 180000 ms

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 180000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

DestroyData

Field	TypeScript type	Required	Semantics
lab	string	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "lab": "/IaC/demo.unl"
}

Processing the result¶

Typical field access after a successful call:

await client.destroyProject(packed);

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
lab_locked	Contractual/known for this call or its transport
lab_locked_mid_apply	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.destroyProject({ lab, manifest, yaml, files });

getProjectStatus¶

Family: Observation

Purpose¶

Returns a lightweight view of the project's current live EVE state, including node runtime states and current link impairments, without rebuilding the structural lab model.

Mental model¶

What is alive right now?

Use when¶

• polling running, stopped, starting, or busy node state
• updating a live UI overlay
• reading current runtime netem
• building monitoring or automation
• checking runtime state from an SDK or from eve-iac status

Do not use when¶

• you need nodes, interfaces, links, and presentation as a structural model; use inspectProject
• you need YAML intent; use getPublicProject
• you want to modify EVE

Reads¶

• project context
• the current EVE runtime lab
• EVE nodes/status

Changes¶

Nothing. Read-only.

Performance¶

Lightweight and suitable for polling, including the canvas once per second. When a runtime lab exists the agent uses the existing lab lookup plus one nodes/status request. It does not export the lab, rebuild topology, read configs, or call each node.

Important semantics¶

• live omitted means there is no runtime lab. That is not an empty lab.
• live.available true is an authoritative successful live read. nodes is always an array and netem is always an object.
• A successful empty nodes array or empty netem object is an authoritative empty result. Do not treat it as a failed read.
• live.available false means the nodes/status read failed. nodes and netem are omitted. The project status call stays HTTP 200 so existing context readers keep working.
• A missing netem side means effective delay 0, jitter 0, loss 0, and bandwidth 0. The response does not include a present zero side.
• joined false means runtime rows were read but they are not all mapped to IaC identities.
• GetLab lock behavior is unchanged: a lock lookup failure stays locked false and HTTP 200.
• Project context plus a lightweight live read. Existing fields stay mode, labs, capabilities, and lock. When runtime_lab is set, live is one GET nodes/status: nodes and netem. A missing netem side is 0,0,0,0 and is omitted. live.available false means that query failed; nodes and netem are then omitted. No runtime lab omits live. Not a lab snapshot and not YAML intent.

Related¶

• inspectProject
• getPublicProject
• planProject
• reconcileProject

How-to¶

• Observe a live lab
• Build a live UI or monitoring loop
• Apply runtime link quality

Signature¶

getProjectStatus(body: ProjectPayload, timeoutMs?: number): Promise<ProjectStatusData>

• HTTP: POST /api/v1/projects/status
• operationId: getProjectStatus
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ProjectStatusData

Field	TypeScript type	Required	Semantics
mode	string	no
source_lab	string	null	no
managed_lab	string	null	no
runtime_lab	string	null	no
capabilities	ProjectModeCaps	no
locked	boolean	no
lock	number	no
live	ProjectLiveStatus	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "mode": "create",
  "runtime_lab": "/IaC/demo.unl",
  "managed_lab": "/IaC/demo.unl",
  "capabilities": {
    "topology_mutation": true,
    "reconcile": true,
    "destroy": true,
    "lifecycle": {
      "start": true,
      "stop": true,
      "wipe": true
    }
  },
  "locked": false
}

Processing the result¶

Typical field access after a successful call:

const status = await client.getProjectStatus(packed);
console.log(status.runtime_lab);

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const status = await client.getProjectStatus({ lab, manifest, yaml, files });
if (status.live?.available) {
  for (const node of status.live.nodes ?? []) {
    console.log(`${node.key}: ${node.state_label}`);
  }
}

inspectProject¶

Family: Observation

Purpose¶

Builds a rich structural observation of the EVE lab: nodes, templates, interfaces, networks, links, topology, presentation, config sets, and the runtime metadata attached to that model.

Mental model¶

What does the current EVE lab look like?

Use when¶

• the first canvas load
• a structural refresh
• resolving node and interface identities
• discovering links and presentation objects

Do not use when¶

• you only need live node state or runtime netem; use getProjectStatus
• you need YAML intent; use getPublicProject
• you are polling every second

Reads¶

• the EVE lab structure and the runtime metadata attached to it

Changes¶

Nothing. Read-only.

Performance¶

A rich structural observation. It is more expensive than getProjectStatus. Do not use it as a high-frequency poll.

Important semantics¶

• For frequent runtime polling, use getProjectStatus. For a structural snapshot, use inspectProject.
• A missing netem side means effective delay 0, jitter 0, loss 0, and bandwidth 0, and is omitted.
• The runtime request flag remains a temporary alias of the getProjectStatus poll.
• Observation, not desired state. Node key is the current repo/state identity join (logical IaC key when mapped); native id is runtime metadata. Not topology.yml. Use getPublicProject for the public IaC JSON tree. Live node state and netem belong on getProjectStatus. A missing netem side is 0,0,0,0 and is omitted. The runtime request flag remains a temporary alias of that poll.

Related¶

• getProjectStatus
• getPublicProject

How-to¶

• Load the structural lab model
• Build a live UI or monitoring loop

Signature¶

inspectProject(body: ProjectPayload, timeoutMs?: number): Promise<InspectionData>

• HTTP: POST /api/v1/projects/inspect
• operationId: inspectProject
• Authentication: Bearer token required
• Default timeout: 300000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 300000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

InspectionData

Field	TypeScript type	Required	Semantics
observation	boolean	no
desired_state	boolean	no
mode	string	no
source_lab	unknown	no
managed_lab	unknown	no
runtime_lab	string	no
capabilities	ProjectModeCaps	no
cached	boolean	no
nodes	Array<InspectNode>	no
netem	AppliedNetem	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Large observation payload is under additional keys when present. LOAD mode sets desired_state=false.

{
  "mode": "load",
  "observation": true,
  "desired_state": false,
  "runtime_lab": "/Customers/OSPF.unl",
  "cached": false,
  "capabilities": {
    "topology_mutation": false,
    "reconcile": false,
    "destroy": false,
    "lifecycle": {
      "start": true,
      "stop": true,
      "wipe": true
    }
  }
}

Processing the result¶

Typical field access after a successful call:

const data = await client.inspectProject(packed);
console.log(data.runtime_lab);

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const observed = await client.inspectProject({ lab, manifest, yaml, files, refresh: true });
// Structural snapshot. Poll live node state with getProjectStatus.

getPublicProject¶

Family: Intent

Purpose¶

Returns the current IaC intent as public JSON, the same information as topology.yml or eve-presentation.yml. It does not read live EVE.

Mental model¶

What do I currently want?

Use when¶

• reading or selecting a subtree of YAML intent
• checking presentation intent

Do not use when¶

• you need live node state; use getProjectStatus
• you need the structural EVE snapshot; use inspectProject

Reads¶

• topology.yml or eve-presentation.yml in the packed project

Changes¶

Nothing. Read-only.

Important semantics¶

• An optional path selects a subtree. An optional filter is an exact IaC key on /nodes, /networks, or /links.
• file is topology or presentation. A missing presentation file returns present false.
• Canonical public IaC JSON isomorphic to topology.yml or eve-presentation.yml. Optional RFC 6901 path selects a subtree. Optional filter is an exact IaC key on /nodes, /networks, or /links only. file=topology|presentation. Absent presentation returns {present:false}. Never reads state/Internal. Does not inspect live EVE.

Related¶

• editProject
• getProjectStatus
• inspectProject
• planProject

How-to¶

• Use traffic filters

Signature¶

getPublicProject(body: ProjectPayload, timeoutMs?: number): Promise<PublicData>

• HTTP: POST /api/v1/projects/public
• operationId: getPublicProject
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

PublicData

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const topology = await client.getPublicProject({ yaml, files, file: "topology" });
// IaC intent. This does not read live EVE.

editProject¶

Family: Intent

Purpose¶

Applies a batch of JSON edits to topology.yml and validates the result before anything is written. It does not deploy, plan, or reconcile.

Mental model¶

Change my IaC intent.

Use when¶

• adding, updating, or deleting nodes, networks, or links in YAML intent

Do not use when¶

• you want EVE to change now; use reconcileProject after the edit
• you want to edit startup-config blobs; use editProjectConfig

Reads¶

• topology.yml

Changes¶

Rewrites topology.yml when the batch validates. applied false writes nothing.

Important semantics¶

• Batch canonical JSON mutations of topology.yml only. One read/parse/apply/validate/serialize. A node or network delete may include deterministic repairs (dangling link match-delete, configset entry remove) in the same in-memory transaction; repairs is omitted when there are none. The invalid intermediate is never serialized. HTTP 200 data is {applied, operations, changed?, valid, errors[], yaml?, repairs?}. applied=false writes nothing. Does not deploy, plan, or reconcile. yaml is a persist sidecar; MCP strips it from the model-visible result.

Related¶

• getPublicProject
• validateProject
• reconcileProject

How-to¶

• Use traffic filters

Signature¶

editProject(body: EditRequest, timeoutMs?: number): Promise<EditResult>

• HTTP: POST /api/v1/projects/edit
• operationId: editProject
• Authentication: Bearer token required
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	EditRequest	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: EditRequest¶

This request type is the same wire shape as EditRequest.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.
operations	Array<EditOperation>	yes	Bounded canonical mutations applied as one in-memory transaction. Not RFC 6902 JSON Patch.

Returns¶

EditResult

Field	TypeScript type	Required	Semantics
applied	boolean	yes
operations	number	yes
changed	EditChanged	no
valid	boolean	yes
errors	Array<ValidationError>	yes
yaml	string	no	Canonical topology.yml after a successful edit. Clients persist it locally. MCP strips this field from the model-visible result. Never an Internal/native dump.
repairs	Array<EditOperation>	no	Deterministic closures the agent added to a node or network delete in this same transaction. Omitted when the requested operations were already coherent. Clients do not compute or replay these operations.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "applied": true,
  "operations": 10,
  "changed": {
    "nodes": [
      "r1",
      "r2",
      "r3",
      "r4"
    ],
    "links": 6
  },
  "valid": true,
  "errors": []
}

Processing the result¶

Typical field access after a successful call:

const edited = await client.editProject({ ...packed, operations });
if (!edited.applied) throw new Error("edit not applied");

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.editProject({ lab, manifest, yaml, files });

getProjectConfig¶

Family: Intent

Purpose¶

Reads startup-config blobs that belong to IaC intent: an index, one blob, or a literal search.

Mental model¶

What startup config do I intend?

Use when¶

• listing, fetching, or searching startup-config text

Do not use when¶

• you want to change a blob; use editProjectConfig
• you want live node state

Reads¶

• packed startup-config files

Changes¶

Nothing. Read-only.

Important semantics¶

• Startup-config index/get/search. operation is index|get|search. lab in SUCCESS is topology name:, never an EVE or IaC path. Never returns configs/ paths. Empty blob is present=true bytes=0 with sha256 of zero bytes. Missing blob is present=false (sha256 omitted). Omitted packed files is 400 config_unavailable, not present=false. files:{} is authoritative absence. Search is literal substring; query required max 256 chars; limit omitted=20 max 50 hits; context_lines omitted=0 max 3; per-config max 1 MiB is config_too_large. Zero matches is SUCCESS results={}.

Related¶

• editProjectConfig

Signature¶

getProjectConfig(body: ConfigReadRequest, timeoutMs?: number): Promise<ConfigData>

• HTTP: POST /api/v1/projects/config
• operationId: getProjectConfig
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	ConfigReadRequest	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: ConfigReadRequest¶

This request type is the same wire shape as ConfigReadRequest.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.
operation	"index"	"get"	"search"
template	string	no	Exact template id filter for index/search.
present	boolean	no	index only. true = blobs present, false = missing. Omitted = both.
query	string	no	search only. Literal substring. Required. Max 256 characters. Empty is invalid_request.
case_sensitive	boolean	no	search only. Omitted = case-insensitive.
limit	number	no	search only. Total match hits, not configs. Omitted = 20. Max 50. No OpenAPI default.
context_lines	number	no	search only. Neighbor lines around each hit. Omitted = 0. Max 3. No OpenAPI default.

Returns¶

ConfigData

Field	TypeScript type	Required	Semantics
lab	string	no
scope	{
nodes?: Array;
}	no
entries	RecordConfigIndexEntry>	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
template	string	no
configset	string	no
present	boolean	no
bytes	number	no
sha256	string	no
content	string	no
query	string	no
truncated	boolean	no
results	RecordConfigSearchNode>	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "lab": "mesh",
  "node": "ceos1",
  "template": "ceos",
  "configset": "default",
  "present": true,
  "bytes": 842,
  "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "content": "hostname ceos1\n"
}

Processing the result¶

Typical field access after a successful call:

const cfg = await client.getProjectConfig({ ...packed, operation: "get", node: "ceos1" });
if (!cfg.present) throw new Error("missing config");

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
unknown_node	Contractual/known for this call or its transport
unknown_configset	Contractual/known for this call or its transport
config_too_large	Contractual/known for this call or its transport
config_unavailable	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.getProjectConfig({ lab, manifest, yaml, files });

editProjectConfig¶

Family: Intent

Purpose¶

Puts or deletes startup-config blobs and updates the config library in IaC intent. It does not deploy the lab.

Mental model¶

Change the startup config I intend.

Use when¶

• writing or removing a startup-config blob

Do not use when¶

• LOAD mode
• you want the change pushed to EVE; deploy or reconcile after this

Reads¶

• packed startup-config files and the config library

Changes¶

Writes startup-config blobs and library binds when the whole batch validates. A conflict writes nothing.

Important semantics¶

• Batch put/delete of startup-config blobs. Preflight all, then apply library binds in memory and ValidateDir before SUCCESS. expected_sha256 mismatch is 409 config_conflict with zero writes. PUT auto-binds configsets..=rel and fills an empty node selector. Selector none with no op.configset is invalid_request. Selector none plus explicit op.configset writes that library and does not change the selector. DELETE drops the blob and library map entry; keeps an empty configsets. when a node still selects it; does not clear nodes.*.configset. HTTP 200 data is {lab, applied, operations, changed}; files/yaml/deleted are persist sidecars stripped by MCP. Invalid resulting YAML is 400 invalid_request with no sidecars. LOAD is forbidden. Does not deploy.

Related¶

• getProjectConfig

Signature¶

editProjectConfig(body: ConfigEditRequest, timeoutMs?: number): Promise<ConfigEditData>

• HTTP: POST /api/v1/projects/config/edit
• operationId: editProjectConfig
• Authentication: Bearer token required
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	ConfigEditRequest	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: ConfigEditRequest¶

This request type is the same wire shape as ConfigEditRequest.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.
operations	Array<ConfigEditOp>	yes	Preflight all, then write. Not a multi-file transaction.

Returns¶

ConfigEditData

Field	TypeScript type	Required	Semantics
lab	string	yes
applied	boolean	yes
operations	number	yes
changed	RecordConfigChanged>	yes
files	Record	no	Changed blobs keyed by project-relative configs/ path. Persist sidecar. MCP strips this field.
yaml	string	no	Canonical topology.yml when configsets or node selectors changed. Persist sidecar. MCP strips this field.
deleted	Array	no	Project-relative configs/ paths to unlink. Persist sidecar. MCP strips this field.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "lab": "mesh",
  "applied": true,
  "operations": 1,
  "changed": {
    "ceos1": {
      "configset": "default",
      "present": true,
      "bytes": 14,
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  }
}

Processing the result¶

Typical field access after a successful call:

const edited = await client.editProjectConfig({ ...packed, operations });
if (!edited.applied) throw new Error("config edit not applied");

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
unknown_node	Contractual/known for this call or its transport
unknown_configset	Contractual/known for this call or its transport
config_too_large	Contractual/known for this call or its transport
config_conflict	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.editProjectConfig({ lab, manifest, yaml, files });

openProject¶

Family: Session

Purpose¶

Confirms the runtime lab exists and returns a short-lived URL that opens it in the browser UI.

Mental model¶

Open this lab in the browser.

Use when¶

• handing a user a browser URL for the runtime lab

Do not use when¶

• you need node state or the structural model

Reads¶

• the runtime lab

Changes¶

Issues a browser token.

Signature¶

openProject(body: ProjectPayload, timeoutMs?: number): Promise<OpenData>

• HTTP: POST /api/v1/projects/open
• operationId: openProject
• Authentication: Bearer token required
• Default timeout: 30000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 30000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

OpenData

Field	TypeScript type	Required	Semantics
url	string	no
ttl	number	no
lab	string	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "url": "https://eve.example/#/lab/abc123"
}

Processing the result¶

Typical field access after a successful call:

const opened = await client.openProject(packed);

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.openProject({ lab, manifest, yaml, files });

Execution / Consoles¶

listProjectConsoles¶

Family: Console

Purpose¶

Lists the console endpoints for nodes in the runtime lab, including whether each node is mapped to an IaC key.

Mental model¶

Where can I attach a console?

Use when¶

• discovering console targets before attach or exec

Do not use when¶

• you want to send a command; use execConsole or runConsole

Reads¶

• nodes in the runtime lab

Changes¶

Nothing. Read-only.

Related¶

• attachConsole
• execConsole

Signature¶

listProjectConsoles(body: ProjectPayload, timeoutMs?: number): Promise<ConsolesData>

• HTTP: POST /api/v1/projects/consoles
• operationId: listProjectConsoles
• Authentication: Bearer token required
• Default timeout: 30000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 30000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ConsolesData

Field	TypeScript type	Required	Semantics
lab	string	no
html5	boolean	no
consoles	Array<ConsoleRecord>	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "consoles": [
    {
      "node": "n_1",
      "name": "R1",
      "status": "running",
      "protocol": "telnet",
      "host": "127.0.0.1",
      "port": 32769
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

const { consoles } = await client.listProjectConsoles(packed);

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.listProjectConsoles({ lab, manifest, yaml, files });

execProject¶

Family: Lifecycle

Purpose¶

Starts, stops, or wipes nodes in the runtime lab. One call covers the listed IaC keys, or every node when the selection is omitted.

Mental model¶

Start, stop, or wipe these nodes.

Use when¶

• starting nodes
• stopping nodes
• wiping node disks

Do not use when¶

• you want to delete the lab; use destroyProject
• you want to change topology; use reconcileProject

Reads¶

• the runtime lab and the selected node keys

Changes¶

Starts, stops, or wipes the selected nodes.

Important semantics¶

• Omitted stopmode is the automatic mode. Explicit 0 is a graceful stop and is different from omitting the field.
• action is start|stop|wipe. nodes is one bulk call for that IaC key list. Omitted nodes uses node. Omitted or empty node means all nodes. Success data is BulkResult with stable lowercase keys. Omitted stopmode is 3; explicit 0 is graceful.

Related¶

• getProjectStatus
• destroyProject

How-to¶

• Start, stop, and wipe lab nodes

Signature¶

execProject(body: ProjectPayload & {
  action: string;
}, timeoutMs?: number): Promise<BulkResult>

• HTTP: POST /api/v1/projects/exec
• operationId: execProject
• Authentication: Bearer token required
• Default timeout: 180000 ms

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload & { action: string; }	yes	Request body.
timeoutMs	number	no	Override the 180000 ms default.

Request schema¶

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	yes
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

BulkResult

Field	TypeScript type	Required	Semantics
requested	number	yes
started	number	yes
already_running	number	yes
already_starting	number	yes
stopped	number	yes
already_stopped	number	yes
wiped	number	yes
failed	number	yes
invalid	number	yes

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "requested": 2,
  "started": 2,
  "already_running": 0,
  "already_starting": 0,
  "stopped": 0,
  "already_stopped": 0,
  "wiped": 0,
  "failed": 0,
  "invalid": 0
}

Processing the result¶

Typical field access after a successful call:

const result = await client.execProject({ ...packed, action: "start" });
if ((result.failed ?? 0) + (result.invalid ?? 0) > 0) process.exit(1);

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
lab_locked	Contractual/known for this call or its transport
lab_locked_mid_apply	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.execProject({ lab, manifest, yaml, files, action: "start" });

exportProjectConfig¶

Family: Startup config

Purpose¶

Writes the running configuration into the chosen EVE startup-config set so a later from_eve can adopt that blob. It does not change IaC files.

Mental model¶

Save the running configuration into this startup-config set.

Use when¶

• the useful configuration is the one running on the node
• a later reconcile from_eve should adopt that startup-config

Do not use when¶

• you want to edit the IaC startup library; use editProjectConfig
• you want to adopt the lab into the project now; use reconcileProject direction from_eve after this call
• you want the running text returned to the client

Reads¶

• the runtime lab, its configsets, and the selected nodes

Changes¶

Replaces the chosen set's startup-config blob on the lab. Restores the node config selector when it had to be switched for the native export.

Important semantics¶

• confirm is enforced by MCP and the CLI. The agent performs the export for a managed lab.
• A node failure does not undo nodes already exported. failed and selector_restore_failed are separate.
• Copies the running NOS configuration into an existing EVE startup-config set. configset is required: default, or the name of a set already on the lab. An unknown name is 400 unknown_configset and creates nothing. nodes is an optional IaC key list; omitted nodes uses node; omitted both means every config-capable node. config -1 is skipped. Stopped nodes are still exported and an EVE refusal such as 80084 or 80061 is failed for that node only. This is not editProjectConfig, not reconcile from_eve, and not a capture returned to the client. topology.yml and configs/** are not written. LOAD and source_lab are 403 operation_not_allowed. A locked lab is refused before writes.

Related¶

• editProjectConfig
• reconcileProject
• execProject

How-to¶

• Copy the running configuration into a startup-config set

Signature¶

exportProjectConfig(body: ExportConfigRequest, timeoutMs?: number): Promise<ExportConfigData>

• HTTP: POST /api/v1/projects/export-config
• operationId: exportProjectConfig
• Authentication: Bearer token required
• Default timeout: 1800000 ms

Parameters¶

Parameter	Type	Required	Description
body	ExportConfigRequest	yes	Request body.
timeoutMs	number	no	Override the 1800000 ms default.

Request schema: ExportConfigRequest¶

This request type is the same wire shape as ExportConfigRequest.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	yes	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ExportConfigData

Field	TypeScript type	Required	Semantics
lab	string	yes
configset	string	yes
nodes	Array<ExportConfigNode>	yes

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Copies the running NOS configuration into an existing EVE startup-config set. Does not write topology.yml or configs/**. A later from_eve adopts the blob. Unknown set is unknown_configset and creates nothing. LOAD and source_lab are refused.

{
  "lab": "/Lab.unl",
  "configset": "default",
  "nodes": [
    {
      "key": "n_1",
      "id": 1,
      "status": "exported"
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

const saved = await client.exportProjectConfig({ ...packed, configset: "default", nodes: ["n_1"] });
const failed = (saved.nodes ?? []).filter((node) => node.status === "failed");

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
unknown_configset	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
lab_locked	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const saved = await client.exportProjectConfig({ lab, manifest, yaml, files, configset: "default", nodes: ["n_1"] });
// Writes the running configuration into that EVE startup-config set.
// It does not change topology.yml. Adopt it later with reconcileProject direction from_eve.

applyLinkQuality¶

Family: Runtime interaction

Purpose¶

Applies live delay, jitter, loss, and bandwidth to one Ethernet link identified by public YAML endpoints. It does not rewrite topology.yml.

Mental model¶

Impair this live link.

Use when¶

• setting or clearing live netem on an Ethernet link
• persisting that impairment into the UNL when save is true

Do not use when¶

• you only want to read the current impairment; use getProjectStatus
• the link is serial

Reads¶

• the public YAML link identity

Changes¶

Changes live netem on the matched link. save true also asks EVE to persist it in the UNL.

Important semantics¶

• Omitted impairment clears live netem on that side.
• Omitted save is live only and does not rewrite topology.yml.
• Public YAML identity (n_1 + interface). Optional save=true sends native save=1 (UNL persist for an admin session on an unlocked lab); omitted save is live-only. persisted follows save. Does not rewrite topology.yml. LOAD allowed like exec. Serial is 400 serial_impairment_unsupported. Unknown match is 400 unknown_link. Native lock is not required for the live apply.

Related¶

• getProjectStatus
• setLinkSuspend

How-to¶

• Apply runtime link quality

Signature¶

applyLinkQuality(body: ProjectPayload & {
  match: PublicLinkMatch;
  source_impairment?: LinkImpairment;
  destination_impairment?: LinkImpairment;
  save?: boolean;
}, timeoutMs?: number): Promise<LinkQualityData>

• HTTP: POST /api/v1/projects/links/quality
• operationId: applyLinkQuality
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload & { match: PublicLinkMatch; source_impairment?: LinkImpairment; destination_impairment?: LinkImpairment; save?: boolean; }	yes	Request body.
timeoutMs	number	no	Override the 30000 ms default.

Request schema¶

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.
match	PublicLinkMatch	yes
source_impairment	LinkImpairment	no
destination_impairment	LinkImpairment	no
save	boolean	no	When true, native quality save=1 persists NETEM into the UNL (admin session, unlocked lab). Omitted or false is live-only save=0. Never writes topology.yml.

Returns¶

LinkQualityData

Field	TypeScript type	Required	Semantics
applied	boolean	yes
persisted	boolean	yes
match	PublicLinkMatch	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Omitted save is live-only (persisted false, native save=0). save=true / CLI --save persists NETEM into the UNL when the session is admin and the lab is unlocked. Neither rewrites topology.yml. Observe inspectProject.

{
  "applied": true,
  "persisted": false,
  "match": {
    "endpoints": [
      {
        "node": "n_1",
        "interface": "e0/0"
      },
      {
        "node": "n_2",
        "interface": "e0/1"
      }
    ]
  }
}

Processing the result¶

Typical field access after a successful call:

const result = await client.applyLinkQuality({ ...packed, match: { endpoints: [{ node: "n_1", interface: "e0/0" }, { node: "n_2", interface: "e0/1" }] }, source_impairment: { delay: 50 }, save: true });

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
unknown_link	Contractual/known for this call or its transport
unknown_node	Contractual/known for this call or its transport
unknown_interface	Contractual/known for this call or its transport
unknown_network	Contractual/known for this call or its transport
serial_impairment_unsupported	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.applyLinkQuality({
  lab, manifest, yaml, files,
  match: { endpoints: [{ node: "n_1", interface: "e0/0" }, { node: "n_2", interface: "e0/1" }] },
  source_impairment: { delay: 50, loss: 1 },
  save: true,
});

setLinkSuspend¶

Family: Runtime interaction

Purpose¶

Suspends or resumes a live link identified by public YAML endpoints. Suspend is not an IaC intent field and is not written to topology.yml.

Mental model¶

Pause or resume this live link.

Use when¶

• suspending a live link
• resuming a live link

Do not use when¶

• you want the flag stored in YAML
• you want to read it back from getProjectStatus; this poll does not carry suspend

Reads¶

• the public YAML link identity

Changes¶

Suspends or resumes the matched live link.

Important semantics¶

• suspended true suspends and false resumes.
• Omitted side means both node endpoints.
• Observe suspend on a structural inspect, not on the status poll.
• Public YAML identity. suspended true/false maps to native PUT /suspend or /resume. Omitted side is both. Never YAML *_suspend. LOAD allowed. Observe inspect runtime source_suspend. Native lock is not required.

Related¶

• inspectProject
• applyLinkQuality

How-to¶

• Suspend and resume a link

Signature¶

setLinkSuspend(body: ProjectPayload & {
  match: PublicLinkMatch;
  suspended: boolean;
  side?: string;
}, timeoutMs?: number): Promise<LinkSuspendData>

• HTTP: POST /api/v1/projects/links/suspend
• operationId: setLinkSuspend
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload & { match: PublicLinkMatch; suspended: boolean; side?: string; }	yes	Request body.
timeoutMs	number	no	Override the 30000 ms default.

Request schema¶

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.
match	PublicLinkMatch	yes
suspended	boolean	yes	true = native suspend; false = native resume. Required; omitted is 400 invalid_request.
side	string	no	source, destination, or both. Omitted/empty is both. Wire-distinct from explicit both.

Returns¶

LinkSuspendData

Field	TypeScript type	Required	Semantics
applied	boolean	yes
suspended	boolean	yes
side	string	no
match	PublicLinkMatch	no
targets	Array<LinkSuspendTarget>	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Runtime TAP suspend. Never a topology.yml field. Observe inspect runtime source_suspend.

{
  "applied": true,
  "suspended": true,
  "side": "both",
  "match": {
    "endpoints": [
      {
        "node": "n_1",
        "interface": "e0/0"
      },
      {
        "node": "n_2",
        "interface": "e0/1"
      }
    ]
  },
  "targets": [
    {
      "node": "n_1",
      "interface": "e0/0"
    },
    {
      "node": "n_2",
      "interface": "e0/1"
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

const result = await client.setLinkSuspend({ ...packed, match: { endpoints: [{ node: "n_1", interface: "e0/0" }, { node: "n_2", interface: "e0/1" }] }, suspended: true });

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
unknown_link	Contractual/known for this call or its transport
unknown_node	Contractual/known for this call or its transport
unknown_interface	Contractual/known for this call or its transport
unknown_network	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.setLinkSuspend({
  lab, manifest, yaml, files,
  match: { endpoints: [{ node: "n_1", interface: "e0/0" }, { node: "n_2", interface: "e0/1" }] },
  suspended: true,
});

startCapture¶

Family: Capture

Purpose¶

Starts a packet capture on one node interface and returns an HTML5 capture URL.

Mental model¶

Capture packets on this interface.

Use when¶

• opening a capture window for one interface

Do not use when¶

• you want a traffic-stream ticket; use attachTraffic

Reads¶

• the public node and interface

Changes¶

Starts a capture docker for that interface.

Important semantics¶

• Closing the browser tab does not stop the capture docker.
• Public node and interface. Native capture_mode=1. HTML5 URL only. evecapture:// is 400. LOAD allowed. Closing the tab does not stop the docker. No MCP tool.

Related¶

• attachTraffic

How-to¶

• Capture traffic

Signature¶

startCapture(body: ProjectPayload & {
  node: string;
  "interface": string;
}, timeoutMs?: number): Promise<CaptureData>

• HTTP: POST /api/v1/projects/capture
• operationId: startCapture
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload & { node: string; "interface": string; }	yes	Request body.
timeoutMs	number	no	Override the 30000 ms default.

Request schema¶

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	yes	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.
interface	string	yes	Interface name on that node.

Returns¶

CaptureData

Field	TypeScript type	Required	Semantics
node	string	yes	omitted: all nodes. empty string: all nodes. named: that IaC node key
interface	string	yes
url	string	yes

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
unknown_node	Contractual/known for this call or its transport
unknown_interface	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.startCapture({ lab, manifest, yaml, files, node: "n_1", interface: "e0/0" });

attachTraffic¶

Family: Capture

Purpose¶

Creates a ticket for a translated traffic stream. The agent keeps native EVE ids and dials the EVE traffic socket.

Mental model¶

Let me watch this lab's traffic.

Use when¶

• obtaining a ticket before streamTraffic

Do not use when¶

• you want a packet-capture page; use startCapture

Reads¶

• the runtime lab

Changes¶

Issues a one-time traffic ticket.

Important semantics¶

• Ticket for the translated traffic stream. Agent dials EVE /traffic-ws. Native ids stay on the agent. LOAD allowed. No MCP tool.

Related¶

• streamTraffic
• startCapture

How-to¶

• Use traffic filters

Signature¶

attachTraffic(body: ProjectPayload, timeoutMs?: number): Promise<TrafficAttachData>

• HTTP: POST /api/v1/projects/traffic/attach
• operationId: attachTraffic
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 30000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

TrafficAttachData

Field	TypeScript type	Required	Semantics
stream	string	yes
transport	string	yes

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
unknown_node	Contractual/known for this call or its transport
unknown_interface	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const attached = await client.attachTraffic({ lab, manifest, yaml, files });

execConsole¶

Family: Console

Purpose¶

Sends one command to a node console and returns when the prompt comes back.

Mental model¶

Run one command on this console.

Use when¶

• a single show, ping, or similar command

Do not use when¶

• you need an ordered expect and send script; use runConsole

Reads¶

• the node console

Changes¶

Writes the command to the console and reads the reply.

Important semantics¶

• Joins or opens the Hub whether session_id is omitted or present. A missing session reopens once. Completes on prompt return after the send. Server clamps timeout_ms to exec max 60000.

Related¶

• runConsole
• attachConsole

How-to¶

• Execute console commands

Signature¶

execConsole(body: ConsolePayload, timeoutMs?: number): Promise<ConsoleExecData>

• HTTP: POST /api/v1/console/exec
• operationId: execConsole
• Authentication: Bearer token required
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	ConsolePayload	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: ConsolePayload¶

This request type is the same wire shape as ConsolePayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
manifest	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	string	no
commands	Array	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	number	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	Array<ConsoleTarget>	no
session_id	string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq	number	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	string	no	Go regexp for waitConsole.
max_bytes	number	no	Bounded history tail for getConsoleHistory.
steps	Array<ConsoleRunStep>	no
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ConsoleExecData

Field	TypeScript type	Required	Semantics
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
name	string	no
console_type	string	no
command	string	no
output	string	no
duration_ms	number	no
timed_out	boolean	no
truncated	boolean	no
prompt	string	no
session_id	string	no
match	string	no
phase	string	no	Interaction phase: discovering, ready, executing, paging, interactive, auth_required, error.
recovered	boolean	no	True when a missing session was reopened for this call.
rx_to	number	no	Receive sequence of the last byte belonging to this command.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "output": "Cisco IOS Software, Version 15.2(4)M6\n",
  "node": "n_1"
}

Processing the result¶

Typical field access after a successful call:

const data = await client.execConsole({ ...packed, node: "n_1", command: "show version" });
console.log(data.output);

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const data = await client.execConsole({ lab, node: "n_1", command: "show version" });

execConsoleMany¶

Family: Console

Purpose¶

Sends one command to several node consoles. A failure on one target stays on that target.

Mental model¶

Run one command on each of these consoles.

Use when¶

• the same command on several nodes

Do not use when¶

• you need a scripted dialogue; use runConsole

Reads¶

• each target console

Changes¶

Writes the command to each selected console.

Important semantics¶

• Joins the Hub for each target. One target failure stays on that target. Server clamps timeout_ms to exec max 60000.

Related¶

• execConsole

How-to¶

• Execute console commands

Signature¶

execConsoleMany(body: ConsolePayload, timeoutMs?: number): Promise<ConsoleExecManyData>

• HTTP: POST /api/v1/console/exec-many
• operationId: execConsoleMany
• Authentication: Bearer token required
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	ConsolePayload	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: ConsolePayload¶

This request type is the same wire shape as ConsolePayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
manifest	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	string	no
commands	Array	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	number	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	Array<ConsoleTarget>	no
session_id	string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq	number	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	string	no	Go regexp for waitConsole.
max_bytes	number	no	Bounded history tail for getConsoleHistory.
steps	Array<ConsoleRunStep>	no
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ConsoleExecManyData

Field	TypeScript type	Required	Semantics
results	Array<ConsoleExecData & ({
ok?: boolean;
code?: string;
error?: string;
} & Record)>	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "results": [
    {
      "node": "n_1",
      "output": "R1#",
      "ok": true
    },
    {
      "node": "n_2",
      "output": "R2#",
      "ok": true
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

const data = await client.execConsoleMany(packed);
for (const row of data.results ?? []) console.log(row.node);

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.execConsoleMany({ lab, manifest, yaml, files });

createConsoleSession¶

Family: Console

Purpose¶

Creates or joins the console session for one node so later commands can reuse it.

Mental model¶

Hold this console open.

Use when¶

• preparing a session before several commands

Reads¶

• the node console

Changes¶

Creates or joins a console session.

Important semantics¶

• Creates or joins Hub lease for (lab, node). Default mode interact when omitted.

Related¶

• execConsole
• closeConsoleSession

Signature¶

createConsoleSession(body: ConsolePayload, timeoutMs?: number): Promise<ConsoleSessionData>

• HTTP: POST /api/v1/console/sessions
• operationId: createConsoleSession
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	ConsolePayload	yes	Request body.
timeoutMs	number	no	Override the 30000 ms default.

Request schema: ConsolePayload¶

This request type is the same wire shape as ConsolePayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
manifest	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	string	no
commands	Array	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	number	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	Array<ConsoleTarget>	no
session_id	string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq	number	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	string	no	Go regexp for waitConsole.
max_bytes	number	no	Bounded history tail for getConsoleHistory.
steps	Array<ConsoleRunStep>	no
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ConsoleSessionData

Field	TypeScript type	Required	Semantics
session_id	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
name	string	no
console_type	string	no
mode	ConsoleWriteMode	no
state	"idle"	"connecting"	"open"
created_at	string	no
last_activity	string	no
observers	number	no
writers	number	no
owner	string	no	Exclusive writer owner when mode is exclusive.
phase	string	no	Interaction phase. state remains the TCP lifecycle.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "session_id": "sess-7f3a",
  "node": "n_1",
  "name": "R1",
  "console_type": "telnet",
  "mode": "interact",
  "state": "open",
  "observers": 1,
  "writers": 1
}

Processing the result¶

Typical field access after a successful call:

const sess = await client.createConsoleSession({ ...packed, node: "n_1", mode: "interact" });

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.createConsoleSession({ lab, manifest, yaml, files });

listConsoleSessions¶

Family: Console

Purpose¶

Lists the console sessions the agent currently holds.

Mental model¶

Which console sessions are open?

Use when¶

• finding a session id

Reads¶

• agent console sessions

Changes¶

Nothing. Read-only.

Related¶

• getConsoleSession
• closeConsoleSession

Signature¶

listConsoleSessions(body: ConsolePayload, timeoutMs?: number): Promise<ConsoleSessionListData>

• HTTP: POST /api/v1/console/sessions/list
• operationId: listConsoleSessions
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	ConsolePayload	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: ConsolePayload¶

This request type is the same wire shape as ConsolePayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
manifest	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	string	no
commands	Array	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	number	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	Array<ConsoleTarget>	no
session_id	string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq	number	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	string	no	Go regexp for waitConsole.
max_bytes	number	no	Bounded history tail for getConsoleHistory.
steps	Array<ConsoleRunStep>	no
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ConsoleSessionListData

Field	TypeScript type	Required	Semantics
sessions	Array<ConsoleSessionData>	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "sessions": [
    {
      "session_id": "sess-7f3a",
      "node": "n_1",
      "mode": "interact",
      "state": "open"
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

const listed = await client.listConsoleSessions(packed);

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.listConsoleSessions({ lab, manifest, yaml, files });

getConsoleSession¶

Family: Console

Purpose¶

Returns one console session by id.

Mental model¶

Is this console session still here?

Use when¶

• checking one session before reuse

Reads¶

• that console session

Changes¶

Nothing. Read-only.

Related¶

• listConsoleSessions

Signature¶

getConsoleSession(body: ConsolePayload, timeoutMs?: number): Promise<ConsoleSessionData>

• HTTP: POST /api/v1/console/sessions/get
• operationId: getConsoleSession
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	ConsolePayload	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: ConsolePayload¶

This request type is the same wire shape as ConsolePayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
manifest	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	string	no
commands	Array	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	number	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	Array<ConsoleTarget>	no
session_id	string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq	number	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	string	no	Go regexp for waitConsole.
max_bytes	number	no	Bounded history tail for getConsoleHistory.
steps	Array<ConsoleRunStep>	no
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ConsoleSessionData

Field	TypeScript type	Required	Semantics
session_id	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
name	string	no
console_type	string	no
mode	ConsoleWriteMode	no
state	"idle"	"connecting"	"open"
created_at	string	no
last_activity	string	no
observers	number	no
writers	number	no
owner	string	no	Exclusive writer owner when mode is exclusive.
phase	string	no	Interaction phase. state remains the TCP lifecycle.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "session_id": "sess-7f3a",
  "node": "n_1",
  "mode": "exclusive",
  "state": "open",
  "owner": "agent-session-1",
  "writers": 1
}

Processing the result¶

Typical field access after a successful call:

const sess = await client.getConsoleSession({ ...packed, session_id: "sess-7f3a" });

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.getConsoleSession({ lab, manifest, yaml, files });

closeConsoleSession¶

Family: Console

Purpose¶

Closes one console session.

Mental model¶

Release this console.

Use when¶

• dropping a session you no longer need

Reads¶

• that console session

Changes¶

Closes the session.

Related¶

• createConsoleSession

Signature¶

closeConsoleSession(body: ConsolePayload, timeoutMs?: number): Promise<ConsoleSessionData>

• HTTP: POST /api/v1/console/sessions/close
• operationId: closeConsoleSession
• Authentication: Bearer token required
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	ConsolePayload	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: ConsolePayload¶

This request type is the same wire shape as ConsolePayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
manifest	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	string	no
commands	Array	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	number	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	Array<ConsoleTarget>	no
session_id	string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq	number	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	string	no	Go regexp for waitConsole.
max_bytes	number	no	Bounded history tail for getConsoleHistory.
steps	Array<ConsoleRunStep>	no
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ConsoleSessionData

Field	TypeScript type	Required	Semantics
session_id	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
name	string	no
console_type	string	no
mode	ConsoleWriteMode	no
state	"idle"	"connecting"	"open"
created_at	string	no
last_activity	string	no
observers	number	no
writers	number	no
owner	string	no	Exclusive writer owner when mode is exclusive.
phase	string	no	Interaction phase. state remains the TCP lifecycle.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "session_id": "sess-7f3a",
  "node": "n_1",
  "state": "closed"
}

Processing the result¶

Typical field access after a successful call:

const closed = await client.closeConsoleSession({ ...packed, session_id: "sess-7f3a" });

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.closeConsoleSession({ lab, manifest, yaml, files });

getConsoleHistory¶

Family: Console

Purpose¶

Returns the recent bytes the console session has already received. It is not the result of a new command.

Mental model¶

What did this console already print?

Use when¶

• reading the tail of a session

Do not use when¶

• you want to send a command; use execConsole

Reads¶

• the session receive ring

Changes¶

Nothing. Read-only.

Important semantics¶

• Bounded tail of the Hub ring (max 65536 bytes). end_seq is the newest retained receive sequence. after_seq returns only newer bytes and sets truncated when that sequence has left the ring. History is not the current command result.

Related¶

• execConsole
• waitConsole

Signature¶

getConsoleHistory(body: ConsolePayload, timeoutMs?: number): Promise<ConsoleHistoryData>

• HTTP: POST /api/v1/console/history
• operationId: getConsoleHistory
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	ConsolePayload	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: ConsolePayload¶

This request type is the same wire shape as ConsolePayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
manifest	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	string	no
commands	Array	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	number	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	Array<ConsoleTarget>	no
session_id	string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq	number	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	string	no	Go regexp for waitConsole.
max_bytes	number	no	Bounded history tail for getConsoleHistory.
steps	Array<ConsoleRunStep>	no
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ConsoleHistoryData

Field	TypeScript type	Required	Semantics
session_id	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
text	string	no	Bounded raw console tail (UTF-8 interpretation).
truncated	boolean	no
byte_count	number	no
available_bytes	number	no	Bytes retained in the Hub ring (max 65536).
end_seq	number	no	Receive sequence of the newest byte retained in the ring.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Ephemeral Hub ring tail only; not persistent audit history.

{
  "session_id": "sess-7f3a",
  "node": "n_1",
  "text": "Router>enable\\nRouter#",
  "truncated": false,
  "byte_count": 18,
  "available_bytes": 18
}

Processing the result¶

Typical field access after a successful call:

const hist = await client.getConsoleHistory({ ...packed, session_id: "sess-7f3a" });

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.getConsoleHistory({ lab, manifest, yaml, files });

waitConsole¶

Family: Console

Purpose¶

Waits until the console output matches a regular expression, or until the wait times out.

Mental model¶

Tell me when the console prints this.

Use when¶

• waiting for a prompt or a banner

Do not use when¶

• you also need to send text; use runConsole

Reads¶

• the console session output

Changes¶

Blocks on the session until the pattern matches, the wait times out, or the call is cancelled.

Important semantics¶

• Go regexp pattern; max timeout_ms 600000; timed_out distinguishable from cancel.

Related¶

• runConsole
• getConsoleHistory

Signature¶

waitConsole(body: ConsolePayload, timeoutMs?: number): Promise<ConsoleWaitData>

• HTTP: POST /api/v1/console/wait
• operationId: waitConsole
• Authentication: Bearer token required
• Default timeout: 615000 ms

Parameters¶

Parameter	Type	Required	Description
body	ConsolePayload	yes	Request body.
timeoutMs	number	no	Override the 615000 ms default.

Request schema: ConsolePayload¶

This request type is the same wire shape as ConsolePayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
manifest	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	string	no
commands	Array	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	number	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	Array<ConsoleTarget>	no
session_id	string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq	number	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	string	no	Go regexp for waitConsole.
max_bytes	number	no	Bounded history tail for getConsoleHistory.
steps	Array<ConsoleRunStep>	no
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ConsoleWaitData

Field	TypeScript type	Required	Semantics
session_id	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
matched	boolean	no
match	string	no
text	string	no	Matched snippet.
duration_ms	number	no
timed_out	boolean	no
truncated	boolean	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "session_id": "sess-7f3a",
  "node": "n_1",
  "matched": true,
  "match": "Router#",
  "text": "Router#",
  "duration_ms": 42,
  "timed_out": false,
  "truncated": false
}

Processing the result¶

Typical field access after a successful call:

const waited = await client.waitConsole({ ...packed, node: "n_1", pattern: "Router#", timeout_ms: 30000 });

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.waitConsole({ lab, manifest, yaml, files });

runConsole¶

Family: Console

Purpose¶

Runs an ordered expect and send script on one console. Use execConsole for a single command.

Mental model¶

Play this dialogue on the console.

Use when¶

• a multi-step console dialogue

Do not use when¶

• a single show, ping, or traceroute; use execConsole

Reads¶

• the console session

Changes¶

Sends the script's bytes and records the transcript of this run.

Important semantics¶

• Interactive expect/send on the Hub. An expect after send matches only bytes received after that send. Transcript is this run. Not the path for a single show, ping, or traceroute. failed_step is 0-based; send_secret redacted; max timeout_ms 600000.

Related¶

• execConsole
• waitConsole

Signature¶

runConsole(body: ConsolePayload, timeoutMs?: number): Promise<ConsoleRunData>

• HTTP: POST /api/v1/console/run
• operationId: runConsole
• Authentication: Bearer token required
• Default timeout: 615000 ms

Parameters¶

Parameter	Type	Required	Description
body	ConsolePayload	yes	Request body.
timeoutMs	number	no	Override the 615000 ms default.

Request schema: ConsolePayload¶

This request type is the same wire shape as ConsolePayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
manifest	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	string	no
commands	Array	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	number	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	Array<ConsoleTarget>	no
session_id	string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq	number	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	string	no	Go regexp for waitConsole.
max_bytes	number	no	Bounded history tail for getConsoleHistory.
steps	Array<ConsoleRunStep>	no
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ConsoleRunData

Field	TypeScript type	Required	Semantics
session_id	string	no
ok	boolean	no
failed_step	number	no	0-based failed step index; -1 when ok.
steps	Array<ConsoleRunStepResult>	no
transcript	string	no	Bytes received after the sends in this run, up to the completing match.
truncated	boolean	no
duration_ms	number	no
prompt	string	no
phase	string	no
rx_to	number	no
recovered	boolean	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

send_secret values appear as ******** in sent/transcript; never include real secrets in samples.

{
  "session_id": "sess-7f3a",
  "ok": true,
  "failed_step": -1,
  "duration_ms": 120,
  "truncated": false,
  "transcript": "Press RETURN to get started\\nRouter>enable\\nRouter#",
  "steps": [
    {
      "index": 0,
      "expect": "Press RETURN",
      "sent": "",
      "matched": "Press RETURN",
      "duration_ms": 10
    },
    {
      "index": 1,
      "expect": "Router>",
      "sent": "enable",
      "matched": "Router>",
      "duration_ms": 15
    },
    {
      "index": 2,
      "expect": "Router#",
      "sent": "********",
      "matched": "Router#",
      "duration_ms": 12
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

const ran = await client.runConsole({ ...packed, node: "n_1", steps: [{ expect: "Router#" }] });

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.runConsole({ lab, manifest, yaml, files });

attachConsole¶

Family: Console

Purpose¶

Returns a ticket for an interactive or read-only console stream. Omitted mode is interact.

Mental model¶

Attach me to this console.

Use when¶

• opening a terminal
• watching a console without writing

Do not use when¶

• you only need one command result; use execConsole

Reads¶

• the node console

Changes¶

Opens or joins a console session and issues a stream ticket.

Important semantics¶

• Omitted mode is interact. Optional session_id joins or creates Hub-backed stream context. Ticket/stream semantics unchanged.

Related¶

• streamConsole
• execConsole

Signature¶

attachConsole(body: ConsolePayload, timeoutMs?: number): Promise<ConsoleAttachData>

• HTTP: POST /api/v1/console/attach
• operationId: attachConsole
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	ConsolePayload	yes	Request body.
timeoutMs	number	no	Override the 30000 ms default.

Request schema: ConsolePayload¶

This request type is the same wire shape as ConsolePayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
manifest	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	string	no
commands	Array	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	number	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	Array<ConsoleTarget>	no
session_id	string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq	number	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	string	no	Go regexp for waitConsole.
max_bytes	number	no	Bounded history tail for getConsoleHistory.
steps	Array<ConsoleRunStep>	no
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

ConsoleAttachData

Field	TypeScript type	Required	Semantics
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
name	string	no
console_type	string	no
stream	string	no
transport	"eve-telnet"	no
session_id	string	no
mode	ConsoleWriteMode	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Omitted mode is interact. stream is a relative ticket path; success streamConsole uses 101 eve-telnet.

{
  "node": "n_1",
  "name": "R1",
  "console_type": "telnet",
  "stream": "/api/v1/console/stream/abc123",
  "transport": "eve-telnet",
  "mode": "interact"
}

Processing the result¶

Typical field access after a successful call:

const attached = await client.attachConsole({ ...packed, node: "n_1" });

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
browser_token_invalid	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport

Example¶

const attached = await client.attachConsole({ lab, node: "n_1" });

streamConsole¶

Family: Console

Purpose¶

Upgrades a console ticket to the raw console byte stream.

Mental model¶

Give me the console bytes.

Use when¶

• attaching a terminal after attachConsole

Reads¶

• the console ticket

Changes¶

Opens a byte stream. Writes on that stream go to the console when the session mode allows them.

Related¶

• attachConsole

Signature¶

streamConsole(ticket: string, timeoutMs?: number): Promise<import("node:net").Socket>

• HTTP: GET /api/v1/console/stream/{ticket}
• operationId: streamConsole
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Success is HTTP 101 Switching Protocols, not a JSON envelope

Parameters¶

Parameter	Type	Required	Description
ticket	string	yes	Path parameter
timeoutMs	number	no	Override the 15000 ms default.

Returns¶

Promise<net.Socket> — upgraded telnet byte stream.

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
browser_token_invalid	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport

Example¶

const sock = await client.streamConsole(ticket);

streamTraffic¶

Family: Capture

Purpose¶

Upgrades a traffic ticket to the byte stream of translated lab traffic.

Mental model¶

Stream the traffic bytes.

Use when¶

• reading the traffic socket after attachTraffic

Reads¶

• the traffic ticket

Changes¶

Opens a stream. It does not change the lab.

Related¶

• attachTraffic

How-to¶

• Use traffic filters

Signature¶

streamTraffic(ticket: string, timeoutMs?: number): Promise<import("node:net").Socket>

• HTTP: GET /api/v1/projects/traffic/stream/{ticket}
• operationId: streamTraffic
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Success is HTTP 101 Switching Protocols, not a JSON envelope

Parameters¶

Parameter	Type	Required	Description
ticket	string	yes	Path parameter
timeoutMs	number	no	Override the 15000 ms default.

Returns¶

Promise<net.Socket> — upgraded telnet byte stream.

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
browser_token_invalid	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport

Example¶

const sock = await client.streamTraffic(ticket);

startOob¶

Family: Console

Purpose¶

Starts the OOB SSH generation for this authenticated session and runtime project, or returns it unchanged when it is already active.

Mental model¶

Open out-of-band SSH for this lab.

Use when¶

• preparing SSH access through the console hub

Do not use when¶

• you only need a browser console; use attachConsole

Reads¶

• the authenticated session and the runtime project

Changes¶

Creates the generation when it was off. Does not attach the hub.

Important semantics¶

• OFF mints one generation. ACTIVE in the same session and project returns that generation and does not rotate keys or drop live SSH.

Related¶

• getOobStatus
• getOobCredentials
• openOob
• stopOob

Signature¶

startOob(body: ProjectPayload, timeoutMs?: number): Promise<OobStatusData>

• HTTP: POST /api/v1/oob/start
• operationId: startOob
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 30000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

OobStatusData

Field	TypeScript type	Required	Semantics
active	boolean	no
username	string	no	SSH username. Always eve-oob while active. HTTP does not authenticate this name.
user_public_key	string	no
host_public_key	string	no
host_fingerprint	string	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.startOob({ lab, manifest, yaml, files });

getOobStatus¶

Family: Console

Purpose¶

Reports whether this session has an active OOB generation for the runtime project.

Mental model¶

Is out-of-band SSH on?

Use when¶

• checking the generation before materializing files

Reads¶

• the OOB generation for this session and project

Changes¶

Nothing. Read-only.

Related¶

• startOob
• getOobCredentials

Signature¶

getOobStatus(body: ProjectPayload, timeoutMs?: number): Promise<OobStatusData>

• HTTP: POST /api/v1/oob/status
• operationId: getOobStatus
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

OobStatusData

Field	TypeScript type	Required	Semantics
active	boolean	no
username	string	no	SSH username. Always eve-oob while active. HTTP does not authenticate this name.
user_public_key	string	no
host_public_key	string	no
host_fingerprint	string	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.getOobStatus({ lab, manifest, yaml, files });

getOobCredentials¶

Family: Console

Purpose¶

Returns the SSH user key, host public key, fingerprint, known_hosts line, and node snapshot for the active generation.

Mental model¶

Give me the SSH material for this generation.

Use when¶

• writing the project-local OOB runtime files

Do not use when¶

• the generation is inactive

Reads¶

• the generation keys and the current node catalogue

Changes¶

Nothing. Does not rotate keys.

Important semantics¶

• Inactive is oob_inactive, not an empty object. known_hosts may grow with the catalogue. Keys stay stable until stop.

Related¶

• startOob
• openOob

Signature¶

getOobCredentials(body: ProjectPayload, timeoutMs?: number): Promise<OobCredentialsData>

• HTTP: POST /api/v1/oob/credentials
• operationId: getOobCredentials
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 30000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

OobCredentialsData

Field	TypeScript type	Required	Semantics
username	string	no
user_private_key	string	no
user_public_key	string	no
host_public_key	string	no
host_fingerprint	string	no
known_hosts	string	no
nodes	Array<OobNode>	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
oob_inactive	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.getOobCredentials({ lab, manifest, yaml, files });

stopOob¶

Family: Console

Purpose¶

Destroys the OOB generation for this session and project and closes its SSH sessions.

Mental model¶

Turn out-of-band SSH off.

Use when¶

• revoking the current generation

Reads¶

• the OOB generation

Changes¶

Closes live SSH, destroys keys, and invalidates tickets. Already off stays off.

Related¶

• startOob

Signature¶

stopOob(body: ProjectPayload, timeoutMs?: number): Promise<OobStatusData>

• HTTP: POST /api/v1/oob/stop
• operationId: stopOob
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 30000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

OobStatusData

Field	TypeScript type	Required	Semantics
active	boolean	no
username	string	no	SSH username. Always eve-oob while active. HTTP does not authenticate this name.
user_public_key	string	no
host_public_key	string	no
host_fingerprint	string	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.stopOob({ lab, manifest, yaml, files });

openOob¶

Family: Console

Purpose¶

Issues a one-shot ticket for one catalogue node in the active generation.

Mental model¶

Give me a ticket for this node's SSH stream.

Use when¶

• the ProxyCommand is about to open the SSH byte stream

Do not use when¶

• you want the console hub attached before SSH authentication

Reads¶

• the generation and the node catalogue

Changes¶

Stores a 30s single-use ticket. Does not dial Telnet.

Important semantics¶

• Ticket only. Does not attach the hub. HTTP does not read the SSH username.

Related¶

• streamOob
• startOob

Signature¶

openOob(body: ProjectPayload, timeoutMs?: number): Promise<OobOpenData>

• HTTP: POST /api/v1/oob/open
• operationId: openOob
• Authentication: Bearer token required
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	ProjectPayload	yes	Request body.
timeoutMs	number	no	Override the 15000 ms default.

Request schema: ProjectPayload¶

This request type is the same wire shape as ProjectPayload.

Field	TypeScript type	Required	Semantics
lab	string	no
yaml	string	no
files	Record	no
state	unknown	no
source	unknown	no
manifest	string	no
prune	boolean	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe	boolean	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	string	no
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	Array	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	number	no
stopmode	number	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh	boolean	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	boolean	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction	string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm	boolean	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file	string	no	getPublicProject only. topology or presentation. Omitted = topology.
path	string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir	string	no	Rejected when non-empty.
out	string	no	Rejected when non-empty.

Returns¶

OobOpenData

Field	TypeScript type	Required	Semantics
node	string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
ticket	string	no	64-char lowercase hex. Single use. 30s TTL. Bound to this session, project, node, and generation.
stream	string	no	GET path for Upgrade: eve-oob.

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
oob_inactive	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

const result = await client.openOob({ lab, manifest, yaml, files });

streamOob¶

Family: Console

Purpose¶

Upgrades an OOB ticket to the raw SSH byte stream. The hub attaches only after a later shell request.

Mental model¶

Give me the SSH bytes.

Use when¶

• splicing OpenSSH through the ProxyCommand

Reads¶

• the OOB ticket

Changes¶

Opens a raw SSH stream. Does not attach the hub by itself.

Related¶

• openOob

Signature¶

streamOob(ticket: string, timeoutMs?: number): Promise<import("node:net").Socket>

• HTTP: GET /api/v1/oob/stream/{ticket}
• operationId: streamOob
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Success is HTTP 101 Switching Protocols, not a JSON envelope

Parameters¶

Parameter	Type	Required	Description
ticket	string	yes	Path parameter
timeoutMs	number	no	Override the 15000 ms default.

Returns¶

Promise<net.Socket> — upgraded telnet byte stream.

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
browser_token_invalid	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport
oob_inactive	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport

Example¶

const result = await client.streamOob();