service.json Reference

Status: canonical runtime manifest reference.

This doc is the one-stop reference for the current service.json direction in the core service-lasso runtime.

It is meant to make the runtime and service templates usable without forcing service authors to reconstruct the contract from scattered notes.

What this doc covers

• top-level manifest purpose
• common top-level fields
• actions
• setup
• env / dependencies / ports
• healthcheck direction
• examples
• what is currently canonical vs still illustrative

Important current rule

The current template direction is:

• default health model = process
• other health models are used only when explicitly declared by service config

Supported explicit healthcheck types include:

• http
• tcp
• file
• variable

Purpose of service.json

service.json is the canonical service manifest used by Service Lasso to understand how a service should be discovered, prepared, executed, and monitored.

At a high level it carries:

• identity
• operator metadata
• lifecycle/action hints
• runtime execution settings
• environment settings
• dependency hints
• health expectations

Current sample manifest

The current sample in this repo is:

{
  "id": "echo-service",
  "name": "Echo Service",
  "description": "Minimal sample service used to prove the service-template contract.",
  "enabled": true,
  "version": "0.1.0",
  "logoutput": true,
  "icon": [
    {
      "provider": "lucide",
      "name": "terminal"
    }
  ],
  "logo": [
    {
      "path": "./logo.svg"
    }
  ],
  "servicetype": 50,
  "servicelocation": 10,
  "actions": {
    "install": {
      "description": "Prepare the sample runtime payload if needed."
    },
    "config": {
      "description": "Materialize effective runtime config for the sample service."
    },
    "start": {
      "description": "Start the sample echo service."
    },
    "stop": {
      "description": "Stop the sample echo service gracefully."
    }
  },
  "execconfig": {
    "serviceorder": 100,
    "serviceport": 0,
    "execcwd": "runtime",
    "executable": "echo-service",
    "env": {
      "ECHO_MESSAGE": "hello from service-template"
    },
    "depend_on": [],
    "healthcheck": {
      "type": "process"
    }
  }
}

Top-level fields

id

Unique service identifier.

Example:

"id": "echo-service"

Current direction:

• required
• should be stable
• should align with the service repo’s identity

name

Human-facing display name.

Example:

"name": "Echo Service"

description

Short operator-facing description.

enabled

Whether the service is enabled by default.

role

Declares whether the manifest describes a normal managed service or a local runtime provider.

Supported values:

• service or omitted: a normal service that can be installed, configured, started, stopped, and health-checked as a managed process when execution metadata is present
• provider: a runtime provider such as @node, @python, or @java; providers can be local/no-download or release-backed through artifact metadata

Provider-role services are installed/configured so their variables and dependency contract are available, but baseline start does not launch them as long-running daemon processes unless a later provider contract explicitly requires that.

Example:

"role": "provider"

version

Current package/version identity for the service.

logoutput

Whether stdout/stderr style runtime logging should be captured/displayed.

icon

UI/operator-facing symbolic icon list.

Current direction:

• icon should be an array of entries
• each entry should identify an icon provider and name
• consumers can choose the first icon provider they support

Example:

"icon": [
  {
    "provider": "lucide",
    "name": "terminal"
  }
]

logo

UI/operator-facing image/logo list.

Current direction:

• logo should be an array of entries
• the simple form is just path
• later entries can grow to include more metadata such as format/theme/size

Example:

"logo": [
  {
    "path": "./logo.svg"
  }
]

servicetype

Numeric service type classification value.

servicelocation

Numeric service location classification value.

actions

actions is where the service defines or overrides named lifecycle actions.

Current intended rule:

• actions correspond to known Service Lasso lifecycle/action names
• service config can override how a named action behaves for that service
• if a service does not override a supported action, Lasso default behavior applies

Current sample actions:

• install
• config
• start
• stop

Current action examples

"actions": {
  "install": {
    "description": "Prepare the sample runtime payload if needed."
  },
  "config": {
    "description": "Materialize effective runtime config for the sample service."
  },
  "start": {
    "description": "Start the sample echo service."
  },
  "stop": {
    "description": "Stop the sample echo service gracefully."
  }
}

Current action semantics direction

• install
  • prepare/install payload and required local setup
• config
  • materialize effective config from explicit inputs
• start
  • launch the service runtime
• stop
  • stop the service gracefully

Additional action names may exist later, but this first-pass template should stay small and lifecycle-focused.

execconfig

execconfig contains the runtime execution contract.

This is where the service tells Lasso how to run and supervise it.

