serve
Register a new service from a prebuilt container image, specifying name, image, port and environment variables. Deploy your image as a running service on the host.
Instructions
Register a service from a prebuilt image.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | Environment variables injected into the container, as literal strings. Omit for none. Secrets belong in ``set_secret``, which overrides an ``env`` key of the same name at launch. | |
| gpus | No | GPUs the service needs; default 0 = none. Allocation is shared, not exclusive, and is checked against the token's quota. | |
| name | Yes | Name for the NEW service: a lowercase DNS label, 1-63 chars (``^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$``). Register-only — an existing name is refused with 409 ``service.name_taken`` rather than redeployed. | |
| port | No | Container port published on the host. Default 8000; 1-65535. | |
| image | Yes | Tag of an image that already exists on the daemon's runtime; it is never built and never pulled here, and a missing one is refused with 400 ``image_not_found``. | |
| vendor | No | GPU vendor to reserve when ``gpus`` > 0 (``nvidia`` or ``amd``); omit to let the daemon choose on a fresh deploy — a redeploy keeps the vendor already recorded. | |
| command | No | Command overriding the image's CMD, split into argv like a shell would (``shlex``) but run WITHOUT a shell — no pipes, redirects or ``$VAR``; write ``sh -c '…'`` for those. Omit to run the image's own CMD. | |
| script_path | No | Host path to a script run under ``nerdit-runtime`` instead of the image CMD. Omit for the image CMD; it bind-mounts a host directory and needs an admin token (403 ``sandbox.script_path_forbidden``). | |
| health_check | No | Probe policy ``{path, type: http|tcp, timeout_s, unhealthy_threshold, start_period_s}``; omit for liveness-only supervision. Repeated failures mark the service ``degraded`` and leave it running — only a dead container is restarted. | |
| restart_policy | No | What the daemon does when the container exits: ``always`` (the default), ``on-failure`` or ``no``. | always |
| idempotency_key | No | Caller-chosen key: a retry with the same key replays the first result instead of acting twice. Omit and a fresh key is minted per call, so each call acts. |