Services and service definitions

A service is a long-running process the platform keeps alive on a device: an HTTP server, a collector, anything that is supposed to stay up. A service definition describes one, the way a job definition describes a piece of work that finishes.

The difference in one line: a job finishes, a service does not.

This page covers the free-form service feature, where you supply the command. A service that serves one of your models through the CLIKA runtime is a model deployment, which the platform defines for you.

Service definitions

clika-rt service-definitions [command]

Subcommand	Purpose
list	Every service definition.
get <name-or-id>	One definition.
create --body '<json>'	Create one.
update <name-or-id> --body '<json>'	Change one.
delete <name-or-id>	Delete one.

A service definition carries the fields a long-running process needs that a job does not.

Field	Type	Meaning
name	string	Display name and handle.
description	string	Free text.
command	array of strings	The argument vector to run. Unlike a job definition, it sits at the top level rather than under script.
env	object	Environment variables.
port	integer	The port the service listens on, which is what the platform advertises and health-checks.
health_check	object	How to tell whether the process is actually serving, as opposed to merely running.
auto_restart	boolean	Restart the process when it exits.
artifacts	array of objects	Files pushed to the device before the service starts.
cleanup_steps	array of objects	What to run when the service is stopped or removed.
required_resources	object	The same minimums, accelerator list and engine gate as a job definition.
project_id	string	Scopes the definition to one project.

Running services

services and devices services-* are the runtime side. They act on the processes actually running, as opposed to the definitions describing them.

clika-rt services list [flags]

Flag	Type	Default	Meaning
--device_id	string	all	Only services on one device.
--state	string	all	Filter by service state.
--search	string	none	Match a service id, a device name, or a service type.
--page	string	1	Page number.
--page_size	string	server default	Rows per page.

That is an organization-wide view. To act on one device's services, use the device commands:

clika-rt devices services jetson-01
clika-rt devices services-create jetson-01 --body '{"service_definition_id":"vllm-server"}'
clika-rt devices services-restart jetson-01 <svc_id>
clika-rt devices services-stop jetson-01 <svc_id>

Starting a service from a committed file works the same way as a job:

kind: Service
service_definition: vllm-server
devices:
  - jetson-01

Service is apply-only. There is no flat collection to fetch one service by id across the fleet, so export does not support the kind. Read a running service back through devices services-svc_id instead.

Desired state keeps a service up

A service is not started once and forgotten. The platform holds it in the device's desired state, and the agent reconciles towards it, which is what brings the process back after a device reboots. The desired-state commands are on the devices page.

Full command reference

Every command below is generated from the deployment's own API description, so one subcommand is exactly one platform operation. Each entry names the method, the endpoint and the MCP tool name, so the same operation is identifiable whichever surface you drive it from. Path parameters are positional arguments, query parameters are flags, and a request body is --body or --body-file. The hand-written commands, the ones that stream, propagate an exit code, or hand your terminal to ssh, carry no operation line.

The prose above covers the commands most people reach for. This section is the complete surface, for when you need the flag you have not used before.

clika-rt service-definitions

service-definitions has 5 subcommands.

clika-rt service-definitions create

Create service definition

clika-rt service-definitions create [flags]

Flag	Type	Default	Meaning
--body	string	none	request body (inline JSON)
--body-file	string	none	request body (path to a JSON file)
--raw	bool	false	print raw response without pretty-printing

Endpoint: POST /api/service-definitions. MCP tool name: post_service_definitions.

clika-rt service-definitions delete

Delete service definition

clika-rt service-definitions delete <name-or-id> [flags]

Positional arguments: required <name-or-id>.

Flag	Type	Default	Meaning
--raw	bool	false	print raw response without pretty-printing

Endpoint: DELETE /api/service-definitions/{id}. MCP tool name: delete_service_definitions_id.

clika-rt service-definitions get

Get service definition

clika-rt service-definitions get <name-or-id> [flags]

Positional arguments: required <name-or-id>.

Flag	Type	Default	Meaning
--raw	bool	false	print raw response without pretty-printing

Endpoint: GET /api/service-definitions/{id}. MCP tool name: get_service_definitions_id.

clika-rt service-definitions list

List service definitions

clika-rt service-definitions list [flags]

Flag	Type	Default	Meaning
--raw	bool	false	print raw response without pretty-printing

Endpoint: GET /api/service-definitions. MCP tool name: get_service_definitions.

clika-rt service-definitions update

Update service definition

clika-rt service-definitions update <name-or-id> [flags]

Positional arguments: required <name-or-id>.

Flag	Type	Default	Meaning
--body	string	none	request body (inline JSON)
--body-file	string	none	request body (path to a JSON file)
--raw	bool	false	print raw response without pretty-printing

Endpoint: PUT /api/service-definitions/{id}. MCP tool name: put_service_definitions_id.

clika-rt services

services has 1 subcommands.

clika-rt services list

List running services (org-wide)

clika-rt services list [flags]

Flag	Type	Default	Meaning
--device_id	string	none	Filter by device ID (UUID)
--page	string	none	Page number (1-based)
--page_size	string	none	Items per page
--raw	bool	false	print raw response without pretty-printing
--search	string	none	Match service id, device name, or type
--state	string	none	Filter by service state

Endpoint: GET /api/services. MCP tool name: get_services.

Related

• Model deployment: the pre-defined service that serves a model through the CLIKA runtime.
• Job definitions: the counterpart for work that finishes.
• Devices: starting, stopping and inspecting a service on one device.
• apply and export: the resource YAML round trip.
• Service concept: what a service is, in prose.