Use Poolside Assistant for desktop

Poolside Assistant for desktop is an Agent Client Protocol (ACP) client for coding agents. Use it outside your editor to work across projects, run tasks in Git worktrees, use built-in terminals, and review changes.

Poolside Assistant is separate from Poolside Enterprise Assistant, the enterprise extension.

Key features

ACP agents: Use Poolside Agent or connect another ACP-compatible agent.
Consistent experience: Use the same assistant experience available in the Poolside Assistant extensions for VS Code and Visual Studio.
Desktop workflows: Manage larger changes with Git worktrees, built-in terminals, and change review tools.
Multiple projects: Work across multiple projects in one window with per-project settings.
GitHub integration: Connect GitHub in Settings > GitHub for pull request awareness and status colors.
MCP servers: Add integrations for services such as GitHub, Linear, Notion, Sentry, Hugging Face, and PostgreSQL from Connectors.
On-device models: Download and run supported models on your Mac.
Remote access: Access the desktop app from your phone (experimental).
Voice input: Dictate prompts instead of typing them.

Install

Prerequisites

You have a Mac with Apple Silicon.

Steps

Go to poolside.ai/get-started and download the Poolside Assistant for desktop .dmg file.
Open the .dmg file and drag Poolside to Applications.
Launch Poolside from Applications.
Open a project.

Poolside Assistant installs and updates its own copy of Poolside Agent, separate from any Poolside Agent CLI installation. Both use the same Poolside configuration.

Start your first task

Poolside Agent is available by default. Sign in to connect it to Poolside models, then start your first task. Prerequisites

You installed Poolside Assistant for desktop and opened a project.

Steps

Click New conversation.
In the conversation tab, click Log in to Poolside.
Complete the login flow in the terminal that opens. For help choosing an access method, see Log in to Poolside.
Return to the conversation tab and click I’m logged in.
Confirm the agent, model, and effort, then describe your task in the prompt input box.

The agent may ask for approval before it reads files, runs commands, or edits code. Review proposed actions and changes before you approve or keep them.

Work with your agent

Type / in the prompt input box to open commands and session controls. Available commands depend on the selected agent.
Type $ in the prompt input box to open skills when the selected agent or workspace provides them. For more information, see Skills.
Mention relevant files, folders, and other project details in your prompt to give the agent context.
Use the prompt controls to change the mode, model, effort, or voice input before you send a prompt. Available controls depend on the selected agent.
Use the prompt controls or the /agent menu to change agents. Switching agents starts a new session and does not carry over the current conversation.
Review changes before you keep them. Approve commands and tool use only when you understand what the agent is about to do.

Use another ACP-compatible agent

Poolside Assistant includes third-party agent harnesses tested by Poolside and other ACP agents from the public registry. Prerequisites

You installed Poolside Assistant for desktop.

Steps

Navigate to Settings > Agents.
Choose an agent under Tested by Poolside or Other Third-Party Agents.
Click Install if the agent is not already enabled.
Start a new conversation and select the agent from the prompt controls.

Third-party agents run local code from their publisher. Install only agents you trust and review the command or binary before installation.

Configure a custom ACP agent

Use assistant.json when you need Poolside Assistant to run a custom ACP executable that is not available in the public registry. Configuration file locations

macOS and Linux: ~/.config/poolside/assistant.json
Windows: %USERPROFILE%\.config\poolside\assistant.json
Custom XDG directory: $XDG_CONFIG_HOME/poolside/assistant.json

The file uses strict JSON and does not support comments.

Add a custom agent

Add the agent to agent_servers. The entry’s key is the name that appears in Poolside Assistant.

{
  "agent_servers": {
    "my-agent": {
      "type": "custom",
      "command": "my-agent",
      "args": ["acp"]
    }
  }
}

The command value can be an executable on your PATH or an absolute path. Poolside Assistant starts the executable directly and passes each args item without interpreting shell syntax. If the command requires shell syntax, invoke the shell explicitly.

Configuration fields

Field	Type	What it’s for
`agent_servers`	object	Maps the names shown in Poolside Assistant to agent configurations.
`default_agent_server`	string	Selects the agent for new conversations. Defaults to `poolside`.
`type`	`custom`, `registry`, or `local`	Defines how Poolside Assistant manages the agent. A custom entry can omit this field.
`command`	string	Sets the executable name or path for a custom agent. Required for custom agents.
`args`	string array	Passes arguments to the custom agent.
`env`	string map	Adds environment variables to the agent process.
`default_config_options`	string map	Sets agent-defined defaults for new sessions.

Values in default_config_options must match the option IDs and values advertised by the agent.

Values in env are stored as plain text in assistant.json. Do not store API keys, tokens, or other secrets there. Use the agent’s login flow, inherited environment, or Poolside connectors instead.

Apply changes

Restart Poolside Assistant after you edit assistant.json manually. Changes made through Settings > Agents stop the affected agent process automatically. Malformed JSON does not prevent Poolside Assistant from starting. It continues with the last loaded agent configuration and shows an error above the prompt input box. Fix the file, then select Retry in the error message.

Run a model on your device

Poolside Local runs supported models on your Mac with the MLX framework instead of connecting to a hosted model. Prerequisites

You installed Poolside Assistant for desktop.
Your Mac has enough disk space and memory for the model you want to download.

Steps

Navigate to Settings > On-Device Models.
Download a model:
- Under Recommended Models, review Fit, estimated memory, and download size, then click Download.
- Under Hugging Face models, search for an MLX model, select it, and click Download.
Start a new conversation.
In the prompt controls, select Poolside Local as the agent, then select the model you downloaded.

Poolside Assistant stores downloaded models in ~/.config/poolside/models. Some gated and private Hugging Face models require you to add the Hugging Face connector and sign in before downloading them.

​Key features

​Install

​Start your first task

​Work with your agent

​Use another ACP-compatible agent

​Configure a custom ACP agent

​Add a custom agent

​Configuration fields

​Apply changes

​Run a model on your device

​Related resources

Key features

Install

Start your first task

Work with your agent

Use another ACP-compatible agent

Configure a custom ACP agent

Add a custom agent

Configuration fields

Apply changes

Run a model on your device

Related resources