> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nanoclaw.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick start

> Install NanoClaw, meet your assistant, and try your first conversation — with guidance at each step.

export const SetupCheck = ({children}) => <div className="not-prose setup-check">
    <span className="setup-check-icon" aria-hidden="true">✓</span>
    <div><div className="setup-check-label">Before you continue</div><div>{children}</div></div>
  </div>;

export const TerminalMenu = ({screens}) => <figure className="not-prose setup-terminal">
    <div className="setup-terminal-label">Terminal · illustration</div>
    <div className="setup-terminal-screens">
      {screens.map((screen, index) => <div className="setup-terminal-screen" key={screen.question}>
          {screens.length > 1 && <div className="setup-terminal-order">Prompt {index + 1}</div>}
          <div className="setup-terminal-question"><span aria-hidden="true">◆</span><span>{screen.question}</span></div>
          <ul className="setup-terminal-options">
            {screen.options.map((option, i) => <li key={option} className={i === screen.selected ? 'setup-terminal-selected' : ''}>
                <span aria-hidden="true">{i === screen.selected ? '●' : '○'}</span>
                <span>{option}{i === screen.selected && <span className="sr-only"> (choice for this guide)</span>}</span>
              </li>)}
          </ul>
        </div>)}
    </div>
    <figcaption>Code-based illustration, not a screenshot. Highlighted choices follow this guide; hints and surrounding output are omitted.{screens.length > 1 && " Separate prompts are shown in setup order."}</figcaption>
  </figure>;

By the end of this guide, you'll have an AI assistant running on your computer and answering your messages. You can start talking to it here, then connect a messaging app when you're ready.

You'll copy a few commands into **Terminal**, the app that lets you give your computer written instructions. We'll explain where to put them and what to expect.

**Time to set aside:** Plan for 30–60 minutes to install NanoClaw, connect your AI account, and reach your first terminal conversation. This is a planning allowance; downloads, a new computer, or Windows preparation can take longer. Allow additional time for a messaging app, especially if you need workspace approval.

<Frame caption="An example of your first conversation. Your assistant's wording will vary.">
  <div className="not-prose w-full space-y-4 p-4 sm:p-6">
    <div className="ml-auto max-w-sm rounded-2xl bg-teal-100 px-5 py-3 text-slate-900">
      <p className="mb-1 text-sm font-semibold">You</p>
      <p>Hi! Give me three ideas for a relaxing weekend at home.</p>
    </div>

    <div className="mr-auto max-w-sm rounded-2xl border border-gray-200 bg-white px-5 py-3 text-slate-900">
      <p className="mb-1 text-sm font-semibold">Your assistant</p>
      <p>Try a movie afternoon, cook a new recipe, or spend an hour on a hobby. Would you like help planning one?</p>
    </div>
  </div>
</Frame>

## Before you start

Have these ready:

* **A Mac or Linux computer with at least 4 GB of memory**, an internet connection, and permission to install software. Keep this computer on and connected when you want your assistant to respond.
* **An AI account.** The walkthrough below uses a Claude Pro or Max subscription. Have its sign-in details ready. If you already use another supported option, see the alternatives below.
* **Git**, the tool used to download NanoClaw. You'll check for it in the next step.

NanoClaw installs the other software it needs. If you choose the recommended download during setup, you'll also sign in to a **NanoClaw account**. You can create that account when prompted; it is separate from your AI account.

