erectl endpoints

Overview

An endpoint is a routable model deployment in your project. The endpoints command group covers its full lifecycle. Every subcommand resolves the active erectl context and authenticates with the project's API key; there are no project UUIDs to pass. Use --context <name> to target a specific deployment.

An endpoint can be served by one or more agents. When it has several, traffic is apportioned across them by weight, and the endpoint keeps serving as long as at least one attached agent is live. The agents subcommand manages that membership.

bash

                    erectl endpoints                       # list (default action)
erectl endpoints show my-endpoint
erectl endpoints agents list my-endpoint
                

endpoints list

List the project's endpoints. The default action when no subcommand is given.

bash

                    erectl endpoints
erectl endpoints -o wide
erectl endpoints -o json --columns id,status,model --filter status=ready
                

Honors the shared output flags (-o, --columns, --filter, --sort-by, --watch). Output columns: ID, NAME, STATUS, MODEL, TIER.

endpoints show

Show the full detail of one endpoint, including its provisioning state and primary agent.

bash

erectl endpoints show <endpoint-id>

endpoints create

Create an endpoint.

bash

                    erectl endpoints create \
  --name "My Endpoint" \
  --slug my-endpoint \
  --model-id <model-uuid> \
  --tier-id self_hosted
                

Flag	Description
`--name`	Display name.
`--slug`	Lowercase kebab-case slug (unique per project).
`--model-id`	Model UUID.
`--tier-id`	Service tier identifier.
`--task-mode`	`generate`, `embed`, or `score`.
`--required-gpu-model`, `--required-gpu-count`	GPU requirements.
`--quantization-override`	Quantization override.

To attach agents to a self-hosted endpoint, create it and then use endpoints agents add. Attach one or many; each takes a share of traffic.

endpoints update

Patch an endpoint. Only the flags you pass are changed.

bash

                    erectl endpoints update <endpoint-id> --name "Renamed"
erectl endpoints update <endpoint-id> --status suspended
                

Accepts --name, --tier-id, --status (active|suspended|draining), --custom-domain, --rpm, --tpm, GPU flags, --quantization-override, --task-mode.

endpoints delete

Soft-delete an endpoint. Prompts for confirmation unless --force is given.

bash

                    erectl endpoints delete <endpoint-id>
erectl endpoints delete <endpoint-id> --force
                

endpoints provision

Trigger provisioning for an endpoint.

bash

erectl endpoints provision <endpoint-id>

endpoints unprovision

Unprovision an endpoint, releasing its agents.

bash

erectl endpoints unprovision <endpoint-id>

endpoints cors

Read or set the endpoint's CORS configuration.

bash

                    erectl endpoints cors get <endpoint-id>
erectl endpoints cors set <endpoint-id> --allow-origins "https://app.example.com"
                

endpoints health

Read or set the health-probe configuration, or trigger a synthetic probe.

bash

                    erectl endpoints health config get <endpoint-id>
erectl endpoints health config set <endpoint-id> ...
erectl endpoints health check <endpoint-id>
                

Multi-agent endpoints

A self-hosted endpoint can be served by several agents at once. Traffic is split across them by a per-agent weight, and the endpoint stays up while any one attached agent is live. Setting an agent's weight to 0 drains it: it takes no new requests, in-flight requests finish, and its model stays loaded so the agent can be un-drained instantly.

The endpoints agents subcommand manages that membership. Adding an agent places the model on it; removing an agent tells it to unload the model first, then detaches it. An agent serves exactly one endpoint at a time, so attaching an agent already serving another endpoint is rejected.

bash

                    erectl endpoints agents list <endpoint-id>
erectl endpoints agents add <endpoint-id> --agent <agent-uuid> --weight 300
erectl endpoints agents weight <endpoint-id> <worker-id> --weight 0
erectl endpoints agents remove <endpoint-id> <worker-id>
                

Agent membership on anchor (shared, admin-owned) endpoints is managed from the admin dashboard, not this command group.

endpoints agents list

List the agents attached to an endpoint, with each agent's weight and live state.

bash

erectl endpoints agents list <endpoint-id>

Output columns: WORKER_ID, WEIGHT, STATE. A weight of 0 reads as draining.

endpoints agents add

Attach an agent to the endpoint. The model is placed on the agent automatically; the agent then joins the weighted rotation.

bash

                    erectl endpoints agents add <endpoint-id> --agent <agent-uuid>
erectl endpoints agents add <endpoint-id> --agent <agent-uuid> --weight 300
                

Flag	Description
`--agent`	Agent UUID to attach. Required.
`--weight`	Relative traffic weight (default 100). 0 drains the agent.

Fails with agent_busy (400) if the agent already serves another endpoint. GPU-fit is verified at attach time on the dashboard; the CLI checks that the model and agent exist and the agent is free.

endpoints agents weight

Change an attached agent's traffic weight. Takes effect immediately: a weight of 0 drains the agent (no new requests; in-flight requests finish; model stays loaded).

bash

                    erectl endpoints agents weight <endpoint-id> <worker-id> --weight 300
erectl endpoints agents weight <endpoint-id> <worker-id> --weight 0   # drain
                

Argument / Flag	Description
`<worker-id>`	The attached agent's worker id (from `agents list`).
`--weight`	New relative weight (>= 0). Required.

endpoints agents remove

Detach an agent from the endpoint. The agent is told to unload the model first, then the binding is removed; if the agent cannot be reached the binding is kept and the detach retried.

bash

erectl endpoints agents remove <endpoint-id> <worker-id>

Removing the last remaining agent unprovisions the endpoint. To drain an agent without detaching it, set its weight to 0 instead.

Examples

Serve one endpoint from two agents, weighting a faster GPU higher, then drain one for maintenance:

bash

                    # attach two agents, 3:1 split toward the faster box
erectl endpoints agents add my-endpoint --agent 1f0e-...-a1 --weight 300
erectl endpoints agents add my-endpoint --agent 2a7b-...-c9 --weight 100

# confirm the rotation
erectl endpoints agents list my-endpoint

# drain the slower agent for maintenance (traffic shifts to the other)
erectl endpoints agents weight my-endpoint DFW3:agent-2a7b --weight 0

# maintenance done -- un-drain instantly
erectl endpoints agents weight my-endpoint DFW3:agent-2a7b --weight 100
                