Python API reference¶

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

Public methods on EveIacClient. Import models from eveiac.

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.

Omitted optional fields use UNSET (or are left off a mapping) and are not serialized. None is JSON null. False, 0, and "" are explicit values.

Pass timeout_ms to override the operation timeout from semantics. None uses the operation default.

Connection / Authentication¶

get_health¶

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¶

get_health(
    timeout_ms: int | None = None
) -> HealthData

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

Parameters¶

Parameter	Type	Required	Description
timeout_ms	int \| None	no	Override the 15000 ms default.

Returns¶

HealthData

Field	Python type	Required	Semantics
status	str	no
tls	bool	no
version	str	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:

health = client.get_health()
if health.status != "ok":
    raise SystemExit(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¶

health = client.get_health()
print(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 | Mapping[str, Any],
    timeout_ms: int | None = None
) -> LoginData

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

Parameters¶

Parameter	Type	Required	Description
body	LoginRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: LoginRequest¶

LoginRequest is the same wire shape as LoginRequest.

Field	Python type	Required	Semantics
username	str	yes
password	str	yes

Returns¶

LoginData

Field	Python type	Required	Semantics
token	str	no
username	str	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:

session = client.login(LoginRequest(username="admin", password="secret"))
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¶

from eveiac import LoginRequest

session = client.login(LoginRequest(username="admin", password="secret"))
client = EveIacClient(url=url, token=session.token, ca_pem=ca_pem)

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 | Mapping[str, Any] | None = None,
    timeout_ms: int | None = None
) -> 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.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: LogoutRequest¶

LogoutRequest is the same wire shape as LogoutRequest.

No object fields (see type).

Returns¶

StatusOkData

Field	Python type	Required	Semantics
status	str	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¶

client.logout()

get_session¶

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¶

get_session(
    timeout_ms: int | None = None
) -> 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
timeout_ms	int \| None	no	Override the 15000 ms default.

Returns¶

SessionData

Field	Python type	Required	Semantics
username	str	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:

session = client.get_session()
assert 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¶

session = client.get_session()

get_capabilities¶

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¶

get_capabilities(
    timeout_ms: int | None = None
) -> 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
timeout_ms	int \| None	no	Override the 15000 ms default.

Returns¶

CapabilitiesData

Field	Python type	Required	Semantics
eveReachable	bool	no
eveBaseUrl	str	no
features	dict[str, bool]	no
projectModes	dict[str, ProjectModeCaps]	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:

caps = client.get_capabilities()
assert caps.eve_reachable

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¶

caps = client.get_capabilities()

Templates / Metadata¶

get_public_schema¶

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¶

get_public_schema(
    body: GetPublicSchemaRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> 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	GetPublicSchemaRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: GetPublicSchemaRequest¶

GetPublicSchemaRequest is the same wire shape as SchemaRequest.

Field	Python type	Required	Semantics
sections	list[Literal["nodes", "networks", "links", "traffic_filters", "tasks", "configsets"]]	yes

Returns¶

SchemaData

Field	Python type	Required	Semantics
revision	str	yes	Lowercase hex SHA-256 of the exact embedded canonical schema bytes. Same value for every fragment in the response.
sections	Mapping[str, Any]	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:

schema = client.get_public_schema(SchemaRequest(sections=["traffic_filters", "tasks"]))
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¶

result = client.get_public_schema()

list_templates¶

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¶

list_templates(
    query: ListTemplatesQuery | Mapping[str, Any] | None = None,
    timeout_ms: int | None = None
) -> 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 \| Mapping \| None)	no	Query object. Omit the argument to send no query string.
timeout_ms	int \| None	no	Override the 15000 ms default.

Query schema: ListTemplatesQuery¶

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

Returns¶

TemplatesData

