diff --git a/docs/user-guide/getting-started/configure-settings.md b/docs/user-guide/getting-started/configure-settings.md index 5ca88d7..a8f470e 100644 --- a/docs/user-guide/getting-started/configure-settings.md +++ b/docs/user-guide/getting-started/configure-settings.md @@ -1,6 +1,6 @@ --- title: Configure Settings -sidebar_position: 2 +sidebar_position: 3 --- Use this page to set the storage location, network behavior, and browser-chat defaults. Keep the changes small, apply them, and prove the server still responds before you move on. @@ -22,7 +22,9 @@ Before you start, open the native Pico AI Server app and keep a terminal ready s - `Port` - `Allow Cross-Origin Resource Sharing (CORS)` - `Enable Bonjour broadcasting` -6. Click `Apply Changes` after network or port changes. +6. In `Server Mode`, set `Open at Login` and `Prevent automatic sleep while Pico is running` if you want. + These two options are configured here rather than during first-run setup. `Open at Login` starts Pico when you log in; `Prevent automatic sleep while Pico is running` keeps the Mac awake so the server stays reachable. +7. Click `Apply Changes` after network or port changes. The app saves the configuration and restarts the server. ## Verify it worked diff --git a/docs/user-guide/getting-started/connect-a-client.md b/docs/user-guide/getting-started/connect-a-client.md index b33b944..a243307 100644 --- a/docs/user-guide/getting-started/connect-a-client.md +++ b/docs/user-guide/getting-started/connect-a-client.md @@ -1,6 +1,6 @@ --- title: Connect a Client -sidebar_position: 3 +sidebar_position: 4 --- Use this page when another app needs to talk to Pico AI Server. The job is to copy the right server address, choose the correct compatibility layer, and prove the client can list models before you try chat. diff --git a/docs/user-guide/getting-started/first-run-setup.md b/docs/user-guide/getting-started/first-run-setup.md new file mode 100644 index 0000000..6ce04ba --- /dev/null +++ b/docs/user-guide/getting-started/first-run-setup.md @@ -0,0 +1,61 @@ +--- +title: First-Run Setup +sidebar_position: 2 +--- + +The first time you launch Pico AI Server, a setup wizard walks you through four pages — **Welcome**, **Model**, **Access**, and **Ready**. By the end you have chosen who can reach the server and the server is running; if you picked a model, it is downloading or already ready (you can also skip that step and add a model later). This page explains each page so you know what every choice does. + +You can change every choice later in the app's Settings window, so pick sensible defaults now and move on. + +## Walk through the wizard + +1. Launch Pico AI Server. +2. On the **Welcome** page, review the summary and continue. + This page introduces Pico AI Server and links to the privacy policy and terms. +3. On the **Model** page ("Choose your first model"), pick a model (or skip it), then continue. + - Pico shows a short list of options — such as **Fast**, **Balanced**, and **Reasoning** — sized for your Mac's memory. + - One selectable option is preselected and marked **Recommended** for this Mac; the page subtitle names it (for example, "Balanced is recommended for this Mac. You can add or switch models later."). + - Each selectable option shows its model name and total download size. An option that isn't available yet is labeled **Coming soon**, and one that needs more memory than your Mac has shows its RAM requirement instead — neither can be selected. + - For a selectable option, the continue button reflects your choice: **Download _tier_ · _size_** for a model that is not on disk yet, or **Use _tier_** for one you already have. + - You can continue without choosing. If no model is available yet, Pico asks you to confirm, and you can download one later in Settings. +4. On the **Access** page ("Choose who can connect"), pick one option, then continue. + - **This Mac only** — the most private choice. Only apps on this Mac can connect. Pico binds to `127.0.0.1`. + - **Devices on my local network** — any device on your network can use Pico. Pico binds to `0.0.0.0`. + - When you choose local-network access, a **Make Pico discoverable automatically** toggle appears. Turn it on to advertise the server over Bonjour so Pico clients and other Pico servers can find it without typing an address. +5. On the **Ready** page, review the live server details, then select **Open Chat**. + - The page shows the real server state: a status dot, the model you chose (when you picked one), the access scope you chose, and the server address. + - Select the copy button next to **Address** to copy the server address. + - **Open Chat** finishes setup, applies your choices, and opens the browser chat. If a model download is still in progress, Pico opens a page that tracks the download instead. + +After you finish, Pico stays in the menu bar. Use its icon to open chat, view memory, or change settings. + +## Verify it worked + +When the Ready page reports the server is running, confirm the API answers: + +```bash +curl http://127.0.0.1:11434/v1/models +``` + +If you get a JSON response, the server is up. If you chose **Devices on my local network**, also ask the server for the address to share with other devices: + +```bash +curl http://127.0.0.1:11434/ip +``` + +## Troubleshooting + +- **Symptom:** The Model page lists fewer options than you expected. + **Cause:** The available tiers depend on your Mac's memory; an 8 GB Mac is offered only the smallest tier. + **Fix:** Choose an available tier now, then add larger models later from the `Models` tab in Settings. +- **Symptom:** A download fails during or after setup. + **Cause:** A network interruption or an unreachable model repository. + **Fix:** Pico shows a **Download Failed** alert. Dismiss it and start the download again from the `Models` tab in Settings. +- **Symptom:** The Ready page shows the server address, but another device cannot connect. + **Cause:** You chose **This Mac only**, so the server is not exposed on the LAN. + **Fix:** Reopen setup or open Settings and switch to **Devices on my local network**, then test again. See [LAN Sharing Basics](../networking/lan-sharing-basics.md). + +## Next steps + +- [Configure Settings](./configure-settings.md) +- [Connect a Client](./connect-a-client.md) diff --git a/docs/user-guide/getting-started/install-and-run-pico-ai-server.md b/docs/user-guide/getting-started/install-and-run-pico-ai-server.md index f2c30dd..10764d4 100644 --- a/docs/user-guide/getting-started/install-and-run-pico-ai-server.md +++ b/docs/user-guide/getting-started/install-and-run-pico-ai-server.md @@ -10,16 +10,17 @@ Pico AI Server is a macOS app for Apple Silicon Macs — it runs models with MLX ## Start the server 1. Launch Pico AI Server. -2. Complete the first-run flow. - The onboarding flow can set `Allow local network connections`, `Broadcast Bonjour`, `Open at login`, and `Prevent sleep`. +2. Complete the first-run setup. + The setup wizard has four pages — Welcome, Model, Access, and Ready. It downloads the model you pick (you can skip and add one later), lets you choose who can connect, and starts the server for you. For a step-by-step walkthrough, see [First-Run Setup](./first-run-setup.md). 3. Open the WebUI at `http://127.0.0.1:11434/`. - The onboarding flow normally opens this address for you after setup. + The setup wizard normally opens this address for you when you finish. 4. If you want LAN access, leave `Allow local network connections` on. With that setting on, Pico AI Server binds to `0.0.0.0`. 5. If you want local-only access, turn `Allow local network connections` off in the native app settings. With that setting off, Pico AI Server binds to `127.0.0.1`. 6. Use the menu extra when you need quick control. When the server is running, it shows the status, a `Start` or `Stop` button, and an IP-based server address with a copy button. + The `Memory` section breaks down memory usage across `Apps`, `MLX`, and `Free` with a bar and legend, and shows a memory `Pressure` indicator. Use the `GB`/`%` button in the `Memory` header to toggle the legend between gigabytes and percentages. ## Verify it worked diff --git a/sidebars.ts b/sidebars.ts index cc1d666..03ee979 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -12,6 +12,7 @@ const sidebars: SidebarsConfig = { label: 'Getting Started', items: [ 'user-guide/getting-started/install-and-run-pico-ai-server', + 'user-guide/getting-started/first-run-setup', 'user-guide/getting-started/configure-settings', 'user-guide/getting-started/connect-a-client', ],