<!-- source: https://deepwiki.com/qhkm/zeptoclaw/2.2-quick-start-guide -->

# Quick Start Guide

- CHANGELOG.md
- README.md
- deploy/homebrew/zeptoclaw.rb
- landing/zeptoclaw/docs/src/assets/logo.svg
- landing/zeptoclaw/docs/src/content/docs/concepts/tools.md
- landing/zeptoclaw/docs/src/content/docs/getting-started/introduction.md
- landing/zeptoclaw/docs/src/content/docs/reference/environment.md
- landing/zeptoclaw/docs/src/content/docs/reference/tools.md
- landing/zeptoclaw/docs/src/styles/custom.css
- landing/zeptoclaw/index.html
- src/cli/config.rs
- src/cli/mod.rs
- src/cli/onboard.rs
- src/config/validate.rs

This guide walks you through installing ZeptoClaw, running the onboarding wizard, and executing your first agent interaction. It covers the minimal path from installation to a working agent. For detailed installation options, see [Installation](/qhkm/zeptoclaw/2.1-installation). For comprehensive configuration reference, see [Configuration Basics](/qhkm/zeptoclaw/2.3-configuration-basics).

## Prerequisites

Before installing ZeptoClaw, ensure you have:

- Operating System : macOS (x86_64/aarch64) or Linux (x86_64/aarch64).
- API Key : At least one LLM provider API key (Anthropic, OpenAI, or OpenRouter recommended).
- Disk Space : ~20MB for binary and config directory.
- Network : Internet connection for LLM API calls.

## Installation Quick Path

Choose one installation method:

After installation, verify the binary:

```

```

**Sources:** [README.md84-96](https://github.com/qhkm/zeptoclaw/blob/2c743d31/README.md?plain=1#L84-L96) [src/cli/mod.rs41-43](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L41-L43) [src/cli/mod.rs158](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L158-L158)

## Onboarding Wizard

ZeptoClaw provides an interactive setup wizard via `zeptoclaw onboard` [src/cli/mod.rs52-59](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L52-L59) that creates your configuration directory, configures LLM providers, and optionally sets up channels and advanced features.

### Express Mode (Default)

Express mode runs a streamlined wizard focusing on essential setup:

```

```

**Express Mode Flow:**

```

```

**Sources:** [src/cli/onboard.rs17-111](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/onboard.rs#L17-L111) [src/cli/onboard.rs114-141](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/onboard.rs#L114-L141) [src/cli/onboard.rs196-206](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/onboard.rs#L196-L206)

### Full Wizard

For advanced setup including channels, heartbeat, and runtime configuration:

```

```

The full wizard includes detailed steps for:

1. Provider Selection : Choose AI providers (Anthropic/OpenAI/OpenRouter/etc.) src/cli/onboard.rs 17-55
2. API Key Entry : Configure provider credentials with validation src/cli/onboard.rs 58-64
3. Model Selection : Live fetching and sorting of models by relevance src/cli/onboard.rs 144-176
4. Personality Setup : Select AI behavior preset (via SOUL.md ) src/cli/onboard.rs 8-9
5. Runtime Isolation : Choose shell execution sandbox (Docker, Landlock, etc.) src/cli/onboard.rs 9

**Sources:** [src/cli/onboard.rs17-123](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/onboard.rs#L17-L123) [src/cli/onboard.rs144-190](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/onboard.rs#L144-L190)

## First Agent Interaction

### CLI Agent Mode

After onboarding completes, run your first agent interaction. By default, streaming is enabled [src/cli/mod.rs71-73](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L71-L73)

```

```

**Implementation Details:**

- Entry Point : cmd_agent in src/cli/agent.rs handles the CLI interaction loop.
- Workspace : Defaults to the Current Working Directory (CWD) in CLI mode to allow relative path resolution for tools.
- Feedback : Uses ShimmerSpinner src/cli/mod.rs 27 to show progress on stderr while thinking and executing tools.

**Sources:** [README.md121-126](https://github.com/qhkm/zeptoclaw/blob/2c743d31/README.md?plain=1#L121-L126) [src/cli/mod.rs64-80](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L64-L80)

### Tool Approvals

In `assistant` mode, ZeptoClaw prompts for approval before executing sensitive tools [src/cli/mod.rs77-79](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L77-L79)

```

```

**Sources:** [README.md78](https://github.com/qhkm/zeptoclaw/blob/2c743d31/README.md?plain=1#L78-L78) [src/cli/mod.rs77-79](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L77-L79)

## CLI to Code Entity Mapping

**Command dispatch and Agent execution flow:**

```

```

**Sources:** [src/cli/mod.rs40-47](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L40-L47) [src/cli/mod.rs64-80](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L64-L80) [src/cli/onboard.rs9-10](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/onboard.rs#L9-L10)

## Common Next Steps

### View Available Tools

```

```

Shows all built-in tools (32+) and indicates if they are configured. Opt-in tools like `grep` and `find` are highlighted [src/cli/mod.rs148-151](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L148-L151)

**Sources:** [landing/zeptoclaw/docs/src/content/docs/concepts/tools.md28-61](https://github.com/qhkm/zeptoclaw/blob/2c743d31/landing/zeptoclaw/docs/src/content/docs/concepts/tools.md?plain=1#L28-L61) [src/cli/mod.rs148-151](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L148-L151)

### Check System Status and Config

```

```

`status` displays active configuration and configured providers [src/cli/mod.rs160](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L160-L160) `config check` runs diagnostics using `validate_config` [src/config/validate.rs182-196](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L182-L196) to find unknown fields or SSRF risks.

**Sources:** [src/cli/config.rs19-38](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/config.rs#L19-L38) [src/config/validate.rs11-48](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L11-L48)

### Troubleshooting Quick Tips

- Missing Provider : Check if ZEPTOCLAW_PROVIDERS_<NAME>_API_KEY is set or run zeptoclaw onboard src/cli/onboard.rs 42-48
- Config Errors : Run zeptoclaw config check . It uses Levenshtein distance src/config/validate.rs 118-140 to suggest correct field names via suggest_field src/config/validate.rs 143-150 if you have typos.
- Coding Tools : If grep / find are missing, use --template coder or set tools.coding_tools: true in config.json src/cli/mod.rs 61-63

**Sources:** [src/config/validate.rs118-150](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L118-L150) [src/cli/onboard.rs42-48](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/onboard.rs#L42-L48) [src/cli/mod.rs61-63](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L61-L63)