serviceorder

Startup ordering hint.

Example:

"serviceorder": 100

serviceport

Primary service port.

In the sample, 0 is being used as a simple first-pass placeholder/default meaning “no fixed service port required by this sample”.

execcwd

Execution working directory.

Example:

"execcwd": "runtime"

executable

Executable or executable key/name used for the service runtime.

Example:

"executable": "echo-service"

Current direction:

• when a service runs directly, executable can be the local binary/script name or path
• when a service runs through a runtime provider, executable should be treated as the executable key exposed by that provider

Provider-backed example:

"execservice": "@node",
"executable": "NODE",
"args": ["runtime/server.js"]

Meaning:

• execservice chooses the runtime/provider service to use
• executable chooses which executable from that provider should be invoked
• the resulting runtime command is conceptually NODE runtime/server.js

This means execservice and executable are related, but not the same thing:

• execservice = who runs it
• executable = what binary from that runner gets used

Practical rule:

• use both when you want provider-backed execution to stay explicit
• do not assume execservice alone is enough unless Service Lasso later defines provider defaults clearly enough to make executable optional

args and commandline

args is the structured argument array passed to the selected executable.

commandline is a platform-specific string map used when a service needs to preserve an exact startup argument string:

"commandline": {
  "win32": " --config=\"${SERVICE_ROOT}\\runtime\\service.yml\" --port=\":${SERVICE_PORT}\"",
  "darwin": " --config=\"${SERVICE_ROOT}/runtime/service.yml\" --port=\":${SERVICE_PORT}\"",
  "linux": " --config=\"${SERVICE_ROOT}/runtime/service.yml\" --port=\":${SERVICE_PORT}\"",
  "default": " --config=\"${SERVICE_ROOT}/runtime/service.yml\" --port=\":${SERVICE_PORT}\""
}

Current core behavior:

• Service Lasso selects commandline[process.platform], falling back to commandline.default.
• ${...} selectors are resolved with the same service variables used for env/config materialization.
• The resolved commandline is parsed into process arguments and overrides args during start and restart.
• commandline is the arguments payload after the executable; it does not include the executable itself.
• Keep args as the fallback when no platform/default commandline is declared.

execservice

Runtime-provider service used to run this service through another packaged/runtime service.

Example:

"execservice": "@node"

Use this when:

• the service should run through a packaged Node/Python/Java runtime provider
• the service does not own the runtime binary directly inside its own payload

Do not use this when:

• the service already ships and runs its own executable directly

env

Service-local environment variables.

Example:

"env": {
  "ECHO_MESSAGE": "hello from service-template"
}

Current direction:

• service env should be explicit
• avoid depending on uncontrolled host-machine env leakage

depend_on

Explicit dependencies.

Example:

"depend_on": []

Current direction:

• use this for services that require another service/runtime/provider first
• keep empty for the minimal sample

Healthcheck

Default rule

Current rule:

• if a service does not explicitly require another model, the default is process

Example:

"healthcheck": {
  "type": "process"
}

This is the right default for a simple sample service.

Explicit healthcheck types

Service Lasso supports these explicit healthcheck types:

• http
• tcp
• file
• variable

process is the current template default direction; use one of the explicit types above when a service needs a stronger readiness signal.

process healthcheck

Use when:

• service health is adequately represented by the process being up/running
• you do not need a deeper readiness endpoint yet

Sample:

"healthcheck": {
  "type": "process"
}

http healthcheck

Use when:

• the service exposes an HTTP readiness or health endpoint

Sample:

"healthcheck": {
  "type": "http",
  "url": "http://localhost:${SERVICE_PORT}/health",
  "expected_status": 200
}

tcp healthcheck

Use when:

• readiness is best represented by a socket accepting connections

Sample:

"healthcheck": {
  "type": "tcp"
}

This relies on the configured service host/port.

file healthcheck

Use when:

• the service creates a file that represents successful readiness/setup

Sample:

"healthcheck": {
  "type": "file",
  "file": "${SERVICE_HOME}/.state/runtime/ready.txt"
}

variable healthcheck

Use when:

• a specific resolved/exported variable is the readiness signal

Sample:

"healthcheck": {
  "type": "variable",
  "variable": "${SERVICE_URL}"
}

Other important manifest aspects

Setup lifecycle steps

setup.steps defines named one-shot commands that run after install and config. Use setup for local preparation work that must execute on the user's machine but is not a daemon process.

Examples:

"setup": {
  "steps": {
    "install-python-deps": {
      "description": "Install service-local Python dependencies.",
      "commandline": {
        "win32": "pip.exe install --user -r \"${SERVICE_ROOT}\\requirements.txt\"",
        "default": "pip install --user -r \"${SERVICE_ROOT}/requirements.txt\""
      },
      "timeoutSeconds": 120,
      "rerun": "ifMissing"
    },
    "load-sample": {
      "description": "Load sample data through Python.",
      "depend_on": ["typedb", "typedb:init-schema", "@python"],
      "execservice": "@python",
      "commandline": {
        "win32": "\"${SERVICE_ROOT}\\jobs\\load-sample\\basic_upload.py\" --port ${TYPEDB_PORT}",
        "default": "\"${SERVICE_ROOT}/jobs/load-sample/basic_upload.py\" --port ${TYPEDB_PORT}"
      },
      "timeoutSeconds": 300,
      "rerun": "manual"
    }
  }
}

Runtime behavior:

• Direct setup: omit execservice; the selected commandline is parsed as the executable plus arguments, or executable plus args can be used.
• Provider-backed setup: set execservice to @node, @python, or @java; commandline or args becomes the provider executable's argument payload.
• Platform selection uses commandline[process.platform] with commandline.default fallback.
• Dependencies in depend_on can name services or setup steps using <serviceId>:<stepId>.
• Service dependencies must be installed/configured; non-provider service dependencies are started and health-checked before the setup step runs.
• Setup runs capture stdout/stderr logs and persist results in .state/setup.json.
• rerun supports ifMissing, manual, and always; baseline bootstrap runs non-manual setup steps and skips already successful ifMissing steps.

CLI:

service-lasso setup list
service-lasso setup run @localcert
service-lasso setup run typedb init-schema

Release artifacts and update policy

Current core manifests use first-class artifact metadata when a service archive should be acquired from a GitHub release.

Pinned example:

"artifact": {
  "kind": "archive",
  "source": {
    "type": "github-release",
    "repo": "service-lasso/lasso-echoservice",
    "tag": "2026.4.20-a417abd"
  },
  "platforms": {
    "win32": {
      "assetName": "echo-service-win32.zip",
      "archiveType": "zip"
    }
  }
}

If artifact.source.tag is present and no active updates policy is declared, Service Lasso treats the service as pinned.

Moving update checks require an explicit updates block:

"updates": {
  "enabled": true,
  "mode": "notify",
  "track": "latest",
  "checkIntervalSeconds": 3600
}

Supported updates.mode values:

• disabled
• notify
• download
• install

Current core status:

• notify can be used by the read-only update discovery function to classify pinned, latest, update_available, unavailable, or check_failed
• download downloads candidates without installing them
• install can install candidates through CLI/API or the opt-in scheduler when policy and safety gates allow
• install mode must declare an installWindow and runningService policy
• installWindow is enforced before automatic install work; out-of-window installs are deferred before download/extract
• runningService controls whether a running service is deferred or stopped/restarted during install

Environment generation

Current broader Service Lasso direction includes:

• explicit service-local env via env
• possible cross-service/global env behavior via globalenv

The sample template keeps this minimal for now.

Ports and URLs

More complex services can use additional fields such as:

• serviceportsecondary
• serviceportconsole
• serviceportdebug
• portmapping
• urls

These are not all used in the minimal sample, but they remain relevant for more complex services.

Runtime-provider relationships

Runtime-provider services use:

• execservice

This is relevant when a service is run via another runtime-provider service such as Node, Python, or Java.

The minimal sample does not use this yet.

Canonical vs illustrative right now

Treat as current first-pass canonical direction

• one service per repo
• service.json as the main service contract file
• lifecycle-focused actions
• execconfig as the execution contract section
• explicit env
• explicit depend_on
• default health model of process
• explicit override to other health models when needed

Still illustrative / not fully locked yet

• exact numeric meaning of servicetype
• exact numeric meaning of servicelocation
• final exact schema shape for all optional execconfig fields
• final exact health schema normalization
• final exact release artifact conventions across all service types

Recommended authoring guidance

For the first template-based service:

1. keep the manifest small
2. use process health unless another model is clearly needed
3. explicitly declare env and dependencies
4. avoid mixing generated runtime state into package content
5. prefer clarity over trying to model every advanced feature on day one

Related docs

Start here for the broader Service Lasso contract:

• docs/service-authoring/overview.md
• docs/development/new-lasso-service-guide.md