Field	Python type	Required	Semantics
templates	list[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:

data = client.list_templates()
ids = [t.id for t in (data.templates or []) if t.id]

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¶

from eveiac import ListTemplatesQuery

templates = client.list_templates()
provisioned = client.list_templates(ListTemplatesQuery(provisioned="true"))

get_template_catalog¶

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¶

get_template_catalog(
    timeout_ms: int | None = None
) -> 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
timeout_ms	int \| None	no	Override the 15000 ms default.

Returns¶

TemplateCatalogData

Field	Python type	Required	Semantics
templates	dict[str, TemplateFamily]	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¶

result = client.get_template_catalog()

get_template¶

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¶

get_template(
    id: str,
    timeout_ms: int | None = None
) -> 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	str	yes	Path parameter
timeout_ms	int \| None	no	Override the 15000 ms default.

Returns¶

TemplateDetail

Field	Python type	Required	Semantics
id	str	no
description	str	no
type	str	no
provisioned	bool	no
configSupported	bool	no
icon	str	no
images	list[TemplateImage]	no
default	str	no
image_requirement	Literal["required", "optional", "not_applicable"]	no
attributes	list[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:

detail = client.get_template("iol")
print(detail.default)

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¶

detail = client.get_template("iol")

list_template_images¶

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¶

list_template_images(
    id: str,
    timeout_ms: int | None = None
) -> 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	str	yes	Path parameter
timeout_ms	int \| None	no	Override the 15000 ms default.

Returns¶

TemplateImagesData

Field	Python type	Required	Semantics
template	str	no
type	str	no
provisioned	bool	no
default	str	no
images	list[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¶

data = client.list_template_images("iol")

list_template_attributes¶

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¶

list_template_attributes(
    id: str,
    timeout_ms: int | None = None
) -> 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	str	yes	Path parameter
timeout_ms	int \| None	no	Override the 15000 ms default.

Returns¶

TemplateAttributesData

Field	Python type	Required	Semantics
template	str	no
type	str	no
attributes	list[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¶

data = client.list_template_attributes("iol")

list_network_types¶

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¶

list_network_types(
    timeout_ms: int | None = None
) -> 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
timeout_ms	int \| None	no	Override the 15000 ms default.

Returns¶

NetworkTypesData

Field	Python type	Required	Semantics
types	list[NetworkType]	no
natOnly	bool	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¶

result = client.list_network_types()

get_network_authoring¶

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¶

get_network_authoring(
    id: str,
    timeout_ms: int | None = None
) -> 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	str	yes	Path parameter
timeout_ms	int \| None	no	Override the 15000 ms default.

Returns¶

NetworkAuthoring

Field	Python type	Required	Semantics
id	str	no
label	str	no
icon	str	no
supported	bool	no
attributes	list[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:

data = client.get_network_authoring("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¶

data = client.get_network_authoring("bridge")

list_icons¶

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¶

list_icons(
    timeout_ms: int | None = None
) -> 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
timeout_ms	int \| None	no	Override the 15000 ms default.

Returns¶

IconsData

Field	Python type	Required	Semantics
icons	list[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¶

result = client.list_icons()

list_folders¶

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¶

list_folders(
    query: ListFoldersQuery | Mapping[str, Any] | None = None,
    timeout_ms: int | None = None
) -> 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 \| Mapping \| None)	no	Query object. Omit the argument to send no query string.
timeout_ms	int \| None	no	Override the 15000 ms default.

Query schema: ListFoldersQuery¶

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

Returns¶

FoldersData

Field	Python type	Required	Semantics
path	str	no
parent	str	no	Parent folder path. Empty at labs root.
folders	list[FolderEntry]	no
labs	list[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:

from eveiac import ListFoldersQuery
root = client.list_folders()
nested = client.list_folders(ListFoldersQuery(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¶

from eveiac import ListFoldersQuery

root = client.list_folders()
nested = client.list_folders(ListFoldersQuery(path="/Customers"))

get_authoring_icons_zip¶

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¶

get_authoring_icons_zip(
    timeout_ms: int | None = None
) -> Any

• 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
timeout_ms	int \| None	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¶

result = client.get_authoring_icons_zip()

get_authoring_revision¶

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¶

get_authoring_revision(
    timeout_ms: int | None = None
) -> 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
timeout_ms	int \| None	no	Override the 0 ms default.

Returns¶

AuthoringRevisionData

Field	Python type	Required	Semantics
revision	str	yes
iconsRevision	str	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¶

result = client.get_authoring_revision()

get_authoring_snapshot¶

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¶

get_authoring_snapshot(
    timeout_ms: int | None = None
) -> 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
timeout_ms	int \| None	no	Override the 0 ms default.

Returns¶

AuthoringSnapshotData

Field	Python type	Required	Semantics
revision	str	yes
templates	list[TemplateDetail]	yes
catalog	TemplateCatalogData	yes
networkTypes	NetworkTypesData	yes
networks	list[NetworkAuthoring]	yes
icons	list[Icon]	yes
netIcons	list[Icon]	yes
cluster	list[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¶

result = client.get_authoring_snapshot()

complete_link_interfaces¶

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¶

complete_link_interfaces(
    body: CompleteLinkInterfacesRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> 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	CompleteLinkInterfacesRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: CompleteLinkInterfacesRequest¶

CompleteLinkInterfacesRequest is the same wire shape as AuthoringPayload.

Field	Python type	Required	Semantics
dir	str	no	Rejected when non-empty.
yaml	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
template	str	no
attributes	Mapping[str, Any]	no
excludeUsed	bool	no
eth_format	str	no

Returns¶

InterfacesData

Field	Python type	Required	Semantics
source	Literal["template", "node"]	no	Whether this result is a template preview or an existing IaC node.
template	str	no	Canonical resolved template id.
node	str	no	IaC node key when source=node. omitted: all nodes. empty string: all nodes. named: that IaC node key
items	list[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:

data = client.complete_link_interfaces({"yaml": yaml, "node": "core_r1"})
assert data.source == "node"
assert data.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¶

from eveiac import CompleteLinkInterfacesRequest

data = client.complete_link_interfaces(CompleteLinkInterfacesRequest(template="iol"))

preview_interfaces¶

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¶

preview_interfaces(
    body: PreviewInterfacesRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> 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	PreviewInterfacesRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: PreviewInterfacesRequest¶

PreviewInterfacesRequest is the same wire shape as AuthoringPayload.

Field	Python type	Required	Semantics
dir	str	no	Rejected when non-empty.
yaml	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
template	str	no
attributes	Mapping[str, Any]	no
excludeUsed	bool	no
eth_format	str	no

Returns¶

InterfacesData

Field	Python type	Required	Semantics
source	Literal["template", "node"]	no	Whether this result is a template preview or an existing IaC node.
template	str	no	Canonical resolved template id.
node	str	no	IaC node key when source=node. omitted: all nodes. empty string: all nodes. named: that IaC node key
items	list[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:

data = client.preview_interfaces({"template": "ceos"})
assert data.source == "template"
assert data.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¶

from eveiac import PreviewInterfacesRequest

data = client.preview_interfaces(PreviewInterfacesRequest(template="iol"))

Projects¶

validate_project¶

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¶

validate_project(
    body: ValidateProjectRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> 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	ValidateProjectRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: ValidateProjectRequest¶

ValidateProjectRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ValidateData

Field	Python type	Required	Semantics
valid	bool	yes
errors	list[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:

from eveiac import ValidateProjectRequest, pack_lab
packed = pack_lab("./lab")
result = client.validate_project(ValidateProjectRequest(**packed.payload))
assert result.valid is 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
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¶

from eveiac import ValidateProjectRequest, pack_lab

packed = pack_lab("./my-lab")
result = client.validate_project(ValidateProjectRequest(**packed.payload))

import_project¶

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¶

import_project(
    body: ImportProjectRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> ImportData

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

Parameters¶

Parameter	Type	Required	Description
body	ImportProjectRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 300000 ms default.

Request schema: ImportProjectRequest¶

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	Python type	Required	Semantics
lab	str	yes
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ImportData

Field	Python type	Required	Semantics
name	str	no
yaml	str	no
files	dict[str, str]	no
mode	str	no
source_lab	str	no
managed_lab	str	no
lab	str	no
state	Any	no
source	Any	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:

imported = client.import_project(ImportProjectRequest(**packed.payload))
managed = imported.managed_lab or imported.lab
state = imported.state  # persist to .eve-iac-state.json

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¶

from eveiac import ImportProjectRequest, pack_lab

packed = pack_lab("./imported-lab")
imported = client.import_project(ImportProjectRequest(**packed.payload))
# Import writes IaC intent. It does not deploy. It is not reconcile from_eve.

plan_project¶

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¶

plan_project(
    body: PlanProjectRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> 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	PlanProjectRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 180000 ms default.

Request schema: PlanProjectRequest¶

PlanProjectRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

PlanData

Field	Python type	Required	Semantics
lab	str	no
exists	bool	no
summary	PlanSummary	no
operations	list[PlanAction]	no
actions	list[PlanAction]	no
applicable	bool	no
blocked	list[PlanAction]	no
text	str	no
plan_identity	str	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	bool	no
lock	int	no
direction	str	no	omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
unsupported	list[str]	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:

plan = client.plan_project(PlanProjectRequest(**packed.payload))
# applicable is summary-only; do not gate reconcile on it
identity = plan.plan_identity  # pass to confirm=true reconcile

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¶

from eveiac import PlanProjectRequest, pack_lab

packed = pack_lab("./my-lab")
result = client.plan_project(PlanProjectRequest(**packed.payload))

deploy_project¶

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¶

deploy_project(
    body: DeployProjectRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> DeployData

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

Parameters¶

Parameter	Type	Required	Description
body	DeployProjectRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 300000 ms default.

Request schema: DeployProjectRequest¶

DeployProjectRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

DeployData

Field	Python type	Required	Semantics
lab	str	no
nodes	int	no
links	int	no
state	Any	no
unsupported	list[str]	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:

deployed = client.deploy_project(DeployProjectRequest(**packed.payload))
lab = 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¶

from eveiac import DeployProjectRequest, pack_lab

packed = pack_lab("./my-lab")
result = client.deploy_project(DeployProjectRequest(**packed.payload))

reconcile_project¶

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¶

reconcile_project(
    body: ReconcileProjectRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> ReconcileData

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

Parameters¶

Parameter	Type	Required	Description
body	ReconcileProjectRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 300000 ms default.

Request schema: ReconcileProjectRequest¶

ReconcileProjectRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ReconcileData

Field	Python type	Required	Semantics
lab	str	no
direction	str	no	omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
status	Literal["converged", "partial", "pending_stop", "failed"]	no
applied	int	no
skippedPrune	int	no
fullDeploy	bool	no
applicable	bool	no	Summary only: full immediate convergence is possible (no requires_stop, no unsupported, not locked). Must not gate execution.
desired_updated	bool	no
live	Mapping[str, Any]	no
requires_stop	Mapping[str, Any]	no
unsupported	Mapping[str, Any]	no	Object {changes, messages} on reconcile. Plan still uses string[].
runtime	Mapping[str, Any]	no
summary	PlanSummary	no
operations	list[PlanAction]	no	The plan that was considered. Classification is not proof that a call was sent.
executed	list[ReconcileStep]	no	Side effects this reconcile actually performed or refused. effect is applied, failed, skipped, or pending_stop.
text	str	no	Human-readable execution report. Same facts as executed.
blocked	list[PlanAction]	no
plan_identity	str	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	Any	no
yaml	str	no
files	dict[str, str]	no
source	Any	no
manifest	str	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:

result = client.reconcile_project(ReconcileProjectRequest(**{**packed.payload, "plan_identity": identity}))
print(result.status, result.applied)
# remaining requires_stop: confirm=True AND matching plan_identity; --yes does not invent it

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¶

from eveiac import ReconcileProjectRequest, pack_lab

packed = pack_lab("./my-lab")
applied = client.reconcile_project(ReconcileProjectRequest(**{**packed.payload, "direction": "to_eve"}))
pulled = client.reconcile_project(ReconcileProjectRequest(**{**packed.payload, "direction": "from_eve"}))
# to_eve makes EVE match IaC intent. from_eve makes the UNL definition the new intent.

destroy_project¶

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¶

destroy_project(
    body: DestroyProjectRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> DestroyData

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

Parameters¶

Parameter	Type	Required	Description
body	DestroyProjectRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 180000 ms default.

Request schema: DestroyProjectRequest¶

DestroyProjectRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

DestroyData

Field	Python type	Required	Semantics
lab	str	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:

client.destroy_project(DestroyProjectRequest(**packed.payload))

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¶

from eveiac import DestroyProjectRequest, pack_lab

packed = pack_lab("./my-lab")
result = client.destroy_project(DestroyProjectRequest(**packed.payload))

get_project_status¶

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¶

get_project_status(
    body: GetProjectStatusRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> 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	GetProjectStatusRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: GetProjectStatusRequest¶

GetProjectStatusRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ProjectStatusData

Field	Python type	Required	Semantics
mode	str	no
source_lab	str	None	no
managed_lab	str	None	no
runtime_lab	str	None	no
capabilities	ProjectModeCaps	no
locked	bool	no
lock	int	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:

status = client.get_project_status(GetProjectStatusRequest(**packed.payload))
assert 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¶

from eveiac import GetProjectStatusRequest, pack_lab

packed = pack_lab("./my-lab")
status = client.get_project_status(GetProjectStatusRequest(**packed.payload))
live = getattr(status, "live", None)
if getattr(live, "available", None) is True:
    for node in getattr(live, "nodes", None) or []:
        print(f"{getattr(node, 'key', '')}: {getattr(node, 'state_label', '')}")

inspect_project¶

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¶

inspect_project(
    body: InspectProjectRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> 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	InspectProjectRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 300000 ms default.

Request schema: InspectProjectRequest¶

InspectProjectRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

InspectionData

Field	Python type	Required	Semantics
observation	bool	no
desired_state	bool	no
mode	str	no
source_lab	Any	no
managed_lab	Any	no
runtime_lab	str	no
capabilities	ProjectModeCaps	no
cached	bool	no
nodes	list[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:

data = client.inspect_project(InspectProjectRequest(**packed.payload))
lab = 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¶

from eveiac import InspectProjectRequest, pack_lab

packed = pack_lab("./my-lab")
observed = client.inspect_project(InspectProjectRequest(**{**packed.payload, "refresh": True}))
# Structural snapshot. Poll live node state with get_project_status.

get_public_project¶

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¶

get_public_project(
    body: GetPublicProjectRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> 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	GetPublicProjectRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: GetPublicProjectRequest¶

GetPublicProjectRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	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¶

from eveiac import GetPublicProjectRequest

topology = client.get_public_project(GetPublicProjectRequest(yaml=yaml, files=files, file="topology"))
# IaC intent. This does not read live EVE.

edit_project¶

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¶

edit_project(
    body: EditProjectRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> EditResult

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

Parameters¶

Parameter	Type	Required	Description
body	EditProjectRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: EditProjectRequest¶

EditProjectRequest is the same wire shape as EditRequest.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.
operations	list[EditOperation]	yes	Bounded canonical mutations applied as one in-memory transaction. Not RFC 6902 JSON Patch.

Returns¶

EditResult

Field	Python type	Required	Semantics
applied	bool	yes
operations	int	yes
changed	EditChanged	no
valid	bool	yes
errors	list[ValidationError]	yes
yaml	str	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	list[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:

edited = client.edit_project(EditProjectRequest(**{**packed.payload, "operations": ops}))
assert edited.applied is 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
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¶

result = client.edit_project()

get_project_config¶

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¶

get_project_config(
    body: GetProjectConfigRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> 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	GetProjectConfigRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: GetProjectConfigRequest¶

GetProjectConfigRequest is the same wire shape as ConfigReadRequest.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.
operation	Literal["index", "get", "search"]	yes	Discriminates the read. Not OpenAPI oneOf.
template	str	no	Exact template id filter for index/search.
present	bool	no	index only. true = blobs present, false = missing. Omitted = both.
query	str	no	search only. Literal substring. Required. Max 256 characters. Empty is invalid_request.
case_sensitive	bool	no	search only. Omitted = case-insensitive.
limit	int	no	search only. Total match hits, not configs. Omitted = 20. Max 50. No OpenAPI default.
context_lines	int	no	search only. Neighbor lines around each hit. Omitted = 0. Max 3. No OpenAPI default.

Returns¶

ConfigData

Field	Python type	Required	Semantics
lab	str	no
scope	Mapping[str, Any]	no
entries	dict[str, ConfigIndexEntry]	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
template	str	no
configset	str	no
present	bool	no
bytes	int	no
sha256	str	no
content	str	no
query	str	no
truncated	bool	no
results	dict[str, ConfigSearchNode]	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:

cfg = client.get_project_config(GetProjectConfigRequest(**{**packed.payload, "operation": "get", "node": "ceos1"}))
assert cfg.present is 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
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¶

result = client.get_project_config()

edit_project_config¶

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¶

edit_project_config(
    body: EditProjectConfigRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> ConfigEditData

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

Parameters¶

Parameter	Type	Required	Description
body	EditProjectConfigRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: EditProjectConfigRequest¶

EditProjectConfigRequest is the same wire shape as ConfigEditRequest.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.
operations	list[ConfigEditOp]	yes	Preflight all, then write. Not a multi-file transaction.

Returns¶

ConfigEditData

Field	Python type	Required	Semantics
lab	str	yes
applied	bool	yes
operations	int	yes
changed	dict[str, ConfigChanged]	yes
files	dict[str, str]	no	Changed blobs keyed by project-relative configs/ path. Persist sidecar. MCP strips this field.
yaml	str	no	Canonical topology.yml when configsets or node selectors changed. Persist sidecar. MCP strips this field.
deleted	list[str]	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:

edited = client.edit_project_config(EditProjectConfigRequest(**{**packed.payload, "operations": ops}))
assert edited.applied is 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
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¶

result = client.edit_project_config()

open_project¶

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¶

open_project(
    body: OpenProjectRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> 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	OpenProjectRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 30000 ms default.

Request schema: OpenProjectRequest¶

OpenProjectRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

OpenData

Field	Python type	Required	Semantics
url	str	no
ttl	int	no
lab	str	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:

opened = client.open_project(OpenProjectRequest(**packed.payload))
print(opened.url)

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¶

from eveiac import OpenProjectRequest, pack_lab

packed = pack_lab("./my-lab")
result = client.open_project(OpenProjectRequest(**packed.payload))

Execution / Consoles¶

list_project_consoles¶

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¶

list_project_consoles(
    body: ListProjectConsolesRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> 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	ListProjectConsolesRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 30000 ms default.

Request schema: ListProjectConsolesRequest¶

ListProjectConsolesRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ConsolesData

Field	Python type	Required	Semantics
lab	str	no
html5	bool	no
consoles	list[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:

consoles = client.list_project_consoles(ListProjectConsolesRequest(**packed.payload))
for c in consoles.consoles or []:
    print(c.node, c.port)

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¶

from eveiac import ListProjectConsolesRequest, pack_lab

packed = pack_lab("./my-lab")
result = client.list_project_consoles(ListProjectConsolesRequest(**packed.payload))

exec_project¶

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¶

exec_project(
    body: ExecProjectRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> BulkResult

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

Parameters¶

Parameter	Type	Required	Description
body	ExecProjectRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 180000 ms default.

Request schema: ExecProjectRequest¶

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	yes
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

BulkResult

Field	Python type	Required	Semantics
requested	int	yes
started	int	yes
already_running	int	yes
already_starting	int	yes
stopped	int	yes
already_stopped	int	yes
wiped	int	yes
failed	int	yes
invalid	int	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:

result = client.exec_project(ExecProjectRequest(**{**packed.payload, "action": "start"}))
if result.failed or result.invalid:
    raise SystemExit(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¶

from eveiac import ExecProjectRequest, pack_lab

packed = pack_lab("./my-lab")
result = client.exec_project(ExecProjectRequest(**{**packed.payload, "action": "start"}))

export_project_config¶

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¶

export_project_config(
    body: ExportProjectConfigRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> ExportConfigData

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

Parameters¶

Parameter	Type	Required	Description
body	ExportProjectConfigRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 1800000 ms default.

Request schema: ExportProjectConfigRequest¶

ExportProjectConfigRequest is the same wire shape as ExportConfigRequest.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	yes	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ExportConfigData

Field	Python type	Required	Semantics
lab	str	yes
configset	str	yes
nodes	list[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:

saved = client.export_project_config({**packed.payload, "configset": "default", "nodes": ["n_1"]})
failed = [node for node in (saved.nodes or []) if 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¶

result = client.export_project_config()

apply_link_quality¶

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¶

apply_link_quality(
    body: ApplyLinkQualityRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> LinkQualityData

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

Parameters¶

Parameter	Type	Required	Description
body	ApplyLinkQualityRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 30000 ms default.

Request schema: ApplyLinkQualityRequest¶

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.
match	PublicLinkMatch	yes
source_impairment	LinkImpairment	no
destination_impairment	LinkImpairment	no
save	bool	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	Python type	Required	Semantics
applied	bool	yes
persisted	bool	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:

result = client.apply_link_quality(ApplyLinkQualityRequest(**{**packed.payload, "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¶

from eveiac import ApplyLinkQualityRequest, pack_lab

packed = pack_lab("./my-lab")
result = client.apply_link_quality(ApplyLinkQualityRequest(**{**packed.payload, "match": {"endpoints": [{"node": "n_1", "interface": "e0/0"}, {"node": "n_2", "interface": "e0/1"}]}, "source_impairment": {"delay": 50, "loss": 1}, "save": True}))

set_link_suspend¶

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¶

set_link_suspend(
    body: SetLinkSuspendRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> LinkSuspendData

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

Parameters¶

Parameter	Type	Required	Description
body	SetLinkSuspendRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 30000 ms default.

Request schema: SetLinkSuspendRequest¶

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.
match	PublicLinkMatch	yes
suspended	bool	yes	true = native suspend; false = native resume. Required; omitted is 400 invalid_request.
side	str	no	source, destination, or both. Omitted/empty is both. Wire-distinct from explicit both.

Returns¶

LinkSuspendData

Field	Python type	Required	Semantics
applied	bool	yes
suspended	bool	yes
side	str	no
match	PublicLinkMatch	no
targets	list[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:

result = client.set_link_suspend(SetLinkSuspendRequest(**{**packed.payload, "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¶

from eveiac import SetLinkSuspendRequest, pack_lab

packed = pack_lab("./my-lab")
result = client.set_link_suspend(SetLinkSuspendRequest(**{**packed.payload, "match": {"endpoints": [{"node": "n_1", "interface": "e0/0"}, {"node": "n_2", "interface": "e0/1"}]}, "suspended": True}))

start_capture¶

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¶

start_capture(
    body: StartCaptureRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> CaptureData

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

Parameters¶

Parameter	Type	Required	Description
body	StartCaptureRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 30000 ms default.

Request schema: StartCaptureRequest¶

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	yes	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.
interface	str	yes	Interface name on that node.

Returns¶

CaptureData

Field	Python type	Required	Semantics
node	str	yes	omitted: all nodes. empty string: all nodes. named: that IaC node key
interface	str	yes
url	str	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¶

from eveiac import StartCaptureRequest, pack_lab

packed = pack_lab("./my-lab")
result = client.start_capture(StartCaptureRequest(**{**packed.payload, "node": "n_1", "interface": "e0/0"}))

attach_traffic¶

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¶

attach_traffic(
    body: AttachTrafficRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> TrafficAttachData

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

Parameters¶

Parameter	Type	Required	Description
body	AttachTrafficRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 30000 ms default.

Request schema: AttachTrafficRequest¶

AttachTrafficRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

TrafficAttachData

Field	Python type	Required	Semantics
stream	str	yes
transport	str	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¶

from eveiac import AttachTrafficRequest, pack_lab

packed = pack_lab("./my-lab")
attached = client.attach_traffic(AttachTrafficRequest(**packed.payload))

exec_console¶

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¶

exec_console(
    body: ExecConsoleRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> ConsoleExecData

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

Parameters¶

Parameter	Type	Required	Description
body	ExecConsoleRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: ExecConsoleRequest¶

ExecConsoleRequest is the same wire shape as ConsolePayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
manifest	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	str	no
commands	list[str]	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	list[ConsoleTarget]	no
session_id	str	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	int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	str	no	Go regexp for waitConsole.
max_bytes	int	no	Bounded history tail for getConsoleHistory.
steps	list[ConsoleRunStep]	no
dir	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ConsoleExecData

Field	Python type	Required	Semantics
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
name	str	no
console_type	str	no
command	str	no
output	str	no
duration_ms	int	no
timed_out	bool	no
truncated	bool	no
prompt	str	no
session_id	str	no
match	str	no
phase	str	no	Interaction phase: discovering, ready, executing, paging, interactive, auth_required, error.
recovered	bool	no	True when a missing session was reopened for this call.
rx_to	int	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:

data = client.exec_console(ExecConsoleRequest(**{**packed.payload, "node": "n_1", "command": "show version"}))
print(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¶

from eveiac import ExecConsoleRequest, pack_lab

packed = pack_lab("./my-lab")
data = client.exec_console(ExecConsoleRequest(**{**packed.payload, "node": "n_1", "command": "show version"}))

exec_console_many¶

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¶

exec_console_many(
    body: ExecConsoleManyRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> ConsoleExecManyData

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

Parameters¶

Parameter	Type	Required	Description
body	ExecConsoleManyRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: ExecConsoleManyRequest¶

ExecConsoleManyRequest is the same wire shape as ConsolePayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
manifest	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	str	no
commands	list[str]	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	list[ConsoleTarget]	no
session_id	str	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	int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	str	no	Go regexp for waitConsole.
max_bytes	int	no	Bounded history tail for getConsoleHistory.
steps	list[ConsoleRunStep]	no
dir	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ConsoleExecManyData

Field	Python type	Required	Semantics
results	list[Mapping[str, Any]]	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:

data = client.exec_console_many(ExecConsoleManyRequest(**packed.payload))
for row in data.results or []:
    print(row.node, row.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¶

from eveiac import ExecConsoleManyRequest, pack_lab

packed = pack_lab("./my-lab")
data = client.exec_console_many(ExecConsoleManyRequest(**packed.payload))

create_console_session¶

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¶

create_console_session(
    body: CreateConsoleSessionRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> ConsoleSessionData

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

Parameters¶

Parameter	Type	Required	Description
body	CreateConsoleSessionRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 30000 ms default.

Request schema: CreateConsoleSessionRequest¶

CreateConsoleSessionRequest is the same wire shape as ConsolePayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
manifest	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	str	no
commands	list[str]	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	list[ConsoleTarget]	no
session_id	str	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	int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	str	no	Go regexp for waitConsole.
max_bytes	int	no	Bounded history tail for getConsoleHistory.
steps	list[ConsoleRunStep]	no
dir	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ConsoleSessionData

Field	Python type	Required	Semantics
session_id	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
name	str	no
console_type	str	no
mode	ConsoleWriteMode	no
state	Literal["idle", "connecting", "open", "draining", "closed"]	no
created_at	str	no
last_activity	str	no
observers	int	no
writers	int	no
owner	str	no	Exclusive writer owner when mode is exclusive.
phase	str	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:

sess = client.create_console_session(CreateConsoleSessionRequest(**{**packed.payload, "node": "n_1", "mode": "interact"}))
print(sess.session_id)

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¶

result = client.create_console_session()

list_console_sessions¶

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¶

list_console_sessions(
    body: ListConsoleSessionsRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> 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	ListConsoleSessionsRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: ListConsoleSessionsRequest¶

ListConsoleSessionsRequest is the same wire shape as ConsolePayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
manifest	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	str	no
commands	list[str]	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	list[ConsoleTarget]	no
session_id	str	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	int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	str	no	Go regexp for waitConsole.
max_bytes	int	no	Bounded history tail for getConsoleHistory.
steps	list[ConsoleRunStep]	no
dir	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ConsoleSessionListData

Field	Python type	Required	Semantics
sessions	list[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:

listed = client.list_console_sessions(ListConsoleSessionsRequest(**packed.payload))

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¶

result = client.list_console_sessions()

get_console_session¶

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¶

get_console_session(
    body: GetConsoleSessionRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> 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	GetConsoleSessionRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: GetConsoleSessionRequest¶

GetConsoleSessionRequest is the same wire shape as ConsolePayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
manifest	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	str	no
commands	list[str]	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	list[ConsoleTarget]	no
session_id	str	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	int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	str	no	Go regexp for waitConsole.
max_bytes	int	no	Bounded history tail for getConsoleHistory.
steps	list[ConsoleRunStep]	no
dir	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ConsoleSessionData

Field	Python type	Required	Semantics
session_id	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
name	str	no
console_type	str	no
mode	ConsoleWriteMode	no
state	Literal["idle", "connecting", "open", "draining", "closed"]	no
created_at	str	no
last_activity	str	no
observers	int	no
writers	int	no
owner	str	no	Exclusive writer owner when mode is exclusive.
phase	str	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:

sess = client.get_console_session(GetConsoleSessionRequest(**{**packed.payload, "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¶

result = client.get_console_session()

close_console_session¶

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¶

close_console_session(
    body: CloseConsoleSessionRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> ConsoleSessionData

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

Parameters¶

Parameter	Type	Required	Description
body	CloseConsoleSessionRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: CloseConsoleSessionRequest¶

CloseConsoleSessionRequest is the same wire shape as ConsolePayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
manifest	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	str	no
commands	list[str]	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	list[ConsoleTarget]	no
session_id	str	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	int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	str	no	Go regexp for waitConsole.
max_bytes	int	no	Bounded history tail for getConsoleHistory.
steps	list[ConsoleRunStep]	no
dir	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ConsoleSessionData

Field	Python type	Required	Semantics
session_id	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
name	str	no
console_type	str	no
mode	ConsoleWriteMode	no
state	Literal["idle", "connecting", "open", "draining", "closed"]	no
created_at	str	no
last_activity	str	no
observers	int	no
writers	int	no
owner	str	no	Exclusive writer owner when mode is exclusive.
phase	str	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:

closed = client.close_console_session(CloseConsoleSessionRequest(**{**packed.payload, "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¶

result = client.close_console_session()

get_console_history¶

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¶

get_console_history(
    body: GetConsoleHistoryRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> 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	GetConsoleHistoryRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: GetConsoleHistoryRequest¶

GetConsoleHistoryRequest is the same wire shape as ConsolePayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
manifest	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	str	no
commands	list[str]	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	list[ConsoleTarget]	no
session_id	str	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	int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	str	no	Go regexp for waitConsole.
max_bytes	int	no	Bounded history tail for getConsoleHistory.
steps	list[ConsoleRunStep]	no
dir	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ConsoleHistoryData

Field	Python type	Required	Semantics
session_id	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
text	str	no	Bounded raw console tail (UTF-8 interpretation).
truncated	bool	no
byte_count	int	no
available_bytes	int	no	Bytes retained in the Hub ring (max 65536).
end_seq	int	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:

hist = client.get_console_history(GetConsoleHistoryRequest(**{**packed.payload, "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¶

result = client.get_console_history()

wait_console¶

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¶

wait_console(
    body: WaitConsoleRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> ConsoleWaitData

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

Parameters¶

Parameter	Type	Required	Description
body	WaitConsoleRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 615000 ms default.

Request schema: WaitConsoleRequest¶

WaitConsoleRequest is the same wire shape as ConsolePayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
manifest	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	str	no
commands	list[str]	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	list[ConsoleTarget]	no
session_id	str	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	int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	str	no	Go regexp for waitConsole.
max_bytes	int	no	Bounded history tail for getConsoleHistory.
steps	list[ConsoleRunStep]	no
dir	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ConsoleWaitData

Field	Python type	Required	Semantics
session_id	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
matched	bool	no
match	str	no
text	str	no	Matched snippet.
duration_ms	int	no
timed_out	bool	no
truncated	bool	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:

waited = client.wait_console(WaitConsoleRequest(**{**packed.payload, "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¶

result = client.wait_console()

run_console¶

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¶

run_console(
    body: RunConsoleRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> ConsoleRunData

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

Parameters¶

Parameter	Type	Required	Description
body	RunConsoleRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 615000 ms default.

Request schema: RunConsoleRequest¶

RunConsoleRequest is the same wire shape as ConsolePayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
manifest	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	str	no
commands	list[str]	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	list[ConsoleTarget]	no
session_id	str	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	int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	str	no	Go regexp for waitConsole.
max_bytes	int	no	Bounded history tail for getConsoleHistory.
steps	list[ConsoleRunStep]	no
dir	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ConsoleRunData

Field	Python type	Required	Semantics
session_id	str	no
ok	bool	no
failed_step	int	no	0-based failed step index; -1 when ok.
steps	list[ConsoleRunStepResult]	no
transcript	str	no	Bytes received after the sends in this run, up to the completing match.
truncated	bool	no
duration_ms	int	no
prompt	str	no
phase	str	no
rx_to	int	no
recovered	bool	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:

ran = client.run_console(RunConsoleRequest(**{**packed.payload, "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¶

result = client.run_console()

attach_console¶

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¶

attach_console(
    body: AttachConsoleRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> ConsoleAttachData

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

Parameters¶

Parameter	Type	Required	Description
body	AttachConsoleRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 30000 ms default.

Request schema: AttachConsoleRequest¶

AttachConsoleRequest is the same wire shape as ConsolePayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
manifest	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command	str	no
commands	list[str]	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms	int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets	list[ConsoleTarget]	no
session_id	str	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	int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode	ConsoleWriteMode	no
pattern	str	no	Go regexp for waitConsole.
max_bytes	int	no	Bounded history tail for getConsoleHistory.
steps	list[ConsoleRunStep]	no
dir	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

ConsoleAttachData

Field	Python type	Required	Semantics
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
name	str	no
console_type	str	no
stream	str	no
transport	Literal["eve-telnet"]	no
session_id	str	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:

attached = client.attach_console(AttachConsoleRequest(**{**packed.payload, "node": "n_1"}))
ticket = attached.stream.rsplit("/", 1)[-1] if attached.stream else None

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¶

from eveiac import AttachConsoleRequest, pack_lab

packed = pack_lab("./my-lab")
attached = client.attach_console(AttachConsoleRequest(**{**packed.payload, "node": "n_1"}))

stream_console¶

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¶

stream_console(
    ticket: str,
    timeout_ms: int | None = None
) -> Any

• 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	str	yes	Path parameter
timeout_ms	int \| None	no	Override the 15000 ms default.

Returns¶

Transport upgrade object (socket). Not a JSON model.

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¶

sock = client.stream_console(ticket)

stream_traffic¶

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¶

stream_traffic(
    ticket: str,
    timeout_ms: int | None = None
) -> Any

• 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	str	yes	Path parameter
timeout_ms	int \| None	no	Override the 15000 ms default.

Returns¶

Transport upgrade object (socket). Not a JSON model.

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¶

sock = client.stream_traffic(ticket)

start_oob¶

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¶

start_oob(
    body: StartOobRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> OobStatusData

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

Parameters¶

Parameter	Type	Required	Description
body	StartOobRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 30000 ms default.

Request schema: StartOobRequest¶

StartOobRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

OobStatusData

Field	Python type	Required	Semantics
active	bool	no
username	str	no	SSH username. Always eve-oob while active. HTTP does not authenticate this name.
user_public_key	str	no
host_public_key	str	no
host_fingerprint	str	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¶

result = client.start_oob()

get_oob_status¶

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¶

get_oob_status(
    body: GetOobStatusRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> 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	GetOobStatusRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: GetOobStatusRequest¶

GetOobStatusRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

OobStatusData

Field	Python type	Required	Semantics
active	bool	no
username	str	no	SSH username. Always eve-oob while active. HTTP does not authenticate this name.
user_public_key	str	no
host_public_key	str	no
host_fingerprint	str	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¶

result = client.get_oob_status()

get_oob_credentials¶

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¶

get_oob_credentials(
    body: GetOobCredentialsRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> OobCredentialsData

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

Parameters¶

Parameter	Type	Required	Description
body	GetOobCredentialsRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 30000 ms default.

Request schema: GetOobCredentialsRequest¶

GetOobCredentialsRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

OobCredentialsData

Field	Python type	Required	Semantics
username	str	no
user_private_key	str	no
user_public_key	str	no
host_public_key	str	no
host_fingerprint	str	no
known_hosts	str	no
nodes	list[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¶

result = client.get_oob_credentials()

stop_oob¶

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¶

stop_oob(
    body: StopOobRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> OobStatusData

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

Parameters¶

Parameter	Type	Required	Description
body	StopOobRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 30000 ms default.

Request schema: StopOobRequest¶

StopOobRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

OobStatusData

Field	Python type	Required	Semantics
active	bool	no
username	str	no	SSH username. Always eve-oob while active. HTTP does not authenticate this name.
user_public_key	str	no
host_public_key	str	no
host_fingerprint	str	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¶

result = client.stop_oob()

open_oob¶

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¶

open_oob(
    body: OpenOobRequest | Mapping[str, Any],
    timeout_ms: int | None = None
) -> OobOpenData

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

Parameters¶

Parameter	Type	Required	Description
body	OpenOobRequest	yes	Request body.
timeout_ms	int \| None	no	Override the 15000 ms default.

Request schema: OpenOobRequest¶

OpenOobRequest is the same wire shape as ProjectPayload.

Field	Python type	Required	Semantics
lab	str	no
yaml	str	no
files	dict[str, str]	no
state	Any	no
source	Any	no
manifest	str	no
prune	bool	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	bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action	str	no
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes	list[str]	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset	str	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id	int	no
stopmode	int	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	bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace	bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity	str	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	str	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	bool	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	str	no	getPublicProject only. topology or presentation. Omitted = topology.
path	str	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter	str	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	str	no	Rejected when non-empty.
out	str	no	Rejected when non-empty.

Returns¶

OobOpenData

Field	Python type	Required	Semantics
node	str	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
ticket	str	no	64-char lowercase hex. Single use. 30s TTL. Bound to this session, project, node, and generation.
stream	str	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¶

result = client.open_oob()

stream_oob¶

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¶

stream_oob(
    ticket: str,
    timeout_ms: int | None = None
) -> Any

• 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	str	yes	Path parameter
timeout_ms	int \| None	no	Override the 15000 ms default.

Returns¶

Transport upgrade object (socket). Not a JSON model.

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¶

result = client.stream_oob()