Setup
Set up this machine for MARS.
Install the mars command, make sure your shell can
find it, download the local runtime pieces, and check the machine
is ready. This page explains what gets installed, what gets
downloaded, what stays on disk, and how to repair setup when a
check fails.
Requirements
| Requirement | Why it matters | Check |
|---|
| macOS or Linux | MARS configures Unix-like shells and publishes darwin/linux binaries. | uname -s |
| Git | Source install, target harness review, release notes, and generated docs all rely on git. | git --version |
| Go 1.25.13 or newer for source installs | Source checkout installs build the CLI locally. Packaged MARS operation does not require an externally installed Go toolchain. | go version |
| Disk space | Local GGUF model bundles are large and live under ~/.mars/models/. | df -h ~ |
| Network for setup | Local setup downloads acknowledged llama.cpp/model artifacts; ordinary setup does not contact GitHub for release auth. | mars setup --dry-run |
| GPU recommended | Autonomous coding work is designed for local model throughput. | mars doctor |
Two separate repos:
the MARS source repo installs the software factory. Your
application repo is the target that receives a deployed harness.
Source Install
The day-to-day source development path is make install.
It installs the binary into the Go bin directory and runs the
installed command's shell PATH setup.
git clone https://github.com/greaveselliott/MARS.git
cd MARS
make install
mars version
| Command | Use | User note |
|---|
make install | Normal source checkout install. | Recommended for local development and docs validation. |
make update-tool | Fast-forward a clean source checkout and reinstall. | Fails deliberately on dirty, missing-origin, or diverged checkouts. |
go build -o build/mars ./cmd/mars | One-off local binary. | Use an explicit output path to avoid stale source-root binaries. |
mars version | Confirm installed binary, OS, architecture, commit, and build date. | Run this after install and after updates. |
Avoid stale binary traps:
do not run go build ./cmd/mars; ./mars .... If the
build fails, your shell can still execute an older
source-root binary.
Exact signed-release bootstrap
The bootstrap is implemented for future approved signed tags,
but no supported launch tag exists yet. Once one is published,
independently review a checkout at that exact tag, create an
owner-controlled destination, and run the repository-owned script
from that checkout. Pass the exact stable tag—never
latest, a branch, prerelease, or pseudo-version. A
network-fetched script piped directly into a shell is not a
supported route. Execute ./scripts/install.sh
directly; invoking it through an explicit shell interpreter
fails closed so the privileged Bash shebang can suppress
inherited functions and BASH_ENV.
mkdir -p "$HOME/.local/bin"
chmod 0700 "$HOME/.local/bin"
./scripts/install.sh vX.Y.Z "$HOME/.local/bin"
First bootstrap requires stable Go 1.25.13 or newer. The script
starts the real body in a clean environment carrying only
PATH, HOME, and TMPDIR;
optional GitHub tokens cross through dedicated descriptors,
remain absent from Go, and enter only the staged signed updater;
resolves one absolute Go executable;
disables Go auth and CGO; neutralizes inherited build controls;
applies -modcacherw; validates every resolved temporary-root ancestor; and
builds only the canonical MARS module through the public Go proxy
and SumDB in owner-only temporary staging. The staged command independently
validates its running command/module, exact tag, canonical
SHA-256 h1 sum, and lack of replacements before it
delegates the same tag and destination to the existing signed
updater without ordinary shell-profile mutation. It does not
download, checksum, or verify release archives itself.
Pre-commit rejection leaves an existing destination unchanged;
recovery-required failures instead require preserved transaction
evidence and trusted-source repair. Successful script exit
requires verified staging removal. Ordinary failures retain their
original error and add a fixed path-free warning when cleanup is
incomplete; a post-install cleanup failure reports that the
binary was installed but staging cleanup remains incomplete.
Later packaged operation is Go-free.
Shell PATH
mars path setup detects Fish, Zsh, Bash, POSIX sh,
Ksh, Csh, or Tcsh and writes an idempotent profile snippet so new
terminals can resolve mars. For profile targets,
command-cache repair, shell completions, and automation recipes,
open the Shell Integration Reference.
Repair the current install
mars path setup
hash -r
mars version
hash -r clears a cached command path in many shells.
Preview profile changes
mars path setup --dry-run
mars path setup --dry-run --json
Use this before changing shell profile files on shared or managed machines.
Configure a specific shell or install directory
mars path setup --shell zsh --install-dir "$HOME/go/bin"
Useful when $SHELL does not match the shell users actually open.
Setup Command
mars setup is idempotent. Each step checks whether it
is already satisfied before running. A dry run increments skipped
steps and prints the setup plan without changing local state.
mars setup
mars setup --inference local --local-bundle auto --download --yes --json
mars setup --dry-run
Before a missing llama.cpp archive or GGUF is requested or written,
setup resolves one stable concrete-bundle plan with immutable
identity, exact byte size, license ID/URL, and terms/notice URLs.
Interactive setup displays the plan and confirms once. Non-TTY and
JSON setup require the exact --download --yes form.
JSON emits a complete preflight event on stderr before requests and
includes the same plan in the final stdout object. Decline, missing
acknowledgement, incomplete provenance, or a changed plan causes no
download request or download-artifact write; acceptance is not
persisted as a legal attestation.
| Step | When it runs | Writes |
|---|
| Create directories | Always considered unless dry run. | ~/.mars/ subdirectories. |
| Write default config | When config is missing or needs defaults. | ~/.mars/config.yaml. |
| Detect hardware | During setup. | Hardware profile metadata in local config/state. |
| Configure shell path | When profile is not already configured. | User shell profile snippet. |
| Install llama-server | After acknowledgement for a supported pending local archive. Automatic Linux acquisition remains disabled. | ~/.mars/bin/. |
| Download models | After acknowledgement for the exact pending local bundle; skipped for --skip-download, --test-mode, defer, or cloud routing. | ~/.mars/models/. |
| Optional GitHub integration placeholder | Only with --github and GitHub checks enabled. | Local setup metadata. |
| Flag | User behavior |
|---|
--skip-github | Skip optional GitHub integration checks. Official release access is already separate from ordinary setup. |
--github | Opt into optional GitHub status/check integration setup. |
--skip-download | Skip llama-server and model download steps. Use only when compatible artifacts already exist or inference is deferred/cloud. |
--download | Select the displayed third-party download plan. In non-TTY/JSON mode it must be paired with --yes. |
--test-mode | Skip downloads and external services for test automation. |
--dry-run | Print planned setup steps without executing them. |
--install-dir | Override the directory added to shell PATH. |
--download --yes --json | Acknowledge the exact pending plan without prompting. The preflight plan event is on stderr; the final result object is on stdout. |
GitHub Release Access
mars auth github check first makes one exact,
no-redirect anonymous request to the official
api.github.com release-metadata endpoint. Only an exact
401, 403, or 404 may resolve
optional credentials and retry the same origin and path once. The
result is anonymous, authenticated, or
unavailable. Optional auth remains available for
private forks and rate-limit fallback. For the full credential map, provider keys,
integration env-var names, and secret-scanning recipes, open the
Authentication And Credentials Reference.
Ordinary public check
mars auth github check --json
No credentials are resolved unless the exact official endpoint returns 401, 403, or 404.
Headless path
GH_TOKEN=... mars auth github setup --json
mars auth github check --json
Use environment variables in CI-like setup. Do not print token values.
Custom config path
mars auth github setup --config /private/tmp/mars-config.yaml
mars auth github check --config /private/tmp/mars-config.yaml --json
mars auth github clear-local --config /private/tmp/mars-config.yaml
clear-local removes only that file's stored github_token; it does not change environment, GitHub CLI or GitHub App credentials, repositories, or remote state.
Inference Modes
Setup can prepare local inference, skip local model work for cloud
routing, or defer inference preparation entirely. Target-level
routing is configured later through init, model overrides, and
runtime flags.
| Mode | Setup behavior | Use when |
|---|
local | Default. Plans local llama-server/model artifacts, then downloads only after acknowledgement. Automatic Linux llama.cpp acquisition is unavailable. | You want local-first autonomous work and have a supported managed artifact or independently installed server. |
cloud | Skips local model downloads during setup. | You will configure explicit cloud/provider routing. |
defer | Skips local model downloads during setup. | You want PATH/config/auth first and will choose models later. |
Open the Models And Inference Guide
for routing precedence, model overrides, providers, Ollama, and
evaluation commands.
Local Bundles
A local bundle maps MARS role tiers to model artifacts. The
recommended default is auto, which selects an eligible
bundle for the detected hardware.
| Bundle | User guidance |
|---|
auto | Use the highest-ranked eligible local bundle for the machine. |
local-cpu-q3 | Use for CPU fallback, dry runs, and smaller machines. |
local-balanced-q4 | Use for practical local autonomous work on capable developer machines. |
local-quality-q8 | Use only when VRAM or unified memory can comfortably handle larger models. |
mars setup --inference local --local-bundle auto
mars models eligible --json
mars models list --provider registry --json
Local State
Setup state is machine-local. Keep it out of target repos unless a
specific report intentionally copies sanitized evidence.
| Path | Purpose | Commit? |
|---|
~/.mars/config.yaml | Machine config, local performance tuning, optional private-release token fallback. | No. |
~/.mars/bin/ | Managed helper binaries such as llama-server. | No. |
~/.mars/models/ | Downloaded GGUF model artifacts. | No. |
~/.mars/db/{repo}/mars.db | Per-target queue, telemetry, scores, and runtime state. | No. |
~/.mars-harness/db/mars.db | Shared multi-repo serve database. | No. |
~/.mars/traces/ | Local command logs and traces. | No, unless sanitized into evidence deliberately. |
.harness/.env.local | Ignored target-local provider credentials. | Never. |
.harness/.env.example | Credential environment variable names only. | Yes. |
Open the Files And State
Reference for the full repository and runtime ownership map.
Doctor
mars doctor is the first command to run after setup and
whenever a target behaves strangely. It checks Go, config, models,
database paths, llama-server, disk, release access, update
drift, and target-specific health when --repo is
supplied. Every finding is meant to leave you with the next safe
command or file to inspect.
Machine health
mars doctor
mars doctor --json
Target health
mars doctor --repo /path/to/repo
mars doctor --repo /path/to/repo --db ~/.mars/db/my-repo/mars.db --json
Offline-friendly check
mars doctor --skip-remote
mars update check --repo /path/to/repo --skip-remote
How to read the result
| Status | Meaning | What to do |
|---|
ok | The check has enough evidence for the current command. | Move on. Some repo-only checks report ok with “skipped” when --repo was not supplied. |
warn | MARS found something that may stop setup, agent runs, updates, or evidence quality later. | Read the fix field or the indented fix: line. Warnings do not make doctor exit non-zero. |
fail | A required local precondition is broken, such as missing Go, missing required model weights, or too little disk. | Run the remediation, then rerun mars doctor. Any failed check makes the command exit non-zero. |
JSON output is an array of check results. Each item includes
name, status, message,
duration in nanoseconds, and fix when
MARS has a concrete remediation.
Checks and fixes
| Check | What it proves | Common next action |
|---|
go-version | With --repo selecting the canonical MARS source module, the external Go toolchain is at least 1.25.13. Packaged/default and ordinary target checks report that Go is not required without invoking it. | For source work, install or upgrade Go and rerun mars doctor --repo . |
config-file | ~/.mars/config.yaml or the path passed with --config exists. | Run mars setup if the config file is missing. |
model-registry | Default model entries are pinned by immutable revision and SHA256. | Source maintainers must pin registry entries before release; ordinary users should update MARS if this fails. |
models-dir | The local model directory exists and contains GGUF model files. | Run mars setup or place required .gguf files in ~/.mars/models/. |
profile-required-models | The active performance profile has the model files it needs. | Run mars setup after changing performance_profile. |
profile-ram-footprint | The active model profile appears to fit available RAM with headroom. | If warned, choose a smaller profile in ~/.mars/config.yaml and rerun setup. |
database | The selected SQLite database directory exists. With --repo, the default is ~/.mars/db/{repo}/mars.db. | Run mars setup, mars register --repo ..., or pass a writable --db outside the target repo. |
llama-server | MARS can find llama-server in PATH or ~/.mars/bin/. | Run mars setup for the managed binary, or install llama.cpp yourself. |
disk-space | The machine has at least 5 GiB free where MARS stores local state. | Free disk before downloading models or running release builds. |
release-access | The official release metadata is reachable anonymously or, after an exact access denial, with optional auth; --skip-remote skips it. | Run mars auth github check; configure optional auth only for private forks or a rate-limit fallback. |
version-drift | The installed CLI and, when --repo is supplied, the deployed harness are not behind known releases. | Run the command in the fix field, usually mars update tool or mars update harness --repo .... |
operating-model | A target repo has the generated operating-model docs MARS expects. | Run mars update harness --repo ...; create migration tickets for stale user-owned docs. |
deterministic-remediation | MARS has a matching repair recipe for common target setup failures, and the target harness scaffold has required files. | Run the named init, upgrade, or update command from the fix field. |
role-registry | The target role registry and .harness/manifest.yaml agree. | Run mars init --repo ... for new repos, restore the manifest, or update registry rows for deliberate custom roles. |
active-plan-hygiene | The target has one active plan and its evidence/ticket state is not stale. | Update docs/exec-plans/active/current-operating-plan.md or rerun the named evidence checks. |
ticket-drain | No eligible in-progress ticket has gone stale without a blocker or dependency. | Complete the ticket, move it back to backlog with blocker metadata, or add blocked_by. |
workspace-hygiene | The target worktree does not contain generated-file churn, unsafe deletes, or hygiene issues that would confuse agents. | Run mars tools run workspace_hygiene --repo ... --trust contributor for the detailed recipe, or apply the fix text. |
Common reads
"Skipped" with no repo
A machine-only run skips repo-only checks such as role registry,
active-plan hygiene, ticket drain, workspace hygiene, and target
operating-model health. Add --repo /path/to/repo
when you want target diagnostics.
Database warning on a new repo
A missing per-repo database usually means the repo has not been
registered or started yet. Run mars register --repo ...
or mars start --repo ...; use --db
only when you deliberately keep runtime state elsewhere.
Remote checks during travel or CI
Use --skip-remote when you only want local state:
config, models, database, target files, and local drift. Run
the full check later before update or release work.
Automation Mode
For scripts and validation jobs, prefer JSON output, explicit
repo/config paths, and non-interactive failure modes.
| Need | Pattern |
|---|
| Preview setup without writes. | mars setup --dry-run --json |
| Configure local setup deterministically. | mars setup --inference local --local-bundle auto --download --yes --json |
| Skip external services in tests. | mars setup --test-mode --json |
| Classify release access. | mars auth github check --json |
| Repair PATH predictably. | mars path setup --shell zsh --install-dir "$HOME/go/bin" --json |
| Diagnose a target. | mars doctor --repo /path/to/repo --json |
Recipes
Ordinary source checkout with local models
make install
mars setup
mars doctor
Optional private-fork update auth
gh auth login
mars auth github setup
mars auth github check
mars update check --repo /path/to/repo
Cloud or deferred inference first pass
mars setup --inference defer --json
mars doctor --skip-remote
Fix command not found after install
mars path setup --dry-run
mars path setup
exec "$SHELL" -l
mars version
Troubleshooting
| Symptom | Likely cause | Next action |
|---|
mars: command not found | The install directory is not in the current shell PATH. | Run mars path setup from a shell that can find the binary, open a fresh terminal, or use the full binary path once. |
| Old version still runs. | The shell cached an earlier path or another binary appears earlier in PATH. | Run hash -r, which mars, and mars version. |
| Release access is unavailable. | The anonymous official metadata request failed, or optional credentials were not accepted after an exact access denial. | Run mars auth github check --json; configure credentials only for a private fork or rate-limit fallback. |
| Setup tries to download models on a machine that should not. | Local inference is the default and downloads run unless skipped. | Use mars setup --inference defer --skip-download or --inference cloud. |
| Model download is interrupted. | Network, disk, or artifact availability issue. | Free disk, rerun mars setup, then check mars doctor. |
doctor reports database path problems. | The selected SQLite path is missing, unwritable, or inside a target repo. | Use the default ~/.mars/db/{repo}/mars.db or pass a writable --db outside the worktree. |
| Token appears in output or docs. | Credential handling was done outside the intended path. | Rotate the token, remove it from durable artifacts, and use env vars, GitHub CLI auth, or owner-only local config instead. |