Singularity

CLI commands

Run autonomous cycles continuously while the being remains solvent.

singularity run

Run the persistent being continuously. It boots the configured identity and surfaces, performs autonomous cycles while the remaining budget is above zero, and sleeps between cycles.

Invocation

singularity run \
  --agent-id <id> \
  --role <role> \
  --environment <environment> \
  --host <host> \
  --workload-id <id> \
  --workload-public-key <64-lowercase-hex> \
  --executable-digest <64-lowercase-hex> \
  --code-digest <64-lowercase-hex> \
  --policy-digest <64-lowercase-hex> \
  --policy-sequence <integer> \
  --las-release-manifest <absolute-file> \
  --las-release-manifest-signature <absolute-file> \
  --las-release-trust-store <absolute-file> \
  --las-release-watermark <absolute-path>

Required inputs

The command requires these options, or their named environment-variable equivalents:

  • --agent-id (SINGULARITY_AGENT_ID), --role (SINGULARITY_ROLE), --environment (SINGULARITY_ENVIRONMENT), --host (SINGULARITY_HOST), and --workload-id (SINGULARITY_WORKLOAD_ID). Each is a 1–128 byte immutable identifier using only ASCII letters, digits, -, _, ., or :.
  • --workload-public-key, --executable-digest, --code-digest, and --policy-digest. Each value is exactly 64 lowercase hexadecimal characters.
  • --policy-sequence <integer>.
  • --las-release-manifest, --las-release-manifest-signature, and --las-release-trust-store. Each must name an absolute regular file. --las-release-watermark must be absolute.
  • Brama signing material: either --brama-secret-file <owner-only-file> / BRAMA_HMAC_SECRET_FILE, or WISENT_APP_AGENT_AUTH_SECRET when no file is supplied.

Runtime options

  • Persona: --agent-name MyAgent, --agent-ticker AGENT, --agent-type general, and --specialty general.
  • State and loop: --stimulus <text>, --starting-balance 10, --instance-price 0, --cycle-interval-secs 5, --max-tool-rounds 8, --state-dir .singularity, --workspace ., and --resume.
  • Brama: --brama-url http://127.0.0.1:8081, --brama-model any, --max-tokens 2048, --temperature 0.2, --input-price 0, and --output-price 0.
  • Las: --las-command node, --las-entrypoint ../las/src/mcp.mjs, --las-only <csv>, --las-skip <csv>, and --required-surfaces skarbiec,finance.
  • Most and deadlines: --most-url http://127.0.0.1:8080, optional --most-token-file <owner-only-file>, --http-timeout-secs 120, --mcp-timeout-secs 120, and --shutdown-grace-secs 10.

Every flag above also has the environment-variable spelling exposed by singularity <command> --help.

Output and state effect

The command creates or resumes the owner-only state directory, saves state.json, and appends lifecycle, model, cost, tool, warning, and stop records to activity.jsonl. It normally writes operational logs rather than a final report to stdout. --stimulus contributes one external observation to the first cycle only.

Ctrl-C cancels the loop. Shutdown saves state, asks Las to stop within --shutdown-grace-secs, and records a final stopped event with status stopped or exhausted. A permanent Brama error aborts; other cycle errors become warning journal events and the next cycle proceeds after the configured interval.

State refusals

Boot is deliberately strict:

  • Existing state without --resume is refused as state: state already exists at <path>; use --resume or a new directory.
  • --resume with no saved state is refused as state: resume requested but no state exists.
  • --resume with a different configured identity is refused as state: resume identity does not match configuration.

A fresh state directory without --resume creates a new being. A matching saved identity with --resume continues it.

Configuration refusals

Before contacting a surface or writing being state, the runtime refuses with the exact relevant message when:

  • stimulus exceeds 65536 bytes or contains NUL: configuration: stimulus must be at most 65536 bytes and contain no NUL;
  • the workspace cannot be resolved or is not a directory: configuration: workspace: <error> or configuration: workspace must be a directory;
  • --max-tool-rounds is zero: configuration: max tool rounds must be positive;
  • a starting balance or price is negative: configuration: prices and balance cannot be negative;
  • temperature is not finite or is outside 0 through 2: configuration: temperature must be finite and between zero and two;
  • the Las entrypoint is not a file: configuration: LAS entrypoint not found: <path>;
  • a release manifest, signature, or trust-store path is not absolute or not a regular file: configuration: <label> must be an absolute regular file;
  • the watermark path is relative: configuration: LAS release watermark must be an absolute path;
  • an immutable identity component is invalid: configuration: <label> is not a valid immutable identifier;
  • a public key or digest is malformed: configuration: <label> must be 64 lowercase hexadecimal characters;
  • neither Brama secret source exists: secret file: BRAMA_HMAC_SECRET_FILE or WISENT_APP_AGENT_AUTH_SECRET is required;
  • a secret path is not a regular file, is group/world accessible, or is empty: secret file: not a regular file: <path>, secret file: <path> must not be group/world accessible, or secret file: <path> is empty.

Clap refuses a missing required option before runtime code executes. Configuration and secret refusals exit 2; upstream Brama, Las/MCP, or Most failures exit 3; state or I/O failures exit 4; tool, runtime, or JSON failures exit 5.