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.
Connect Google Workspace (optional)
If you want Ambient to work with Gmail, Google Calendar, and Drive, connect a Google account from Plugins → Install Capabilities → Google Workspace. It is a one-time, five-step setup, and each step shows its own status so you always know what is left. You will need a Google account and a free Google Cloud project to create the OAuth client.
This is a first-party connector, not a generic plugin: Ambient installs a pinned Google Workspace CLI, you supply your own Desktop OAuth client, and the connection is validated with read-only probes before anything depends on it. The card looks like this:
Install the Workspace CLI
Click Install gws. Ambient downloads a pinned, checksum-verified Google Workspace CLI into its managed app data — there is no system-wide install to manage.
Create a Desktop OAuth client
Click Open Google Console and create a Desktop application OAuth client in your own Google Cloud project: configure the consent screen, then download the client_secret JSON. The project, scopes, and consent stay yours.
Import the OAuth client JSON
Click Import OAuth JSON and choose the downloaded client_secret file. Ambient copies it into local, tightly-permissioned storage — you never paste credentials into chat.
Connect your Google account
Click Connect account to start a browser sign-in. You complete Google's login and consent yourself; Ambient never sees your password or 2FA code. The requested scopes cover Gmail, Calendar, and Drive.
Validate connectors
Click Validate. Ambient runs quick read-only probes — list Gmail labels, list calendars, search Drive — and marks the account available once they pass.
What you can do once Google is connected
Gmail
Search and read mail, list labels, and draft messages. Inside Workflows, Google access stays read-only by default.
Calendar
List calendars and search or read events. Event creation is gated and runs as a dry run by default inside Workflows.
Drive
Search files, read and export documents, and materialize files into your workspace through approved file handles.
Multiple accounts
Connect more than one account; when several are present, the agent asks which account a given request should use.
Why create my own OAuth client instead of signing in directly?
Connecting through your own Google Cloud project means the access, scopes, and consent belong to you, and a Desktop OAuth client keeps the credential local to your machine.
Google shows an "unverified app" warning — is that normal?
Yes. While your OAuth client is in testing, Google shows an unverified-app notice and you must be listed as a test user on the consent screen. That is expected for a personal Desktop client.
Validation failed. What should I check?
Re-run Validate. The usual causes are a missing test-user entry, an API not enabled in your Cloud project, or a rotated client secret (download and re-import the new JSON). Each probe reports which connector failed.
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.