Know which settings are local, committed, generated, and user-owned.

Configuration Locations

Machine-Local Config

mars setup prepares local state outside repositories. This lets the same installed binary run across many target repos without committing model weights, database files, tokens, or logs.

mars setup
mars setup --download
mars doctor --json
mars path setup

mars auth github check
mars auth github clear-local

mars start --repo /path/to/repo --db /private/tmp/mars-demo.db
mars serve --db /private/tmp/mars-shared.db

Execution Profile Admission

run, start, serve, tools run, and mcp serve default to observer. This operator-selected boundary independently caps manifest and stored trust, blocks shell_exec and all mutating tools, and cannot be enabled from target YAML.

mars run engineer --repo /path/to/repo --dry-run
mars start --repo /path/to/repo \
  --execution-profile host --acknowledge-host-execution

Host execution has the current OS user's filesystem, network, process, keychain, and credential authority and is not containment. Acknowledgement does not upgrade role trust. isolated fails before runtime state until MARS has an enforceable adapter.

Managed child environments

MARS-managed shell, CLI, dependency, Git, MCP, update, and inference subprocesses inherit ordinary variables such as PATH, HOME, temporary-directory, locale, and toolchain/cache settings. Credential-like names and MARS, GitHub, cloud/provider, authorization, SSH, token, secret, password, API-key, private-key, and credential variables are removed by default.

MARS_CHILD_ENV_ALLOWLIST=SSH_AUTH_SOCK,JIRA_API_TOKEN \
  mars serve --execution-profile host --acknowledge-host-execution

MARS_CHILD_ENV_ALLOWLIST is an environment-only, comma- or whitespace-separated owner control. It can restore only explicitly named parent variables, cannot be set by repository or model configuration, and is never propagated to a child. Jira env_passthrough names must also appear in this owner allowlist. Filtering is name-based and does not inspect values; subprocesses still run with the current OS user's authority, so this boundary reduces ambient credential exposure but is not isolation, a secret vault, or containment.

Code Intelligence Config

Code intelligence defaults on through local config and can be overridden per command. MARS resolves --code-intel first, then MARS_CODE_INTEL_ENABLED, then code_intel.enabled. Role runs still need code-intel tools in the manifest before automatic graph context is injected. For full behavior, metrics, and benchmark guidance, open the Code Intelligence Reference.

code_intel:
  enabled: true

mars run engineer --repo /path/to/repo --code-intel false
MARS_CODE_INTEL_ENABLED=true mars start --repo /path/to/repo

Aggregate Telemetry Config

Telemetry is off by default. Users can always inspect local status and preview the exact allowlisted aggregate payload before anything leaves the machine. Sending requires the mode named telemetry.reporting: anonymous and a collector endpoint. The mode name describes payload minimization; it does not make the network transport anonymous, and the collector can observe ordinary request metadata.

telemetry:
  reporting: off
  endpoint: ""
  token: ""
  report_interval: 24h

mars telemetry status --repo ~/my-project
mars telemetry preview --repo ~/my-project

MARS_TELEMETRY_REPORTING=anonymous \
MARS_TELEMETRY_ENDPOINT=http://127.0.0.1:9092 \
mars telemetry send --repo ~/my-project

Raw traces, prompts, file contents, repo paths, remotes, and raw errors are not sent in the anonymous aggregate report. For command recipes and privacy boundaries, open the Observability Guide.

.harness/manifest.yaml

The manifest is required for target harness execution. It must have a name and at least one role. New generated manifests use orchestration_mode: dispatch. For exact schema, routing behavior, generated defaults, and manifest errors, open the Bundle And Manifest Reference.

name: my-project
description: Starter autonomous AI pipeline for my-project
orchestration_mode: dispatch

roles:
  engineer:
    prompt: roles/engineer.md
    domain: engineer
    mode: ticket-delivery
    model: coding
    trust_level: contributor
    max_turns: 100
    schedule: "0 0,6,12,18 * * 1-5"
    knowledge: [knowledge/context-glossary.yaml]
    guardrails: [guardrails/safety.yaml]
    tools: [file_read, file_write, shell_exec, mars_cli, grep, docsync_audit, git_status, git_diff, git_commit]
    triggers:
      - ticket.assigned

