Local runtime (experimental)

Experimental

The local build and runtime are experimental. The tsm runtime commands, their behaviour and configuration may still change.

Full local Compose currently requires Docker Desktop on macOS or Windows. Linux host routing to loopback-published ports is unsupported; startup rejects that combination. Mixed profiles remain available on Linux. Managed JVM ownership has a Windows fallback; external/IDE placement is rejected because process arguments cannot be inspected safely. Windows ownership requires the recorded PID, exact start time and executable path. Legacy Windows process records without an executable remain unmanaged; inspect and stop them manually before recovery. An older Windows external runtime must use a separate source checkout until its process ownership can be established. Windows Compose profiles with native tenant preparation artifacts are rejected before startup because their host paths are not valid Linux container paths. Use remote tenant preparation or a macOS runtime for that workflow.

Most users do not need this chapter. It is for developers who want to build and run tSM services on their own machine.

tsm runtime runs tSM for one workspace in two ways:

• Full local stack: all required services, database and infrastructure run locally in Docker. See Run the whole stack locally.
• One service from your IDE: you run one service (for example ordering) in the IDE, and the rest of the services come from a shared development environment. See Run one service from your IDE.

How it works

Term	Meaning	Stored in
Service catalog	Which services exist and where their sources are	Workspace .tsm/runtime-profiles.yaml
Runtime profile	How the catalog runs: which services, as containers, JVMs or remote	Workspace .tsm/runtime-profiles.yaml
Runtime instance	One running setup per workspace: ID, ports, data	Workspace .tsm/state/ (generated)

• One workspace has exactly one instance. For independent data or ports, use another workspace.
• The profile is selected by the runtime command argument, otherwise by the workspace default.
• An environment without URL (for example local) means the workspace's own instance. While it runs, tsm --workspace demo app … talks to the local gateway; --context dev forces the remote environment instead.
• A stopped instance is an error. tsm never silently falls back to a remote environment.
• tsm runtime down stops the instance and keeps its data; changing a running profile needs down and up.
• .tsm/ is personal and generated: add it to .gitignore and never copy it from another user.

Reference: Runtime profiles, Troubleshooting.