Quickstart
Start in the Welcome Folder, finish setup, then run a small calculator task with visible proof.
Main shell
The main Ambient Desktop shell combines chat, workspace context, navigation, and evidence panels in one local developer workstation.
Start in the Welcome Folder
On first launch, Ambient creates a pinned project named Welcome Folder. Open it from the sidebar before starting a real task. The folder is the product-owned first-run curriculum, not a sample project.
The Welcome Folder opens at the Instructions thread and includes two setup threads: Core Setup and Plugin Setup. It also copies product screenshots into the folder so the tour can show the actual shell, Planner Mode, Project Board, Draft Inbox, map view, Git summary, Plugin Manager, and Settings surfaces.
Open the pinned Welcome Folder
Use the folder/project area in the sidebar and select Welcome Folder. If it is already open, stay there for the first session so the screenshots and seeded instructions match the workspace you are using.
Read the Instructions thread
Use it as the live map of the shell: sidebar, composer, Planner Mode toggle, right-side work surfaces, Project Board, Git summary, browser, files, terminal, diffs, and Workflow Recordings.
Keep the Welcome screenshots nearby
The screenshots in the Welcome Folder are the first visual references for this Quickstart. They should match the product UI more closely than abstract diagrams.
Finish Core Setup before relying on web research
Open the Core Setup thread. The live setup card is generated from Ambient's provider catalog and Settings actions, so the buttons you see there are the same product entry points used elsewhere in the app.
Click Start guided setup for the broad first-run path, or use Open Settings when you want to inspect a specific provider, permission, or runtime state. Setup chats are approval-gated: they should not silently install dependencies, bind secrets, download models, activate providers, or change provider selections.
Search, web, and research
Review search providers, scraping, retrieval, and deep research setup. For most developers, the important early check is whether public web extraction can work safely.
MCP runtime and ToolHive
Ambient uses ToolHive as the runtime boundary for MCP workloads. If Docker, Podman, or another supported container runtime is missing or not running, Core Setup should route you through recovery before installing default web capabilities.
Default Scrapling capability
Scrapling is Ambient's reviewed default public web extraction capability. It is installed through a pinned descriptor and ToolHive-managed workload, and individual tool calls still remain permissioned.
Security and access
Provider keys, browser credentials, permission grants, and account integrations stay in Ambient-managed approval surfaces. Do not paste secrets into chat.
Optional: local research setup
Local Research and Local Deep Research should be presented as an expandable path, not as a prerequisite for every first run. Enable it when you want local-first retrieval, managed local model assets, or lower-latency research loops on a machine that can support the runtime.
When should I expand local research setup?
Open it when your task benefits from local-first research, local model routing, or privacy-sensitive retrieval. Leave it collapsed for a normal first calculator task.
What does local research setup check?
It should walk through runtime readiness, managed model assets, llama.cpp availability, provider preference, memory telemetry, validation, and repair steps.
How does this relate to ToolHive and Scrapling?
ToolHive and Scrapling make public web extraction safer. Local Research is a separate optional path for local-first research and model-backed retrieval.
Open Plugin Setup after Core Setup
Plugin Setup is for extension surfaces that are not already covered by Core Setup: curated or imported Codex plugins, Pi packages, custom MCP servers, generated capabilities, and workspace-specific integrations.
Use Open Plugins to inspect installed and importable capabilities. Use Create capability only when the existing catalog does not cover a narrow repeatable job. Generated capabilities should show their command contracts, dependency approvals, secret requests, validation, repair, update, re-registration, and removal actions.
Codex plugins
Curated or imported bundles with skills, apps, and MCP servers.
Generated capabilities
Capability Builder packages that can be previewed, validated, repaired, updated, re-registered, and removed.
Custom MCP
Use this path for custom MCP servers that are not the default Scrapling web research path.
Team integrations
Use plugins or generated capabilities for narrow internal tools with explicit inputs, outputs, secrets, and validation.
Run a calculator task three ways
Use one contained task to learn the product: build a small calculator app with keyboard input, error states, and screenshot proof. Run it in a new folder so it is safe to inspect, delete, or repeat.
Path 1: prompt it
Create a new folder and ask: Build a small calculator app with keyboard input, clear error states, and screenshot proof. Keep the implementation simple and show me the changed files and Git status when done.
Path 2: plan to goal
Switch to Planner Mode first. Ask for the same calculator, answer the required decisions, review the durable plan, then approve implementation from the plan.
Path 3: plan to Project Board
Start in Planner Mode, create a board from the plan, review Draft Inbox cards, accept only the useful cards, run one card, then inspect proof before running the rest.
What to inspect before you trust the result
- Changed files: inspect the files or diff panel rather than trusting the final message alone.
- Screenshot proof: confirm the calculator actually rendered and the UI state is visible.
- Terminal or validation output: check whether commands ran, failed, or were skipped.
- Project Board evidence: if you used the board path, inspect Draft Inbox choices, card proof, and map relationships.
- Git summary: confirm branch, worktree status, changed files, and whether a commit is appropriate.
Quickstart FAQ
Do I need ToolHive before every task?
No. A local calculator task can run without ToolHive. You need ToolHive readiness when using ToolHive-backed MCP workloads such as the default Scrapling public web extraction capability.
What if Core Setup says the container runtime is missing?
Install or start Docker Desktop, Podman, or another supported runtime, then rerun the ToolHive readiness check before installing Scrapling.
Should I start with Project Board?
Use direct prompting for a tiny task. Use Planner Mode when you want decisions recorded. Use Project Board when you want Draft Inbox review, card-level execution, dependencies, and durable proof.