.harness/model-overrides.yaml

Model overrides let a repo route all roles, a model tier, or one role to a specific local bundle, Ollama model, cloud provider, or OpenAI-compatible endpoint. Role overrides win over tier overrides, which win over the default route.

version: 2
default:
  routing: local
  local_bundle: auto
  reason: Use the best eligible local bundle for this machine.
tiers:
  coding:
    provider: ollama
    model: qwen3.6:27b
    endpoint: http://127.0.0.1:11434/v1
    reason: Local coding experiment.
roles:
  engineer:
    provider: openai-compatible
    model: repo-coder
    endpoint: http://127.0.0.1:8088/v1
    api_key_env: REPO_CODER_API_KEY
    reason: Target-specific coding gateway.

mars models override --repo /path/to/repo --tier coding --provider ollama --model qwen3.6:27b
mars models override --repo /path/to/repo --role engineer --provider openai-compatible --endpoint http://127.0.0.1:8088/v1 --model repo-coder
mars models credentials write-local-env --repo /path/to/repo --api-key-env OPENAI_API_KEY

Use the Authentication And Credentials Reference for provider key storage, env-var naming, and secret-scanning rules.

.harness/integrations.yaml

Integrations are optional and default off. Generated targets receive .harness/integrations.example.yaml, but MARS never writes .harness/integrations.yaml by default. Missing config, empty profile, or unknown profile normalizes to ceo-led.

version: 1
flow_profile: board-driven

ingestion:
  jira:
    enabled: true
    provider: atlassian_mcp
    base_url_env: JIRA_SITE_URL
    auth:
      email_env: JIRA_EMAIL
      api_token_env: JIRA_API_TOKEN
      bearer_token_env: JIRA_BEARER_TOKEN
    webhook_secret_env: JIRA_WEBHOOK_SECRET
    poll_interval: 60s
    jql: project = DEMO AND labels = example-required-label
    project_repo_map:
      - { project: DEMO, repo: greaveselliott/example-target }
    scope:
      allowed_workspaces_env: JIRA_ALLOWED_WORKSPACES
      required_labels: [example-required-label]
      board_id_env: JIRA_BOARD_ID
    prioritisation:
      scope: active_sprint
      ready_statuses: ["To Do", "Ready for Dev", "Selected for Development"]
      order: [priority, rank, age]
      respect_blocked_by: true

design_sources:
  figma:
    enabled: false
    token_env: FIGMA_TOKEN

delivery:
  enabled: false
  mode: trunk
  branch_pattern: "mars/{ticket}-{slug}"
  min_trust: contributor

Guardrails

Guardrails are YAML policies referenced from manifest roles. Hard rules block operations; advisory rules appear in role context. For full field defaults, matching semantics, secret scanning, git hooks, and troubleshooting, open the Guardrails Reference.

rules:
  - id: no-hardcoded-secrets
    name: No hardcoded secrets
    severity: hard
    scope: global
    pattern: '(?i)(password|secret|api_key|token)\s*[:=]\s*["''][^"'']{8,}'
    message: Do not hardcode secrets. Use environment variables or a secrets manager.
    stale_days: -1

Keep guardrail messages actionable. A blocked role should know what went wrong and what safe remediation command or file change to use.

Knowledge Routes And Skills

Knowledge routes point roles at durable docs. Skills teach recurring procedures. Neither grants authority; tools, trust, and guardrails still come from the manifest and runtime policy.

routes:
  - when: release planning, semantic versioning, changelog, patch notes, or tags
    paths: VERSION, CHANGELOG.md, docs/design-docs/release-versioning.md

---
name: self-improvement
scope: all
---

# Self-Improvement Skill

Use this when a repeated failure suggests the harness should improve itself.

Add routes when context is missing. Add skills when a repeatable workflow should be taught compactly. Add tools only when a repeated deterministic action needs code, validation, and policy.

Secrets And Local Values

Validation Commands

mars doctor --repo .
mars run engineer --repo . --dry-run
mars docsync audit --repo .
go test ./internal/docsconsistency ./internal/docsync

Troubleshooting