Executors¶
An executor runs a job. Select one with -e (--executor-keys):
| Executor | Runs on | Returns after reboot? |
|---|---|---|
local |
This host, as a managed daemon. | Needs a supervisor to restart it. |
systemd |
This host, as a user service. | Yes, once the user session starts. |
api:label |
Another Meerschaum API server. | Depends on that server's executor. |
An installed Meerschaum uses systemd when a user systemd session is available, including in Compose roots. Source checkouts, development builds, and hosts without systemd use local. Set meerschaum:executor in edit config to change the default.
For API-managed work, an administrator can also select a team's execution environment:
the main host, a generated Stack container, or an independently managed service. This placement
applies after the main API authorizes the caller. Selecting -e api:label sends a request to that
API; it does not override the team's placement or permissions there.
Run a job remotely¶
mrsm sync pipes --loop --name syncing-engine -e api:prod -d
mrsm show logs syncing-engine -e api:prod
-e chooses where code runs; -i chooses where Pipe data is stored.
# Execute on the remote host, using its sql:local instance.
mrsm sync pipes -i sql:local -e api:prod
# Execute here, storing data through the remote API.
mrsm sync pipes -i api:prod
Local daemons¶
Job metadata lives in $MRSM_ROOT_DIR/jobs/<name>/; logs live in $MRSM_ROOT_DIR/logs/. When the process that starts a job holds MRSM_CONFIG or MRSM_PATCH (a Compose project's config: block, for example), the job receives them as owner-only files in its directory (.mrsm_config.json, .mrsm_patch.json, written at every start and removed with the job) named by MRSM_CONFIG_FILE / MRSM_PATCH_FILE, so its environment holds no credentials. A job started before 5.1 keeps its environment until it is started again. start, stop, pause, and delete jobs manage the daemon. A local job does not restart itself after a host reboot. While an API server runs on the root (mrsm start api, or a Docker container), it restarts stopped --restart jobs every second, so the jobs inside a container come back with it; jobs stopped by hand stay stopped. Otherwise use systemd or another supervisor.
Systemd services¶
Jobs are enabled as user services. Logs are available through both mrsm show logs and journalctl --user.
Scoped jobs in 5.1 require the trusted standalone native mrsm launcher. Their units require
systemd 235 or newer and use UnsetEnvironment= to remove inherited loader and interpreter
settings before startup. After upgrading, recreate existing scoped units through the job's
original CLI or Compose definition; restarting an old unit alone does not add these rules.
The migration guide covers team runtime changes.
Unit names, environment, and login sessions
The default root uses mrsm-<name>.service. Other roots use mrsm-<project>.<name>.service, with the Compose project name or a short root-path hash. Commands list only the current root's jobs.
Units save the root, plugins directory, and project environment. Their files use mode 0600. Since 5.1 a unit carries no MRSM_CONFIG / MRSM_PATCH: their text is written to owner-only files next to the unit ($MRSM_ROOT_DIR/systemd/services/<name>/.mrsm_config.json and .mrsm_patch.json) and the unit sets MRSM_CONFIG_FILE / MRSM_PATCH_FILE. Units written by earlier versions keep their Environment=MRSM_CONFIG=... line until the job is created again (compose up recreates its jobs). To keep user services running while logged out, enable lingering:
Older installations which used local Compose jobs move them to systemd on the next compose up or restart jobs. Set meerschaum:executor: local to keep local daemons.
Custom executors
Plugins may implement an executor type. See the Python Executor API or Rust executors and streams.