<AccordionGroup>
  <Accordion title="Using Windows?">
    First follow [Microsoft's WSL installation guide](https://learn.microsoft.com/en-us/windows/wsl/install). WSL lets you run Linux on Windows. Once it is ready, open your Linux app (for example, Ubuntu) and follow this guide there. Allow extra time for that preparation.
  </Accordion>

  <Accordion title="Using ChatGPT or an API key?" id="other-ai-accounts">
    Setup also offers **Codex**, which connects through a ChatGPT subscription or an OpenAI API key. Choose **Codex** at the AI service step. The prebuilt sandbox currently supports Claude only, so if you already chose it, setup asks whether to stop using it and builds a sandbox on your computer instead.

    If you use an Anthropic API key, choose **Claude**, then **Paste an Anthropic API key**. API keys use your provider's usage-based billing. See [AI providers](/extend/providers) for the other options.
  </Accordion>

  <Accordion title="Already installed NanoClaw, or using a server?">
    This walkthrough starts with a new installation. For an existing copy, see [Installation](/installation); for a prebuilt assistant, see [Getting started with a template](/templates/getting-started). If you're moving from v1, follow the [migration guide](/migrate-from-v1) before setup.

    On Linux, use your regular user account. The installer warns about running as root and about Google Cloud virtual machines. See [installation requirements](/installation#requirements) before choosing a server.
  </Accordion>
</AccordionGroup>

## Set up your assistant

<div className="quickstart-walkthrough">
  <Steps>
    <Step title="Open Terminal and check Git" id="open-terminal">
      <Tabs>
        <Tab title="Mac">
          Press **Command + Space**, type **Terminal**, and press **Return**.
        </Tab>

        <Tab title="Linux or Windows with WSL">
          On Linux, open **Terminal** from your applications. On Windows, open the Linux app you installed with WSL, such as **Ubuntu**.
        </Tab>
      </Tabs>

      Copy the command below into that window. Press **Enter** to run it.

      ```bash theme={null}
      git --version
      ```

      <SetupCheck>A line beginning with <code>git version</code> appears. The number after it can vary.</SetupCheck>

      If your Mac offers to install developer tools, follow that prompt, then run the command again. If Git is missing, follow the [Git installation instructions](https://git-scm.com/install/) for your operating system before continuing.
    </Step>

    <Step title="Download NanoClaw and start setup" id="download-and-start">
      These four commands open your home folder, download NanoClaw, open its folder, and start setup. Copy and run **one line at a time**, waiting for each command to finish:

      ```bash theme={null}
      cd ~
      git clone https://github.com/nanocoai/nanoclaw.git
      cd nanoclaw
      bash nanoclaw.sh
      ```

      It checks your computer and installs supporting software. Follow any prompts it shows. On a new Mac, this can include installing Apple's developer tools and entering your computer password.

      Choose **Standard setup**, then **Fresh agent** when the next question appears. Use the arrow keys to move through choices and **Enter** to select one.

      <TerminalMenu
        screens={[
  { question: "How would you like to begin?", options: ["Standard setup", "Advanced"], selected: 0 },
  { question: "How should we create your first agent?", options: ["Fresh agent", "From the NanoClaw template library", "From local templates"], selected: 0 }
]}
      />

      An agent is your AI assistant. You can give it a job and preferences by chatting with it.
    </Step>

    <Step title="Prepare your assistant's workspace" id="prepare-workspace">
      Setup calls this workspace a **sandbox**. It keeps the assistant's working files separate from the rest of your computer.

      Setup asks **Enable Echo’s hardened agent image? Open the perks dashboard in your browser?** Press **Enter** to accept. This is how you get the prepared software.

      <span id="prefer-to-skip-the-nanoclaw-account" />

      **Using Codex or skipping the download account?** Answer no to the browser question. Wait for the local build to finish, then continue to the AI account step. This can take several minutes. See [other AI accounts](#other-ai-accounts).

      For the download option, sign in to NanoClaw in the browser window that opens. You can create an account there. If no browser opens, open the link shown in Terminal.

      If asked to confirm a code, check that it matches the code in Terminal. Once you see the confirmation screen, return to Terminal.

      <Tabs>
        <Tab title="Sign-in screen">
          <Frame caption="Real NanoClaw sign-in screen. Use an existing account or choose Sign up.">
            <img src="https://mintcdn.com/qwibitai-nanoclaw-8/xW_R85ba7XMvZh0L/images/echo/hardened-runtime/signin-02-sign-in.png?fit=max&auto=format&n=xW_R85ba7XMvZh0L&q=85&s=7de879f25e57c539382603e7ee64f095" alt="NanoClaw sign-in page with email, Google, and GitHub options and a Sign up link" style={{ maxHeight: '320px', width: 'auto', maxWidth: '100%', margin: '0 auto' }} width="1020" height="1214" data-path="images/echo/hardened-runtime/signin-02-sign-in.png" />
          </Frame>
        </Tab>

        <Tab title="Confirmation screen">
          <Frame caption="Real NanoClaw confirmation screen. You can return to Terminal.">
            <img src="https://mintcdn.com/qwibitai-nanoclaw-8/xW_R85ba7XMvZh0L/images/echo/hardened-runtime/signin-04-success.png?fit=max&auto=format&n=xW_R85ba7XMvZh0L&q=85&s=ef81351ff654aa100d0ce19f2ee30eb9" alt="NanoClaw confirmation saying You are all set, your device is connected, and you may close the page" width="1020" height="364" data-path="images/echo/hardened-runtime/signin-04-success.png" />
          </Frame>
        </Tab>
      </Tabs>

      <SetupCheck>Keep Terminal open until the download or local build finishes and setup moves on to your AI account.</SetupCheck>
    </Step>

    <Step title="Connect your AI account" id="connect-ai">
      Setup first installs **OneCLI**, the vault that stores your AI sign-in securely.

      For this walkthrough, choose **Claude**, then **Claude subscription**. Follow the browser prompts to connect your AI account. This is separate from the NanoClaw download account.

      If you chose the Codex path, select **Codex** instead and follow its sign-in prompts. See [other AI accounts](#other-ai-accounts).

      <TerminalMenu
        screens={[
  { question: "Which agent runtime should power your assistant?", options: ["Claude", "Codex", "OpenCode"], selected: 0 },
  { question: "How would you like to connect to Claude?", options: ["Claude subscription", "Paste an OAuth token", "Paste an Anthropic API key", "Skip for now"], selected: 0 }
]}
      />

      <SetupCheck>When the browser sign-in finishes, Terminal shows <strong>Done.</strong> after saving your sign-in to the vault. Return to Terminal if you're still in the browser.</SetupCheck>

      When Terminal says **Setting your assistant's access rules…**, setup is configuring which extra folders on your computer can be shared with your assistant. On a fresh installation, that list starts empty. Your assistant still has its own workspace; you do not need to share personal folders to complete this guide. If you already have access rules, setup keeps them.

      This step runs automatically. Wait for **Access rules set.** or **Access rules already set.**, then let NanoClaw start its background service so it can keep running after setup. Enter the name you'd like your assistant to call you when asked.
    </Step>

    <Step title="Have your first conversation" id="first-conversation">
      Setup sends a test message to check your assistant can reply. The first response may take a little time while it starts.

      Choose **Pause here and chat with your agent from the terminal**. This creates the terminal assistant you'll use in this guide. Move down to that option with the arrow key, then press **Enter**.

      <TerminalMenu
        screens={[
  { question: "What next?", options: ["Continue with setup", "Pause here and chat with your agent from the terminal"], selected: 1 }
]}
      />

      Type a message such as:

      ```text theme={null}
      Hi! Give me three ideas for a relaxing weekend at home.
      ```

      Press **Enter** to send it.

      <SetupCheck>Your assistant replies beneath your message. You can send another message at the next prompt.</SetupCheck>

      When you're ready to finish setup, leave the next message empty and press **Enter**. Follow the timezone prompt if one appears.
    </Step>

    <Step title="Finish setup, with messaging now or later" id="finish-setup">
      At the channel question, choose **Skip for now** to keep using the terminal assistant you just created. A channel is a way to message an assistant, such as Telegram or Slack.

      <Accordion title="Want to connect a messaging app now?">
        Choose an app and have the following ready:

        * **[Telegram](/channels/telegram):** A Telegram account. Setup walks you through creating a bot with @BotFather, pasting its token into Terminal, and sending a pairing code to your bot.
        * **[Slack](/channels/slack):** A Slack workspace where you can install an app, or an administrator who can approve it. Setup offers to create the app for you, with a manual setup option if needed.
        * **[WhatsApp](/channels/whatsapp):** Your phone with WhatsApp signed in. Open **Linked Devices** to link NanoClaw using a QR code or pairing code.

        For other apps, see the [channel guides](/channels/overview).

        Follow the final instructions for that app: some require you to send the first message. A messaging app can connect to a different assistant from the one you met in Terminal.
      </Accordion>

      <SetupCheck>If you skipped the channel question, Terminal ends with <strong>You're ready! Chat with <code>pnpm run chat hi</code>.</strong> If you connected a messaging app, it ends with <strong>You're set.</strong> and tells you to look for a welcome message in that app. If setup reports a problem instead, follow its recovery instructions before continuing.</SetupCheck>

      To send another message later, run this from the same Terminal window, still in the `nanoclaw` folder:

      ```bash theme={null}
      pnpm run chat "Help me plan one of those weekend ideas."
      ```

      This sends one message and prints the reply. Run it again with different text for your next message.

      If you open a new Terminal window later, run `cd ~/nanoclaw` first. If Terminal cannot find `pnpm`, see [command not found](#command-not-found) below.
    </Step>
  </Steps>
</div>

## Things to try first

Replace the text inside the quotes in the command above, or send a message in your connected app:

* **Plan something:** “Help me make a shopping list for a dinner for two.”
* **Set a preference:** “Please keep your answers short and use bullet points.”
* **Explore a topic:** “Find three beginner resources for learning to grow herbs.”

<Note>
  Keep the computer running NanoClaw on and connected to the internet. To receive reminders as notifications on your phone, [connect a messaging app](/channels/overview). Terminal chat only displays replies while its command is running.
</Note>

## If you get stuck

<AccordionGroup>
  <Accordion title="Terminal says command not found" id="command-not-found">
    If the missing command is `git`, return to [the Git check](#open-terminal).

    If setup finished but Terminal cannot find `pnpm`, open a new Terminal window so it can pick up the newly installed tools. Run `cd ~/nanoclaw`, then retry your message command. On Windows, reopen your Linux app.

    If that does not help, or setup did not finish, follow the error shown by setup or use the [troubleshooting guide](/operate/troubleshooting).
  </Accordion>

  <Accordion title="A nanoclaw folder already exists">
    Don't delete it to repeat the download. It may contain an existing assistant. See [Installation](/installation) to continue from your existing copy.
  </Accordion>

  <Accordion title="Setup stopped or sign-in did not finish">
    Follow the recovery prompt in Terminal. If you need to restart setup, run `bash nanoclaw.sh` again from the same `nanoclaw` folder. If asked what to do with the existing installation, choose **Keep it & continue setup**.

    Still stuck? Ask in [Discord](https://discord.gg/VDdww8qS42) with the step name and error message. Leave out passwords, keys, and sign-in codes.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Message from your favorite app" icon="comments" href="/channels/overview">
    Connect a messaging app so you can reach an assistant from your phone.
  </Card>

  <Card title="Give your assistant a job" icon="wand-magic-sparkles" href="/guides/customize-an-agent">
    Set its preferences and standing instructions.
  </Card>
</CardGroup>

For technical details about what was installed and where its files live, see [Installation](/installation).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.