Skip to main content
This page assumes Pioneer is installed and the desktop app opens. It takes you through one working thread without requiring the advanced features first.
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.

​
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:
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:
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.
One desktop app can connect to many gateways. Use this to keep environments separate without installing a different client for each one.

​
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 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:
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:
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 when you want reusable instructions or specialized behavior. Use MCP servers when Pioneer needs to talk to external tools and systems. Use Tasks when work should run again later or be broken into subagent-backed steps.
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.
Recheck the API key, model ID, provider endpoint, region, and network access from the gateway host.
Open the tool event in the timeline. Look at the command, working directory, permissions, timeout, and stderr output.
Tools run where the gateway runs. If your desktop app connects to a server, the agent sees the server filesystem, not your laptop filesystem.

​
Further reading

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