Operate MARS while agents are running.

Start Vs Serve

Choose the runtime mode from the operating need. Both use the same queue, dashboard package, controls, tools, traces, and local inference routing; the difference is scope and default database behavior.

mars start --repo ~/my-project --execution-profile host --acknowledge-host-execution
mars start --repo ~/my-project --dashboard-addr 127.0.0.1:9090 --addr 127.0.0.1:9091 --execution-profile host --acknowledge-host-execution

mars register --repo ~/my-project --remote owner/repo
mars serve --addr 127.0.0.1:9091 --concurrency 2 --db ~/.mars-harness/db/mars.db --execution-profile host --acknowledge-host-execution

Startup Lifecycle

Acknowledged-host mars start is intentionally more than a process launcher. It prepares the target harness, creates a clean initial scaffold commit when needed, registers the repo, reconciles stale or resumable lifecycle state, then either resumes work or seeds the bootstrap role.

1. Resolve target repository

   If --repo is omitted, the current directory is used. MARS rejects runtime DB or log paths that would live inside the target repo.

2. Ensure the deployed harness exists

   In this acknowledged-host path, a missing .harness/manifest.yaml runs the same scaffold as mars init. Generated first-run files are committed as chore(harness): initialize mars harness so agents start from a clean baseline; observer mode fails before target writes.

3. Open the per-repo database

   The default path is ~/.mars/db/{repo-name}/mars.db. Use --db only when you deliberately want another database location outside the repo.

4. Build runtime dependencies

   MARS resolves local configuration, code graph settings, dashboard/control addresses, model endpoint override, local model preflight, and inference tuning.

5. Reconcile lifecycle state

   Existing active jobs, stale recoverable jobs, in-progress tickets, rework states, and deterministic dispositions are resumed before a fresh CEO bootstrap is seeded.

6. Run until stopped

   The worker pool claims jobs, records telemetry and traces, updates the dashboard, and responds to terminal or HTTP controls.

Dashboard

The current dashboard is embedded in the Go binary. It uses server-rendered HTML, embedded static assets, Chart.js, htmx-style interaction, and server-sent events. It is local by default and requires no frontend build step or outbound CDN. Page/login shells, embedded assets, and minimal status are bounded observer views; privileged reads, SSE, and mutations require environment-only MARS_DASHBOARD_CONTROL_SECRET, login, exact Host/Origin, and session CSRF. For endpoint-level request, response, error, and scripting details, use the Dashboard API Reference.

mars start --repo ~/my-project --dashboard-addr 127.0.0.1:9090
open http://localhost:9090

curl -N http://localhost:9090/api/events

Controls API

The dashboard exposes bounded local JSON endpoints for operators and companion UIs. Mutating endpoints require authenticated POST, exact same-origin Origin, and the current session CSRF token. Missing callbacks return a not-implemented response rather than pretending a control succeeded.

Serve-Attached Read APIs

When the dashboard is created by the orchestrator, serve attaches additional read APIs used by the dashboard pages: /api/telemetry, /api/evolution, /api/roles, /api/quality-score, /api/throughput, /api/orchestration, and /api/orchestration/decisions.

Terminal Controls

When start or serve is attached to an interactive terminal, MARS exposes keyboard controls and a status bar. The same operations are available through the dashboard API.

State And Paths

MARS keeps durable runtime state outside target repos by default. Target repositories remain the system of record for plans, tickets, feature contracts, changelogs, and committed work; runtime queues, traces, local model artifacts, and process logs live under ~/.mars/. For a complete ownership and cleanup map, use the Files And State Reference.

Queue And Recovery

The orchestrator is designed to resume useful work and avoid restarting broad jobs blindly. Startup reconciliation inspects jobs, tickets, deterministic dispositions, stale recoverable work, and ambiguous states before deciding what to seed next.

Logs And Traces

Use debug output when you are actively diagnosing a run, and log files when you need a durable artifact outside the repo. Role traces record the turn-level evidence needed for quality, scoring, and troubleshooting.

mars start --repo ~/my-project --debug
mars serve --debug

mars start --repo ~/my-project --log-file ~/.mars/traces/logs/my-project-start.log
mars serve --log-file ~/.mars/traces/logs/orchestrator.log

mars run engineer --repo ~/my-project --trace --debug

mars checks run --repo ~/my-project --name go-test -- go test ./...

mars doctor --repo ~/my-project --json
mars trust --repo ~/my-project

Operator Recipes

mars init --repo ~/my-project
mars doctor --repo ~/my-project --json
mars run engineer --repo ~/my-project --dry-run
mars start --repo ~/my-project --concurrency 1 --execution-profile host --acknowledge-host-execution

mars start --repo ~/my-project \
  --model-endpoint http://127.0.0.1:8088/v1

mars start --repo ~/my-project --dashboard-addr 127.0.0.1:9190 --addr 127.0.0.1:9191
mars start --repo ~/my-project --model-endpoint http://127.0.0.1:8088/v1

Troubleshooting