Quickstart

Set up aidashos on your Mac.

Both paths run the same checked-in scripts. Large model downloads and interactive subscription sign-ins stay under your control.

Two commands

install aidashos

$ git clone https://github.com/rahul-nath/aidashos.git && cd aidashos && make

$ ./scripts/boot/boot.sh

make prepares the toolchain and local ledger. The boot lane then walks through llama.cpp, model weights, interactive subscription sign-ins, configuration, and a final readiness check.

Hand your local agent these prompts to install aidashos

Copy these prompts in order. They inspect first, ask before large downloads, and hand interactive sign-ins back to you.

Boot the stack

Checks for a checkout, then runs the boot sequence: local models, subscription sign-ins, configuration, and verification.

Read the prompt

Help me set up aidashos, a local-first agent OS.
First inspect the current workspace for an existing aidashos checkout and preserve any local changes.
If there is no checkout, ask me which parent directory to use, then clone https://github.com/rahul-nath/aidashos.git into a new aidashos directory there.
Never overwrite, delete, reset, or repurpose an existing directory; if that destination exists, ask me to select the existing checkout or choose another location.
Work from the verified checkout root.
Read scripts/boot/README.md and docs/onboarding/ONBOARDING.md before acting.

Then complete the boot sequence:

1. Run ./scripts/bootstrap.sh --check-only and report what is missing.
2. If uv or the Python environment is not ready, run `make` and wait for it to finish.
3. Run the boot stages one at a time from scripts/boot/, in numeric order (10-check-prereqs.sh, 20-install-llama-cpp.sh, 30-fetch-model-qwen3.sh, 31-fetch-model-gemma4.sh, 40-login-anthropic.sh, 41-login-chatgpt.sh, 50-set-default-stack.sh, 60-verify-boot.sh), rather than boot.sh, so each failure is visible and fixable.
4. Stages 30 and 31 download model weights and are the only slow, large steps. Before each, run `./scripts/download-models.sh --list` to show me exactly which repository and file it will fetch, and wait for my confirmation.
5. The two sign-ins are interactive browser flows. Hand control to me for them and never enter credentials yourself.
6. If a stage fails, read its output: every blocked line prints the command that fixes it. Fix, then re-run the stage; all stages are idempotent.
7. Finish by running ./scripts/boot/60-verify-boot.sh and show me its full output.

Start the runtime and prove it

Brings the resident services up, re-checks readiness, and compiles the example design document into a governed plan.

Read the prompt

The aidashos boot sequence finished on this machine. Bring the system up and prove it works:

1. Run ./scripts/start-agent-runtime.sh. It exits non-zero naming any service that failed to come up; report what started.
2. Run ./scripts/first-run-check.sh and show me the report.
3. Compile the example design document into a governed plan: uv run agent-ledger compile_design_doc docs/examples/work_unit_acceptance_design_doc.md. Show me the compiled milestones.
4. Run uv run pi /ledger and summarize the current state.
5. Stop there. Approving a plan and dispatching work are my decisions; tell me the exact commands (uv run pi /approve-most-recent, uv run pi /dispatch) and what each will do, then wait.

Attach your own AI tool

Connects Claude Code, Codex, or any MCP client to the coordination ledger, so your daily driver can operate the OS.

Read the prompt

Connect my AI coding tool to the aidashos coordination ledger over MCP.

1. Read skills/operate-agent-os/SKILL.md and docs/AGENT_MANUAL.md in this repo.
2. If my tool is Claude Code: the repo ships .mcp.json, so open a session in the repo root and confirm the agent-os server's tools are listed.
3. If my tool is Codex: show me the [mcp_servers] block from the SKILL file, wait for my approval, then add it to ~/.codex/config.toml.
4. For any other MCP client: the server command is `uv run agent-ledger --root <repo> serve`, stdio transport.
5. Verify the connection by calling read_execution_ledger, describe_resident_loops, and list_dispatch_intents, and summarize what they say about this machine.
6. From now on, prefer the ledger tools for reading system state, and drive workflows with the pi commands described in the SKILL file.

Attach your cockpit

Use the AI tool you already reach for

Claude Code

Open it at the repository root. The checked-in .mcp.json offers the local agent-os server.

Codex or another MCP client

Add the stdio configuration from the operator skill, using the absolute path to your AiDashOS checkout.

Paste into AGENTS.md, CLAUDE.md, or your equivalent project instructions

When a task needs durable state, separate implementation and review, operator approvals, recovery, or evidence that must survive this session, route it through AiDashOS and follow <AIDASHOS_ROOT>/skills/operate-agent-os/SKILL.md.

Use a direct single pass for a bounded local change.

Read the operator skill Read every setup stage

Developer preview boundaries

macOS is supported. Linux is expected to work but is not exercised on a schedule. Windows is not supported.
The default frontier path uses logged-in Codex and Claude Code CLIs. Their subscription limits still apply.
A local model is required for the junior tier. Automatic all-local senior and staff fallback is not shipped yet.
Durable state survives a stopped process. An agent can still lose its uncommitted context and need a new attempt.