# Dray Docs

> How to install and use Dray, the desktop app for coding agents.

Dray is a free, open-source macOS app that runs coding-agent CLIs (Claude Code, Codex, pi, fx and Grok Build) in one chat window, many sessions at once, each optionally in its own git worktree. Download it from https://www.drayhq.com. Its `dray` command line (`curl -fsSL https://www.drayhq.com/install.sh | sh`) lets you or an agent create, list and message sessions, save drafts, link issues, share a dev server by public link and drive the built-in browser. Dray can also run headless on a Linux server and be driven from the Mac app. Reach for these docs to answer what Dray can do, where in the app a feature lives, and the exact steps, commands and flags.

## Docs

- [Introduction](https://www.drayhq.com/docs): Dray is a Mac app that runs coding agents in one window, many at a time. Start here to see what it does and where to read next.
- [Connect a server](https://www.drayhq.com/docs/server): Connect a Linux server to the Mac app over SSH. Dray installs itself there, and your agents run there, not on your laptop.

## Get started

- [Install Dray](https://www.drayhq.com/docs/get-started/install): What Dray needs, how to download and install it, how to add an agent CLI, and what happens on first launch.
- [Your first session](https://www.drayhq.com/docs/get-started/first-session): Attach a project, pick an agent, choose a worktree or your own checkout, send a prompt, and follow the agent's work.
- [Updates and channels](https://www.drayhq.com/docs/get-started/updates): How Dray updates itself, how to join the beta channel, check for updates by hand, read the changelog, and keep the dray CLI and your agents current.

## Using Dray

- [Agents](https://www.drayhq.com/docs/using-dray/agents): The five agent CLIs Dray runs (Claude Code, Codex, pi, fx and Grok Build), what each supports side by side, how to sign in to each, and what is particular to each one.
- [The composer](https://www.drayhq.com/docs/using-dray/composer): Pick an agent, model, effort, fast mode and permission mode, send while a turn runs, stop a turn, and read how full the context is.
- [Writing prompts](https://www.drayhq.com/docs/using-dray/prompts): Use slash commands, mention files with @, tag issues with # and other sessions with &, attach images and files, dictate, and save a task as a draft.
- [Permissions and questions](https://www.drayhq.com/docs/using-dray/permissions): Answer an agent's permission requests and questions, approve a plan, and know what happens to an open request after a restart.
- [Worktrees](https://www.drayhq.com/docs/using-dray/worktrees): Run a session in its own copy of the repository, see where it lives and what it starts from, and delete it when the work is done.
- [Sessions and the sidebar](https://www.drayhq.com/docs/using-dray/sessions): Find sessions in the sidebar, read its marks and groups, pin, settle, set aside, fork, rename and delete sessions, and move between them from the keyboard.
- [Spaces](https://www.drayhq.com/docs/using-dray/spaces): Group projects into spaces, like work and personal, switch between them in the sidebar, and keep other spaces' sessions and notifications out of sight.

## dray CLI

- [The dray command](https://www.drayhq.com/docs/cli): Install the dray CLI, keep it up to date, and see every command it has for sessions, drafts, issues, the browser, sharing and servers.
- [Sessions](https://www.drayhq.com/docs/cli/sessions): Start, list and message Dray sessions from the command line, with every flag for model, effort, agent, base branch, issues and fast mode.
- [Orchestration](https://www.drayhq.com/docs/cli/orchestration): Have one agent fan work out into several sessions, review its work with a second model, and pass messages between parent and child sessions.
- [Drafts](https://www.drayhq.com/docs/cli/drafts): Save a task for later with dray draft, list saved drafts, and start or remove them.
- [Issues](https://www.drayhq.com/docs/cli/issues): Tag a session with the Linear or GitHub issues its work is against using dray issue link, and remove tags with dray issue unlink.
- [Browser](https://www.drayhq.com/docs/cli/browser): Drive a session's own browser with dray browser — open pages, read them, click and type, take screenshots and record videos.
- [Share](https://www.drayhq.com/docs/cli/share): Publish a session's dev server as a public link with dray share, list live links, and take them down.
- [Servers](https://www.drayhq.com/docs/cli/servers): Make a machine a Dray server with dray server, give it a public address, and manage the app's list of servers with dray machine.

## Settings

- [Settings](https://www.drayhq.com/docs/settings): Open Settings with the gear or ⌘, and find what each tab holds — appearance, spaces, servers, accounts, transcription, integrations, shortcuts, the changelog and About.
- [Accounts](https://www.drayhq.com/docs/settings/accounts): See which account Claude Code, Codex, pi, fx, Grok Build and gh are signed in as, sign in through Terminal or with an API key, reauthorize, sign out, and hide an agent from the picker.
- [Issues](https://www.drayhq.com/docs/settings/issues): Connect Linear with an API key or GitHub through gh, browse and filter issues on the Issues page, change status and priority, tag issues in prompts with #, and see the issues linked to a session.
- [Dictation](https://www.drayhq.com/docs/settings/dictation): Download a speech model, pick a microphone, and dictate into the composer with ⌘D. Transcription runs on your Mac; audio never leaves it.
- [Appearance](https://www.drayhq.com/docs/settings/appearance): Pick a theme and light, dark or system mode, cycle them with ⌘⌥T and ⌘⌥L, zoom the whole app with ⌘= ⌘- ⌘0, and choose where the side panel opens.
- [Notifications](https://www.drayhq.com/docs/settings/notifications): How Dray tells you a session finished, needs permission or asked a question — a macOS banner, an in-app card, or nothing — plus the ready-to-merge card, ⌘G, the sidebar marks and the dock badge.
- [Shortcuts](https://www.drayhq.com/docs/settings/shortcuts): Every default keyboard shortcut in Dray, and how to rebind, remove or reset one in Settings → Shortcuts.

## Reference

- [Remote access and sharing](https://www.drayhq.com/docs/reference/remote-access): Keep sessions running after you quit, connect the app to other machines, reach this Mac from another one, share a dev server by public link, and update remote servers.
- [Data on disk](https://www.drayhq.com/docs/reference/data): What Dray keeps in ~/.dray, what goes when you delete a session, the environment variables you can set, and where each agent keeps its own data.
- [Privacy](https://www.drayhq.com/docs/reference/privacy): Exactly which analytics events Dray sends and what they carry, what is never sent, how to turn analytics off, and how surveys and the website measure visits.
- [Troubleshooting](https://www.drayhq.com/docs/reference/troubleshooting): Fixes for common problems — a missing or logged-out agent, a stuck session, a dead permission card, a refused dray command, silent dictation, missing notifications, gh, worktrees, rate limits — and where the logs are.

## Agent skills

- [dray-docs](https://www.drayhq.com/docs/.well-known/agent-skills/dray-docs/SKILL.md): Read the Dray Docs instead of answering from memory. How to install and use Dray, the desktop app for coding agents. Use when a task involves Dray Docs: how it works, how to set it up or configure it, or its API.

## Agent resources

- [llms-full.txt](https://www.drayhq.com/docs/llms-full.txt): The full Markdown of every page in one file.
- [Page Markdown](https://www.drayhq.com/docs/index.md): Append `.md` to any page URL to fetch that page as raw Markdown.
- [JSON API](https://www.drayhq.com/docs/api/docs/pages.json): Page index of the JSON docs API; each entry links the page's JSON and Markdown forms. Described by the OpenAPI document at https://www.drayhq.com/docs/openapi.json.
- [Agent skills](https://www.drayhq.com/docs/.well-known/agent-skills/index.json): Agent Skills discovery index of the skills this site publishes.
- [API catalog](https://www.drayhq.com/docs/.well-known/api-catalog): RFC 9727 linkset of the APIs documented here.
- [AI catalog](https://www.drayhq.com/docs/.well-known/ai-catalog.json): ARD manifest of the agent-facing resources on this site (MCP server, skills, APIs).
- [agent-readability.json](https://www.drayhq.com/docs/agent-readability.json): Manifest of every agent-facing artifact on this site.
- [Sitemap](https://www.drayhq.com/docs/sitemap.xml): Every indexable page URL with its last-modified date.