Skip to content

Configuration

The default configuration is ~/.molcrafts/molq/config.json. Select another JSON or YAML file with --config. Configuration files are used individually, not merged.

Temporary service

With no endpoint, the CLI starts a temporary stdio service. Python does the same with Molq(). Cluster definitions persist in the default registry at ~/.molcrafts/molq/registry.db.

Choose separate files for a project:

import json

from molq import Molq

mq = Molq(registry="./registry.db", config="./config.json")
print(json.dumps(mq.clusters.list(), ensure_ascii=False))
mq.close()
molq --registry ./registry.db --config ./config.json cluster list

Keep the registry on local disk. Use one active service per registry when sharing observations; independent instances do not share caches or cursors.

Shared service

Save this as config.json. Replace the example token with your own token of at least 16 characters; server and client tokens must match.

{
  "serve": {
    "host": "127.0.0.1",
    "port": 17891,
    "token": "replace-with-your-own-token"
  },
  "client": {
    "endpoint": "http://127.0.0.1:17891",
    "token": "replace-with-your-own-token"
  }
}

Start the service in one terminal:

molq serve --config ./config.json

Use it from another:

molq --config ./config.json cluster list

Python and TypeScript take the endpoint and token explicitly:

import json

mq = Molq(endpoint="http://127.0.0.1:17891", token="replace-with-your-own-token")
print(json.dumps(mq.clusters.list(), ensure_ascii=False))
mq.close()

For HTTP connections, the registry and settings file belong to the service. Molq(config=...) selects a temporary service's file; it does not select an HTTP endpoint from the file's client section. The CLI does read that section.

Settings and presets

Cluster defaults apply to submissions on that destination. Presets are reusable request fragments; retrieve one and apply its fields explicitly.

{
  "settings": {"cache_max_entries": 4096, "cache_max_age": 5},
  "presets": {"small": {"resources": {"tasks": 1, "cpus_per_task": 2}}}
}

Manage these through the service:

molq rpc config.get --params '{"key":"cache_max_age"}'
molq rpc config.set --params '{"key":"cache_max_age","value":5}'
molq rpc presets.get --params '{"key":"small"}'
molq rpc config.reload

config.reload applies external edits and resets observation cursors. Invalid edits leave the previous settings active. default_cluster is a saved preference; RPC operations still require an explicit scope.

Layout upgrade and legacy maintenance

Stop every old serve and stdio process using the registry. Back up registry.db and submissions/<registry-id>/ and remove job_retention_days from the configuration. On open, the new runtime imports legacy submission evidence into the existing SQLite database. Imported keys remain reserved and return CONFLICT on new submissions. Run maintenance.prune_submissions to remove only files verified against the SQLite copy. The result reports removed and retained filenames.

Old archives are preserved during upgrade. Inspect a cluster's archive, then choose specific verified duplicates to delete:

molq rpc maintenance.inspect --params '{"cluster":"hpc"}'
molq rpc maintenance.prune --params '{"cluster":"hpc","entries":["0123456789abcdef0123456789abcdef"]}'
molq rpc maintenance.prune_submissions

Inspection checks the local manifest and returns an optional after value for the next page. For a removed cluster, inspect by its original cluster ID. Pruning checks the manifest again and verifies the remote copy. It deletes only serve-host archive files whose complete matching copy is still present on the target. Interrupted copies, mixed archives, and the only known copies of logs or Shell receipts stay available for manual export. The new runtime does not look up old Shell runs through these archives.

SSH connection options belong in OpenSSH configuration. molq does not read MOLQ_* environment variables. See watch configuration for cadence and notification routes.