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.
| 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
| 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).
| 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:
| 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 -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
}'
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']}")
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 https://api.erebine.ai/proj_ABC123/v1/management/join-keys \
-H "Authorization: Bearer ere_my-project_abc123"
Revoke a Join Key
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.
| 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.
| 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:
|
EIM and EEM API Examples
List EIMs and EEMs
curl https://api.erebine.ai/proj_ABC123/v1/management/agents \
-H "Authorization: Bearer ere_my-project_abc123"
Get Details
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 -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 -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 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 -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:
- Create a join key in the dashboard or via the API (see Join Key API Examples).
- Save the full key value immediately, it is shown only once.
- Run the EIM with the
enrollsubcommand, passing the join key. - The EIM authenticates with the router and establishes a secure encrypted connection.
- The EIM transitions to
activestatus and begins sending heartbeats. It is then ready to receive inference requests.
# 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 -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.
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.
| 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.
| 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.
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.
| 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 PATHEREBINE_EIM_HF_TOKEN_FILE=PATHEREBINE_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.
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.
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:
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:
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.
| 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.
| 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
| 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
stateDiagram-v2
[*] --> pending: join key issued
pending --> active: enrollment handshake
pending --> dead: join key expired
active --> suspended: PATCH status=suspended
active --> disconnected: heartbeat timeout
active --> dead: extended absence
disconnected --> active: heartbeat resumes
disconnected --> suspended: owner suspends
disconnected --> dead: extended absence
suspended --> active: PATCH status=active
suspended --> dead: extended absence
dead --> [*]
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.