Service

A Service is a long-running, resilient entry point (like an API or UI) that provides a stable, persistent URL. Its primary purpose is to ensure there is always a healthy Job running behind the scenes to handle incoming requests.

Think of a Service as the manager or controller, and a Job as the actual worker process. The Service manages the lifecycle, recovery, and network exposure of the Job. Users interact with the stable URL of the Service, and the system automatically proxies requests to the active Job.

Service vs Job

While a Service relies on a Job to execute its task, their roles and behaviors in the Toolkit are fundamentally different.

• A Service is a persistent, long-running entity designed for continuous availability. It provides a stable, permanent URL and its primary responsibility is to manage the lifecycle of its underlying job, automatically restarting it if it fails. Think of a Service as the manager for always-on applications like APIs, model serving endpoints, or web UIs.

• A Job, on the other hand, is an ephemeral, one-time execution. It runs a specific task from start to finish and then terminates. While a Service uses a job as its worker, a normal job can be run standalone for batch processing, data analysis, or model training. It does not have a persistent URL and is not automatically restarted upon completion or failure.

Getting Started

1. Create the Service

First, you create the Service resource.

eai service new testsvc

id                                   name    fullName             role                      runtime                      status accessUrl
6c5bf9ec-71f7-4d13-b5ec-24b37f0f8e9e testsvc snow.testacc.testsvc snow.testacc.testsvc_role snow.testacc.testsvc_runtime on     https://6c5bf9ec-71f7-4d13-b5ec-24b37f0f8e9e.service.console.elementai.com

Note

This creates the service and an associated (but currently empty) data resource named snow.testacc.testsvc_runtime to act as its runtime and role resource named snow.testacc.testsvc_role. You can also pass flags like --runtime to link to an existing Data resource, --role to specify a different role, or --upload to upload your application or configuration files directory in the same step.

2. Push Application and Configuration Files to the Runtime

Next, push your application files (e.g., server.py) and any necessary configuration files (e.g., nginx.conf) to the service’s runtime.

eai data push snow.testacc.testsvc_runtime ./server.py

3. Configure the Job Specification

Now, configure how the service’s job will run. You can do this by using the eai service update command to set the parameters directly or by pushing an eai.yaml file to the runtime. The eai service update command is often the most straightforward way to define the job spec.

eai service update 6c5bf9ec-71f7-4d13-b5ec-24b37f0f8e9e --i "python:3.9-slim" --cpu 1 --mem 1 -- python3 -u /service/server.py

Note

• The job spec command must come at the end of eai service update after – as above example.

• More options and usage formats can be found using the eai service update --help command.

You can now verify that the runtime contains your pushed files and the newly generated eai.yaml.

eai data content ls snow.testacc.testsvc_runtime

name             status
eai.yaml         new
server.py        new

4. Access the Service to Trigger the Job

The first time you access the service’s URL, the system automatically starts a job based on your configuration.

# Access the URL with curl or a browser
curl -H "$(eai login token -H)" https://6c5bf9ec-71f7-4d13-b5ec-24b37f0f8e9e.service.console.elementai.com

• This initial request triggers the following automated process:

  • The system checks for an active job for the service.

  • If no active job is found, it looks for a previously failed, interrupted, or cancelled job with the same specification to retry.

  • If no reusable job is found, a new job is created.

  • The system waits for the job to become healthy by passing a readiness check. For this to succeed, you must have a valid server running in your container and a valid command in your eai.yaml to start it.

  • Once ready, the original HTTP request is proxied to the job.

• You can confirm the job is running:

eai job ls --service 6c5bf9ec-71f7-4d13-b5ec-24b37f0f8e9e

id                                   state   name created              command runs.exitCode accessUrl
a147dd0c-5aba-4465-b1e8-1fb77b6d2258 RUNNING      2025-08-05T18:52:53Z []      -             https://a147dd0c-5aba-4465-b1e8-1fb77b6d2258.job.console.elementai.com

• Subsequent requests are proxied directly to the already-running job.

Default eai.yaml Creation

If you access a service for the first time or update the service runtime for the first time and its runtime does not contain an eai.yaml file, the system will automatically create a default one to ensure a job can start.

runtime:
    image: python:3.10
    command:
        - "/bin/sh"
        - "-c"
        - "cp /service/* /tmp/ && python3 -m http.server 8080 --directory /tmp"
    resources:
        cpu: 1
        mem: 1

A default index.html file is also created. This file shows a message “Service is Running” on the service’s access URL page.

Service Lifecycle and Resource Management

The service is designed to be efficient and manage resources automatically.

• Stopping a Service: When you stop a service using the eai service stop command, two things happen:

  • The service’s status is set to “off”, and its access URL will no longer accept traffic.

  • The system will automatically find and kill any currently running jobs associated with that service.

  This ensures that a stopped service does not consume any resources.

• Cancelling Old Jobs: When you update a service’s runtime or job specification, the system starts a new job with the new configuration. The old job associated with the previous configuration is automatically cancelled to ensure only the latest version is active.

• Automatic Downscaling: To conserve resources, services that are not in use are automatically scaled down. If a service receives no traffic for 24 hours, its running job will be stopped. The next time the service URL is accessed, a new job will be started on-demand.

Service Commands

• Creates the service resource.

eai service new testsvc

Note

More options and usage formats can be found using the eai service new --help command.

• Lists all services in your account or organization.

eai service ls snow.testacc

• Shows detailed information about a specific service.

eai service get 6c5bf9ec-71f7-4d13-b5ec-24b37f0f8e9e

• Modifies the job specification of an existing service.

eai service update 6c5bf9ec-71f7-4d13-b5ec-24b37f0f8e9e -i python:3.10 --gpu 2 --cpu 2 --mem 2 --non-preemptable -- python3 -u /service/server.py

Note

The job spec command must come at the end of eai service update after -- as above example. More options and usage formats can be found using the eai service update --help command.

• Enables a service, allowing it to start jobs and accept traffic.

eai service start 6c5bf9ec-71f7-4d13-b5ec-24b37f0f8e9e

• Disables a service. Its URL will become unavailable, and its running job will be stopped.

eai service stop 6c5bf9ec-71f7-4d13-b5ec-24b37f0f8e9e

• Deactivates a service.

eai service deactivate 6c5bf9ec-71f7-4d13-b5ec-24b37f0f8e9e

• Reactivates a previously deactivated service.

eai service reactivate 6c5bf9ec-71f7-4d13-b5ec-24b37f0f8e9e

• Manages roles and permissions for the service.

eai service role [command] [flags]