Agent API

The Yokai agent listens on port 7474 by default. Every endpoint requires the bearer token generated during bootstrap.

Authorization: Bearer <agent-token>

Unauthenticated or incorrect requests receive 401 Unauthorized.

System and metrics

Method	Path	Purpose
GET	/health	Status, version, uptime, and hostname
GET	/system/info	OS, architecture, kernel, CPU, memory, disk, GPU, and Docker facts
GET	/metrics	Current system, GPU, container, and service JSON metrics
GET	/metrics/prometheus	Normalized Prometheus text exposition

Example:

curl -H "Authorization: Bearer $YOKAI_AGENT_TOKEN" \
  http://127.0.0.1:7474/health

Containers

Method	Path	Purpose
GET	/containers	List Yokai-managed containers
POST	/containers	Create and start a workload
DELETE	/containers/{id}	Stop and remove a workload
POST	/containers/{id}/stop	Stop without removing
POST	/containers/{id}/restart	Restart a workload
POST	/containers/{id}/test	Probe its declared service endpoint
GET	/containers/{id}/logs	Stream logs over SSE

Container creation accepts name, image, port mappings, environment, volumes, GPU selection, command arguments, labels, and runtime options. The daemon produces this payload; direct agent clients should preserve the yokai.* labels used for inventory and metrics.

Images

Method	Path	Purpose
GET	/images/tags/{image...}	List available tags for an image repository
POST	/images/pull	Pull an image and report progress

Prometheus contract

GET /metrics/prometheus emits bounded labels: service, backend, model, image, and result where appropriate. It must not emit container IDs, request IDs, prompts, or client IPs as labels.

Core metric families include:

yokai_service_up
yokai_service_info
yokai_llm_prefill_tokens_per_second
yokai_llm_decode_tokens_per_second
yokai_llm_requests_in_flight
yokai_llm_requests_queued
yokai_llm_prompt_tokens_total
yokai_llm_generated_tokens_total
yokai_llm_requests_total
yokai_llm_ttft_seconds
yokai_llm_request_duration_seconds
yokai_llm_kv_cache_utilization_ratio

Use Prometheus bearer-token configuration:

scrape_configs:
  - job_name: yokai-agent
    metrics_path: /metrics/prometheus
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/secrets/yokai-agent-token

Error behavior

Expect standard HTTP status codes: 400 for invalid input, 401 for failed authentication, 404 for missing resources, 409 for conflicts such as an existing container name, and 5xx for device or Docker failures.