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

# Quick Start

> Connect a gateway, add a model provider, and start your first Pioneer thread.

This page assumes Pioneer is installed and the desktop app opens. It takes you through one working thread without requiring the advanced features first.

<Note>
  Start your first agent turns in **Supervised** mode so Pioneer asks before commands and file changes. After you understand the tool timeline, use **Auto-accept edits** or **Full access** only for gateways and projects you trust.
</Note>

## Connect to a gateway

When Pioneer opens, it needs a gateway.

If you installed the desktop app for local use, start the local gateway when the app asks. The UI and gateway then run on the same computer.

If you installed the gateway separately, confirm it is running:

```bash theme={null}
pioneer status
```

For a remote gateway, add a new connection in the desktop app. Use the host and port of the gateway machine, plus a token created on that machine:

```bash theme={null}
pioneer issue-superuser-token
```

Give the connection a name that describes the environment, not the hardware. `Work`, `Study`, `Home`, and `Sandbox` are usually more useful than `ubuntu-4vcpu-nyc`.

<Tip>
  One desktop app can connect to many gateways. Use this to keep environments separate without installing a different client for each one.
</Tip>

## Choose a workspace

Pioneer creates a default workspace automatically on first launch. You can use it for your first thread, or open the workspace selector at the top of the main thread sidebar to create another workspace first.

Use workspaces when you want separate threads, provider keys, MCP servers, skills, tasks, and artifacts inside the same gateway. Use separate gateways when the execution environment itself should be different.

## Add a model provider

Pioneer cannot answer until the gateway has access to at least one model provider.

Use the providers icon in the bottom bar to open **Providers**, then add whichever provider you already use. The connection flow is the same across providers: choose the provider type, enter the required credential or endpoint details, save it for the current workspace on the gateway, then select one of its models in a thread.

Provider settings belong to the current workspace on the gateway, not to the desktop app. If you switch workspace or connect to another gateway later, configure providers there too.

See [Providers](/providers/overview) for the full supported provider list.

## Start your first thread

Create a new thread, choose the provider and model you configured, choose **Supervised** as the permission mode for the first turn, and send something deliberately simple:

```text theme={null}
Explain what you can do in this Pioneer workspace.
```

You should see the answer appear in the thread timeline. If the model uses tools, those tool calls appear as separate events. Open them. The timeline is where you learn what the agent actually did, what it tried, and why something failed.

Once basic chat works, test a read-only tool request:

```text theme={null}
List the files in this workspace root and summarize what kind of project it looks like. Do not modify any files.
```

If that behaves as expected, move slowly toward write operations. Supervised mode will ask before file changes and commands; use a temporary folder or throwaway repository first.

## What to add next

Add capabilities as you need them rather than enabling everything at once.

Use [Skills](/skills/overview) when you want reusable instructions or specialized behavior. Use [MCP servers](/mcp/overview) when Pioneer needs to talk to external tools and systems. Use [Tasks](/tasks/overview) when work should run again later or be broken into subagent-backed steps.

<AccordionGroup>
  <Accordion title="The app cannot connect to the gateway">
    Run `pioneer status` on the gateway host. Check that the service is active, the port is reachable, and you are using the token from the same gateway.
  </Accordion>

  <Accordion title="The provider does not work">
    Recheck the API key, model ID, provider endpoint, region, and network access from the gateway host.
  </Accordion>

  <Accordion title="A tool failed">
    Open the tool event in the timeline. Look at the command, working directory, permissions, timeout, and stderr output.
  </Accordion>

  <Accordion title="A remote gateway sees the wrong files">
    Tools run where the gateway runs. If your desktop app connects to a server, the agent sees the server filesystem, not your laptop filesystem.
  </Accordion>
</AccordionGroup>

## Further reading

* [Gateway Architecture](/architecture/gateway) explains why provider calls and tools run on the gateway host.
* [Permission Modes](/getting-started/permissions) explains which mode to use for supervised, edit-friendly, or full-access turns.
* [Permission System](/architecture/permissions) explains Supervised, Auto-accept edits, Full access, sandbox/resource policy, and approval prompts.
* [Providers Architecture](/architecture/providers) explains how provider adapters turn Pioneer messages into model API calls.
* [Tools Architecture](/architecture/tools) explains shell, web, dynamic, and artifact-facing tools.
* [Agent Loop](/architecture/agent-loop) explains what happens after you send a turn.