docs
// Infrastructure

Private EIMs

Bring your own hardware under the router. Mint a time-bounded join key, run the Erebine Inference Microservice (EIM), watch it transition from pending to active, and the router treats it as a first-class EIM for the project that owns it. This page is the practical CRUD: join keys, enrollment, lifecycle, monitoring.

Overview

One EIM drives one accelerator or many, and several EIMs can share a machine, so you decide how your accelerators are split.

For a side-by-side of private EIMs vs. shared EIMs, see the EIM Types overview.

This page documents the project-scoped Frontend API (authenticated with a project API key or dashboard session). The router also exposes a parallel API-key-authed management surface at /:project_id/v1/management/join-keys and /:project_id/v1/management/agents; see the API reference for details. Defaults may differ between the two surfaces.

EIM and EEM Fields

The following fields describe an enrolled EIM, or an enrolled Erebine Execution Manager (EEM): both are records of the management API's agents resource. They are returned by its list and detail endpoints.

Fields returned by the EIM and EEM list and detail API endpoints.
Field Type Description
id string (UUID) Unique EIM or EEM identifier.
name string Human-readable name for the EIM or EEM. Settable at enrollment and updatable via PATCH.
worker_id string Unique worker identifier used in the mesh protocol.
region string Region where the EIM or EEM is located (1-24 ASCII characters, inherited from the join key used at enrollment).
max_concurrent_requests integer Admit slots: the concurrent inference requests this EIM accepts, reported by the EIM (safe slots times its over-provisioning factor). On create and update it is the ceiling the EIM's admit slots are capped at; 0 means auto-configured by the platform.
safe_concurrent_requests integer Safe slots: the concurrent requests this EIM's KV cache holds without preemption, as last reported; 0 until the EIM reports. Read-only. EIMs serving an anchor are routed by safe slots; other EIMs by admit slots.
description string or null Optional description or notes about this EIM or EEM. Updatable via PATCH.
supported_tiers array of strings or null Service tier slugs this EIM serves. Membership is explicit: the EIM's accelerator never adds or removes a tier. Example: ["self_hosted"].
agent_public_key string Public key the EIM or EEM authenticates the mesh connection with. Set at enrollment and immutable afterwards.
country_code string ISO 3166-1 alpha-2 country the EIM or EEM serves from. An operator assertion: nothing on the wire proves where a host sits, so you set it and the response echoes back what was stored. Updatable via PATCH.
allow_model_preseed boolean Whether this EIM may register models imported from its local disk. Defaults to false. EIMs only. See Preseeding a Local Model.
status string Current lifecycle status. See EIM Lifecycle for all values.
last_heartbeat_at string (ISO 8601) or null Timestamp of the most recent heartbeat received from the EIM or EEM.
enrolled_at string (ISO 8601) or null Timestamp when the EIM or EEM successfully completed enrollment.
created_at string (ISO 8601) or null Timestamp when the record was created.
updated_at string (ISO 8601) or null Timestamp of the most recent change to the record.
agent_role string or null Role the record enrolled as: inference (an EIM) or execution (an EEM). Returned by the list and detail reads. Null on the create and PATCH responses, and null whenever the role cannot be read back - treat a missing role as "not proven", never as inference.
capability_manifest_hash string or null SHA-256 of the capability manifest an EEM published at enrollment. Returned by the list and detail reads for EEMs only; null for EIMs, and null on the create and PATCH responses, where no manifest exists yet. Use it to confirm the EEM you started published the manifest you expect.
engine object, omitted when absent The inference engine the EIM registered: name (vllm or laya), version (the engine package version), task_modes (the task modes the EIM serves), device (where the engine computes, such as cpu, cuda or mps) and cpu_fallbacks (requests the engine moved to CPU after running out of GPU memory). version is omitted when the EIM could not read it; device and cpu_fallbacks are omitted until the engine reports them, and a vLLM engine reports neither. The whole object is omitted for an EEM and for an EIM that has not registered an engine. An EIM from an earlier release sends no engine; the router records it as vllm without a version. See Registration and Placement.
gpus array of objects, omitted when absent Each GPU's readings from the EIM's last status report: index (the EIM's GPU number), utilization_percent (0 to 100), memory_used_bytes, memory_total_bytes, temperature_celsius, power_watts (current draw) and power_limit_watts. A reading the GPU does not report is omitted, never sent as 0; on Intel, utilization and power appear from the second report on. The array is omitted for an EEM, a CPU EIM, and an EIM from an earlier release. The readings are informational: placement does not use them.
events array of objects or null Recent events, newest first, embedded by the single-record read so a dashboard renders the timeline in one round-trip. Null on the list response; page the dedicated events endpoint for the full history.

Join Key Management

Join keys are secure tokens that authorize an EIM or EEM to enroll in your project. Each key is tied to a specific project, carries a region assignment, and expires after a configurable TTL (maximum 1 hour). Keys can be single-use or multi-use.

API Endpoints

REST endpoints for managing join keys.
Method Endpoint Description
POST /:projectId/v1/management/join-keys Create a new join key.
GET /:projectId/v1/management/join-keys List all join keys for the project (paginated).
DELETE /:projectId/v1/management/join-keys/:keyId Revoke a join key. EIMs and EEMs already enrolled are not affected. Returns 204 No Content on success.
GET /:projectId/v1/management/tiers List the platform's service tiers. The slug values are what supported_tiers accepts.

Join Key Fields

The following fields are accepted when creating a join key (POST).

Request body fields for POST join-keys.
Field Type Required Description
name string Yes Human-readable label for the join key (e.g. "datacenter-rack-3").
region string Yes Region to assign to EIMs and EEMs enrolled with this key. Must be 1-24 ASCII characters (e.g. "us-east-1").
expires_in_hours integer or null No Time-to-live in hours. Defaults to the maximum (1 hour). The hard limit is 1 hour regardless of the value supplied. Must be greater than 0: a value less than or equal to 0 is refused with 400.
max_enrollments integer or null No Maximum number of EIMs or EEMs that may enroll with this key. Must be greater than 0; a value less than or equal to 0 is refused with 400. Defaults to 10. Set 1 for a single-use key.
router_addresses array of strings or null No Router addresses for EIMs and EEMs to connect to. When omitted, platform defaults are used.
supported_tiers array of strings or null No Service tier slugs every EIM enrolled with this key inherits. When omitted or empty, the key carries every self-hosted tier. An unknown slug is refused with 400. Keys created here enroll EIMs. List valid slugs with GET /:projectId/v1/management/tiers.

The response for a create request includes the full key value exactly once. It cannot be retrieved later because only the SHA-256 hash is stored.

The list and detail responses include the following join key fields:

Fields returned by the join-key list and detail endpoints.
Field Type Description
id string (UUID) Unique join key identifier.
name string Human-readable label.
key_prefix string Visible prefix of the key for identification. The first 8 characters include the ejk_ tag and the leading characters of the project slug (e.g. for project slug myproj, the prefix renders as ejk_mypr****wxyz). The full key is never returned after creation.
region string Region assigned to EIMs and EEMs enrolled with this key.
max_enrollments integer Maximum enrollments allowed.
current_enrollments integer Number of EIMs or EEMs that have enrolled using this key so far.
expires_at string (ISO 8601) Timestamp when the key expires.
status string Current status: active, used, expired, or revoked.
can_enroll boolean Whether the key can still be used for enrollment (active, not expired, enrollments remaining).
created_at string (ISO 8601) or null Timestamp when the key was created.
storage_limit_enabled boolean or null Whether a storage limit was set on this key. The limit travels to the EIM in its enrollment payload; it is a property of the key, not of the enrolled EIM, so the EIM's record does not carry it.
storage_limit_bytes integer (int64) or null Storage ceiling in bytes applied to EIMs enrolled with this key. Relevant only when storage_limit_enabled is true.

Join Key API Examples

In the examples below, replace proj_ABC123 with your project external id (e.g. proj_a1b2c3d4). The project external id is the leading path segment, and the API key must carry the management scope.

Create a Join Key

curl
curl -X POST https://api.erebine.ai/proj_ABC123/v1/management/join-keys \ -H "Authorization: Bearer ere_my-project_abc123" \ -H "Content-Type: application/json" \ -d '{ "name": "datacenter-rack-3", "region": "us-east-1", "expires_in_hours": 1, "max_enrollments": 1 }'
Python
import requests headers = { "Authorization": "Bearer ere_my-project_abc123", "Content-Type": "application/json" } response = requests.post( "https://api.erebine.ai/proj_ABC123/v1/management/join-keys", headers=headers, json={ "name": "datacenter-rack-3", "region": "us-east-1", "expires_in_hours": 1, "max_enrollments": 1 } ) result = response.json() # Save the key value immediately, it cannot be retrieved later print(f"Join Key: {result['key']}")
Node.js
const response = await fetch( "https://api.erebine.ai/proj_ABC123/v1/management/join-keys", { method: "POST", headers: { "Authorization": "Bearer ere_my-project_abc123", "Content-Type": "application/json" }, body: JSON.stringify({ name: "datacenter-rack-3", region: "us-east-1", expires_in_hours: 1, max_enrollments: 1 }) } ); const result = await response.json(); // Save the key value immediately, it cannot be retrieved later console.log(`Join Key: ${result.key}`);

List Join Keys

curl
curl https://api.erebine.ai/proj_ABC123/v1/management/join-keys \ -H "Authorization: Bearer ere_my-project_abc123"

Revoke a Join Key

curl
curl -X DELETE https://api.erebine.ai/proj_ABC123/v1/management/join-keys/KEY_ID \ -H "Authorization: Bearer ere_my-project_abc123"

EIM and EEM API

EIMs and EEMs are enrolled automatically using a join key (see EIM Enrollment). Once enrolled, you can list, view, update, and remove them via the following endpoints.

REST endpoints for managing enrolled EIMs and EEMs.
Method Endpoint Description
GET /:projectId/v1/management/agents List all enrolled EIMs and EEMs for the project (paginated). Supports ?status= filter.
GET /:projectId/v1/management/agents/:agentId Get full details of a specific EIM or EEM.
PATCH /:projectId/v1/management/agents/:agentId Update an EIM's or EEM's name, description, or status (suspend/resume).
DELETE /:projectId/v1/management/agents/:agentId Remove an EIM or EEM from the project. The stored status is set to disconnected and a disconnected event is emitted with reason=removed_by_user. The EIM remains visible in the list under the disconnected status. Returns 204 No Content on success.
GET /:projectId/v1/management/agents/:agentId/events Retrieve the event log for a specific EIM or EEM.

PATCH Request Body

All fields are optional. Only provided fields are updated.

Optional fields accepted by the PATCH endpoint.
Field Type Description
name string or null New human-readable name for the EIM or EEM.
description string or null New description or notes for the EIM or EEM.
allow_model_preseed boolean or null Grant (true) or revoke (false) local model preseeding for this EIM. Granting it to an EEM is refused. See Preseeding a Local Model.
status string or null Status change request. Valid values:
  • active: resume a suspended EIM or EEM.
  • suspended: suspend an active EIM or EEM. Suspended ones do not receive new requests.

EIM and EEM API Examples

List EIMs and EEMs

curl
curl https://api.erebine.ai/proj_ABC123/v1/management/agents \ -H "Authorization: Bearer ere_my-project_abc123"

Get Details

curl
curl https://api.erebine.ai/proj_ABC123/v1/management/agents/AGENT_ID \ -H "Authorization: Bearer ere_my-project_abc123"

Suspend an EIM or EEM

curl
curl -X PATCH https://api.erebine.ai/proj_ABC123/v1/management/agents/AGENT_ID \ -H "Authorization: Bearer ere_my-project_abc123" \ -H "Content-Type: application/json" \ -d '{"status": "suspended"}'

Resume an EIM or EEM

curl
curl -X PATCH https://api.erebine.ai/proj_ABC123/v1/management/agents/AGENT_ID \ -H "Authorization: Bearer ere_my-project_abc123" \ -H "Content-Type: application/json" \ -d '{"status": "active"}'

Get Events

curl
curl https://api.erebine.ai/proj_ABC123/v1/management/agents/AGENT_ID/events \ -H "Authorization: Bearer ere_my-project_abc123"

Remove an EIM or EEM

curl
curl -X DELETE https://api.erebine.ai/proj_ABC123/v1/management/agents/AGENT_ID \ -H "Authorization: Bearer ere_my-project_abc123"

EIM Enrollment

To enroll a private EIM:

  1. Create a join key in the dashboard or via the API (see Join Key API Examples).
  2. Save the full key value immediately, it is shown only once.
  3. Run the EIM with the enroll subcommand, passing the join key.
  4. The EIM authenticates with the router and establishes a secure encrypted connection.
  5. The EIM transitions to active status and begins sending heartbeats. It is then ready to receive inference requests.
Shell
# Enroll an EIM. The key goes in the environment: # a command line is visible to every account on the host. EREBINE_EIM_JOIN_KEY="ejk_my-project_..." erebine-eim enroll

After enrollment, start the EIM in serve mode to begin handling inference requests. See the EIM Deployment guide for detailed setup instructions.

Preseeding a Local Model

A preseeded model is one that is already on the EIM's disk. Point the EIM at the directory and it registers the model with the router: the model joins your project's model list, endpoints can serve it, and the weights never cross the network. The platform keeps no copy of the files.

Private EIMs only. EEMs cannot hold models, so the permission below is refused for them.

1. Allow the EIM to Preseed

New EIMs are created with Allow model preseed already ticked; clear it on the create form if you would rather this EIM never registered local weights. EIMs created before this default shipped have it off. To change it on an enrolled EIM, open its Actions menu, choose Edit, and set Allow model preseed there -- or use the API:

curl
curl -X PATCH https://api.erebine.ai/proj_ABC123/v1/management/agents/AGENT_ID \ -H "Authorization: Bearer ere_my-project_abc123" \ -H "Content-Type: application/json" \ -d '{"allow_model_preseed": true}'

The CLI carries the same switch: erectl eims EIM_ID --update --allow-preseed, and --no-allow-preseed to take it back.

The import is a local filesystem operation, so nothing checks the permission while it runs. The check happens when the EIM registers the model with the router. Grant it first, or the registration is rejected and the model never appears.

2. Import the Model

The source must be a Hugging Face model directory: a config.json plus at least one .safetensors or .bin weight file. A source that is a symlink into a Hugging Face cache is resolved to the real files first.

Stop the EIM before importing. The import takes exclusive access to the model cache and refuses to start while a running EIM holds it.

Shell
sudo systemctl stop erebine-eim-agent erebine-eim import-model /srv/models/my-model \ --model-name my-model \ --link-mode auto sudo systemctl start erebine-eim-agent

The command prints the model id, the link mode it resolved, the file count, and the size. When the EIM registers the model, your project gives it an id of its own and the EIM switches to that id; list-models shows the id the model has now. An EIM from an earlier release cannot register a newly imported model, so upgrade it first.

Arguments and options accepted by the import-model subcommand.
Argument Description
<path> Required. Path to the model directory.
--model-name Name shown in your model list. Defaults to the source directory name.
--link-mode auto, hardlink, copy, or symlink. Defaults to auto.
--model-cache-path Cache path to import into. Defaults to EREBINE_EIM_MODEL_CACHE_PATH, then to the EIM's built-in path.
--log-level trace, debug, info, warning, or error. Defaults to info.

Link Modes

The link mode decides how the files get into the cache, and what it costs you in disk.

How each link mode places the model files into the EIM model cache.
Mode Behavior
auto Hardlink, falling back to a copy when the source and the cache are on different filesystems. This is the default.
hardlink Hardlink only. Fails when the source and the cache are on different filesystems.
copy Always copy. Consumes cache space; a copy larger than the space left is refused before any bytes move.
symlink Symlink into the source. Costs nothing, and the model breaks if you move or delete the source.

Importing the same directory twice is a no-op. A source whose files already match a cache entry returns that entry and writes nothing.

Downloading from Hugging Face

Instead of a directory, give the EIM a Hugging Face repository id. It downloads the model itself -- no Python, no Hugging Face tools -- and imports it in the same run.

Shell
erebine-eim import-model --hf Qwen/Qwen3-0.6B

The revision resolves to a commit before anything moves, and every file is checked against the hashes the Hub publishes before the model is imported. An interrupted download resumes where it stopped: run the same command again.

The download can run while the EIM is running. Registering the model needs the EIM stopped, exactly like a directory import. If the EIM is still running when the download finishes, the command says so and exits with an error; stop the EIM and run the same command again. Verified files are not downloaded twice.

Options import-model accepts for a Hugging Face download.
Option Description
--hf Repository id, org/name. Replaces the directory argument. A model page URL is refused.
--revision Branch, tag, or commit. Defaults to main.
--include Glob of a skipped file to download anyway. Repeatable.
--exclude Glob of a file not to download. Repeatable. Wins over --include.
--hf-token-file File holding a Hugging Face token. See Gated and Private Repositories.
--hf-endpoint Hub or mirror base URL, https only. Defaults to EREBINE_EIM_HF_ENDPOINT, then to https://huggingface.co.
--concurrency Files downloaded at once, 1 to 16. Defaults to 4.
--model-name Name shown in your model list. Defaults to the repository's name.

--link-mode does not apply: downloaded files belong to the model cache and count against its size limit. The model registers with its Hugging Face id set, and list-models shows the repository and commit it came from.

Only what the engine serves is downloaded. Skipped by default: documentation and images, files and folders whose names start with a dot, the original/ reference checkpoints, other formats (GGUF, ONNX, OpenVINO, Core ML, TensorFlow, Flax), training state, and .bin weights when .safetensors weights exist. Everything else comes, so tokenizer, processor, chat template, and speaker files are never left behind. In a glob, * matches within one path segment, ** across segments, and ? one character; **/*.pt matches .pt files at any depth.

A repository without a config.json at its root, or without .safetensors or .bin weights (a GGUF-only repository, for one), is refused before any download, as is a selection that needs more disk or more model cache than is left.

Gated and Private Repositories

Public repositories need no token. A gated repository needs a token from an account that has accepted its terms on the model page; a private one, a token from an account that can read it. A read-only token is enough.

The token is never a command-line value, because every user on the host can read a command line. Put it in a file only you can read and pass the file, or use the environment. The first one set wins:

  • --hf-token-file PATH
  • EREBINE_EIM_HF_TOKEN_FILE=PATH
  • EREBINE_EIM_HF_TOKEN=TOKEN

HF_TOKEN and the Hugging Face CLI's saved token are not read, so a token already on the host is never used without you naming it. The token goes only to the Hub endpoint, never to the download hosts it redirects to, is never logged, and is not stored by the EIM.

Mirrors, Proxies, and Firewalls

EREBINE_EIM_HF_ENDPOINT (or --hf-endpoint) points the download at a mirror that serves the Hub API; a path prefix is allowed. Only https is accepted, for the endpoint and for every redirect. A mirror signed by a private certificate authority needs that authority in the system trust store.

Behind a proxy, set HTTPS_PROXY to an http:// proxy (credentials may be in the URL) and list the hosts that bypass it in NO_PROXY. Behind a firewall, allow outbound HTTPS to huggingface.co and the download hosts it redirects to: cdn-lfs-us-1.hf.co, cdn-lfs-eu-1.hf.co, us.aws.cdn.hf.co, us.gcp.cdn.hf.co, cas-server.xethub.hf.co, cas-server.xethub-eu.hf.co, transfer.xethub.hf.co, and transfer.xethub-eu.hf.co. Hugging Face changes these hosts from time to time, so allow every host under hf.co and huggingface.co where your firewall matches domain suffixes.

3. Start the EIM

The EIM registers its imported models when it starts and again on every reconnect. Once the router accepts one, it appears in the project's model list with a Preseeded badge; see Model Management for what you can do with it from there.

The model registers with the metadata its config.json supplies and the chat capability. Set anything else (capability tags such as vision, the parsers, trust remote code, speculative decoding, HF config overrides) once it appears, from the macOS app's Models pane, with erectl models update <id> --metadata <file.json> or PATCH /v1/models/{modelId}.

A rejection is logged with its reason: the EIM is not allowed to preseed, the name is already taken by another model in the project, or the model was deleted from the project. In the delete case the EIM purges its own copy; in the others, fix the cause and the next registration goes through.

Importing from the macOS App

The macOS application has an Import Model pane: pick the directory, pick the link mode, watch the checksum progress -- or pick Hugging Face, enter the repository, and watch the download, which the app runs itself with the same checks as import-model --hf. The app owns its EIM, so you do not stop anything first. With the EIM running the model is registered immediately; with it stopped, at the next start. Its Advanced group takes that metadata at import, all but reasoning effort and speculative decoding, and applies it once the router registers the model, before any endpoint the import creates. See EIM on macOS.

Importing in a Container

The import must run inside the EIM's mount namespace, or it writes to a cache the EIM never reads. It also cannot run while the EIM holds that cache. So: stop the EIM container, then run the import as a one-shot container carrying the same cache volume plus the source directory. The image entrypoint passes the arguments straight through.

Shell
docker run --rm \ -v MODEL_CACHE_VOLUME:/var/lib/inference/.cache/erebine/models \ -v /srv/models/my-model:/models/my-model \ ghcr.io/erebine/container-agents/eim-vllm-cuda:latest \ import-model /models/my-model

Two constraints follow the mounts. Hardlinking needs the source and the cache on one filesystem, so a source bind-mounted from elsewhere lands on copy instead. And the files have to be readable by the UID the EIM runs as.

A Hugging Face download needs only the cache volume, plus the token file for a gated or private repository, mounted read-only and readable by the EIM's UID. It can run beside the EIM container; stop the EIM before the run that registers the model.

Shell
docker run --rm \ -v MODEL_CACHE_VOLUME:/var/lib/inference/.cache/erebine/models \ -v /etc/erebine/hf-token:/run/secrets/hf-token:ro \ -e EREBINE_EIM_HF_TOKEN_FILE=/run/secrets/hf-token \ ghcr.io/erebine/container-agents/eim-vllm-cuda:latest \ import-model --hf meta-llama/Llama-3.2-1B

Listing and Removing Imported Models

The EIM can tell you what it holds and where each model stands with the router. Safe to run while the EIM is running:

shell
erebine-eim list-models

Each model reports registered (the router accepted it and it is in your model list), refused with the reason, or not announced when no verdict has arrived yet.

Removal has two halves, and they are not interchangeable. Deleting the model on the platform is the complete removal: the router tombstones it and asks every EIM in your project holding it to purge, and an EIM that misses that command self-purges on its next announce. The deletion applies to your project only. Do that from your model list, the desktop app's Import Model pane, or the API.

Removing the local copy deletes the files on one machine and nothing else -- the model stays in your project's list, pointing at bytes that are gone, until you delete it on the platform too. An EIM holds no management credential, so this is all the CLI can do:

shell
erebine-eim remove-model MODEL_ID

The EIM must be stopped for remove-model (it holds the cache lock while running). Source files outside the model cache are never touched, so a hardlink or symlink import leaves your originals alone. Models the platform downloaded are refused: removing one only forces the next provision to download it again.

What a Preseeded Model Does Not Do

  • It is not shared. The weights stay on the EIMs that imported them. The platform makes no copy, publishes nothing to the catalog, and refuses share and unshare.
  • Nothing reads the files in the background. Revalidation and metadata refresh are refused, and the background sweeps skip preseeded models. The only reader is the engine serving it.
  • It has no versions. Creating, promoting, and rolling back a version are refused.
  • It runs only where its bytes are. Endpoints can only bind EIMs that hold the files. The endpoint wizard blocks the other pairings and names the holders; creating or attaching past it is refused.
  • It uses no storage quota. Your quota counts bytes the platform stores, and it stores none of these.

Metadata is the exception: it stays yours to edit and it still drives what the EIM launches the engine with. See Model Management.

Deleting a Preseeded Model

  • Unbind it first. Delete is refused while an endpoint or an anchor endpoint binds the model.
  • Deleting removes it from your project. The model leaves your project and every EIM of your project holding the files purges its cached copy. An EIM that was offline at the time purges on its next registration attempt.
  • The purge stays inside the EIM's model cache. Your source directory is untouched.
  • Importing the same directory again creates a new model with a new id. Deleting bans the entry, not the files.

EIM Monitoring

The EIM dashboard at /eims provides real-time visibility into your enrolled EIMs:

  • Heartbeat status: whether each EIM is actively communicating with the router.
  • Current load: active request count and capacity.
  • Uptime: how long each EIM has been up since it last connected, and its availability over the last 24 hours, the share of that time it was online. Time it was disabled is not counted.
  • Model information: which model is loaded and its serving state.
  • Event history: per-EIM log of significant lifecycle events.

Programmatic Access

For programmatic snapshot access to your fleet, use the documented REST endpoint GET /:projectId/v1/management/agents (see EIM and EEM API) with a project API key.

Heartbeat Tracking

The router tracks the last_heartbeat_at timestamp for each EIM. An EIM with a heartbeat older than the staleness threshold (default 30 seconds; the deployment sets it) is considered disconnected and excluded from routing decisions until it reconnects and resumes sending heartbeats. The effective status shown in the dashboard and API is derived from both the stored status and heartbeat freshness.

EIM Controls

Each row's Actions menu carries three verbs beyond Edit and Delete. All three act on EIMs you own; none of them re-enrol the EIM or touch its downloaded models.

Owner-facing EIM control verbs and what each one does.
Action Endpoint Effect
Reset agent POST /agents/AGENT_ID/reset The EIM drops its endpoint assignment and its pinned model, restarts, and re-attaches from the router. Cached model files and enrolment survive, so recovery costs no re-download. In-flight requests are lost. Use this when the EIM stays connected but will not serve.
Disable agent POST /agents/AGENT_ID/disable Parks the EIM: it stops serving and frees its accelerator, but stays enrolled and keeps renewing its lease. A maintenance window opens for the duration, so the interval is excluded from the EIM's uptime. Refused while the EIM is suspended.
Enable agent POST /agents/AGENT_ID/enable Reverses a disable and closes the maintenance window. The EIM's endpoints return to service on the router's next health scan. Replaces the Disable entry in the menu while the EIM is disabled.

Reset and Disable both ask for confirmation in the dashboard. How an EIM comes back from a Reset depends on how it runs: a container with a restart policy or a systemd unit starts a fresh process; the macOS desktop app hosts the EIM itself and cycles it in place, without closing the app; an EIM run in the foreground stays stopped until you start it again.

EIM Lifecycle

EIMs and EEMs transition through the following status states. The status field in the database reflects the stored lifecycle state. The effective_status is computed at runtime from the stored status and heartbeat freshness.

Stored lifecycle states for an enrolled EIM or EEM.
Status Description
pending The record has been created (join key issued) but the EIM or EEM has not yet connected and authenticated.
active The EIM or EEM is connected and sending regular heartbeats. If the most recent heartbeat is older than the heartbeat staleness threshold (default 30 seconds; the deployment sets it), the effective status is disconnected even while the stored status remains active.
disconnected Stored after the heartbeat-timeout worker observes a stale EIM or EEM or after a DELETE remove call; also computed as the effective_status when the stored status is active but the most recent heartbeat is stale. The router excludes it from routing until it reconnects and heartbeats resume. The EIM or EEM may reconnect and return to active.
suspended Suspended by the project owner. A suspended EIM or EEM does not receive new requests. Resume with PATCH status=active.
dead Terminal state. The EIM or EEM failed to come online within the join key lifespan or was declared dead by the platform. A dead one does not receive requests and cannot be revived.

Allowed Transitions

Permitted state transitions and the trigger that causes each one.
From To Trigger
pending active The EIM or EEM connects and completes the enrollment handshake.
pending dead Join key expired before the EIM or EEM connected.
active suspended Owner calls PATCH with status=suspended.
active disconnected Heartbeat timeout detected by the router.
active dead Platform declares it dead after extended absence.
disconnected active It reconnects and heartbeats resume.
disconnected suspended Owner suspends a disconnected EIM or EEM.
disconnected dead Platform declares it dead after extended absence.
suspended active Owner calls PATCH with status=active.
suspended dead Platform declares it dead after extended absence.

State Diagram

Single-EIM Queuing

When only one EIM is available for an endpoint's tier, the router queues incoming requests instead of immediately returning a 503 error. This matters for deployments with a single EIM.

The queue timeout is 30 seconds by default; the deployment sets it. If the EIM does not become available within the timeout, the request fails with a timeout error.