# Build in Playground (/docs/build/playground) Playground is a coding agent inside Console for a [hosted app](/docs/concepts/hosting). Describe a change in plain words, such as "add a page that lists our rewards", and the agent edits your project. You watch the result in a live preview next to the chat, and every turn is saved as a checkpoint you can go back to. * **Members don't see your work yet.** Changes reach members only after you [stage](/docs/build/staging) them and a promotion takes that build live. * **No setup on your computer.** The agent works in a sandbox with a copy of your project's repository and runs the app's development preview for you. * **Where to find it.** Open **Developers → Build** with the **Test** environment selected. You need publish permission in **Test**. ```mermaid flowchart LR Chat["Chat with the agent"] --> Checkpoint["Checkpoint saved"] Checkpoint --> Preview["Preview updates"] Checkpoint --> Save["Save to main"] Save --> Stage["Stage"] Stage --> Staging["Staging app"] ``` ## Chat with the agent [#chat-with-the-agent] Open **Developers → Build** in **Test** to chat with the hosted agent beside your app's preview. Send a description of the change. Your message appears immediately, and the conversation follows the response as it grows. Scroll up to read earlier work; choose **Scroll to end** to follow again. Consecutive tool calls and reasoning appear in a collapsed summary, such as **Ran 3 commands and read 2 files**. Progress messages separate the groups. Expand a summary to see individual steps, then expand a tool call for its command, output, or file diff. Running work and failed calls are marked in the summary. When a turn finishes, the chat keeps your message, the final answer, and the checkpoint's **Stage** or **Restore** control visible. Expand **Worked for…** to read intermediate messages and work summaries. ### Answer questions and permission requests [#answer-questions-and-permission-requests] Questions appear above the message box. Select the requested options or enter your own answer, then choose **Next** for the following question or **Submit** after the last one. **Skip** dismisses the request and lets the agent continue without an answer. Permission requests show the action and affected resources. Choose **Allow once**, **Always allow** when offered, or **Reject**. Requests from a subagent appear here too. Beside the model picker, the message box shows the AI credit the last turn used and the AI balance left for this project, for example **$0.12 last turn · $8.40 left**. AI usage draws credit at Domino's rates. Use **Stop** to interrupt the current turn. If sending fails, the message returns to the composer so you can retry. Questions and permissions are loaded again when you reopen the playground. ## Work in the side panes [#work-in-the-side-panes] Next to **Chat**, Playground has six panes: | Pane | What it shows | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **Preview** | The app's development preview, with the [preview controls](#point-to-a-change-in-the-preview) | | **Map** | The project's campaign as a [map](#see-the-campaign-as-a-map): trackers, quests, caps and rewards, with their numbers | | **Simulate** | A pasted campaign, built and published to a throwaway project, with generated members run through it; see [Simulate a campaign](/docs/build/simulate) | | **Files** | The project's files in the sandbox | | **Changes** | What the playground changed compared with `main` | | **Terminal** | A terminal in the sandbox | Playground starts the development server for you. Its agent can inspect the server's status and logs, recover a stopped server, or restart it after configuration or dependency changes. These controls use the same server shown in **Preview**. Source edits update through the running server. If the agent reports that its preview controls are unavailable, reload Playground to boot the sandbox again. ## See the campaign as a map [#see-the-campaign-as-a-map] **Map** draws what the project runs in **Test**, read from its latest published deployment rather than from the source files. Playground publishes the project's quests to **Test** each time the agent's changes build, and the map follows within about ten seconds while the pane is open. | On the map | What it shows | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Sources** | Trackers, with their source, X search query and refresh interval, and **Members** or **Staff** for quests people submit or staff confirm | | **Quests** | How often each quest completes, the data it checks, staff review, when it is open, and the group it is limited to | | **Budgets and caps** | Each limit, such as "5 completions per member per day", shared by every quest that spends it | | **Rewards** | The point ledgers quests pay into, and badges, groups, Discord roles and other rewards | | **Leaderboards and referrals** | Which ledger each leaderboard ranks and its prizes, and what each referral program pays the inviter and the invitee | Each arrow says what crosses it: which records start a quest and who it pays, what a completion takes from a cap, and the points a quest, prize or referral pays. A dashed arrow is a prerequisite, such as another quest or a minimum balance. Archived quests, leaderboards and referral programs are left out. Notices about the deployment, such as a missing integration, appear above the map. When the latest change doesn't build, **Map** shows the error instead of a map that no longer matches the project. Ask the agent to fix it; the map returns once the quests build and publish again. The map is read-only: change the campaign by asking the agent. ## Keep threads apart [#keep-threads-apart] Playground keeps each conversation as a thread. Use the thread menu above the chat to start a **New thread**, switch between threads, rename one, or archive one you no longer need; archived threads stay under **Archived** and can be moved back. * **One copy of the project.** Your threads share it, so they see each other's changes. * **One thread works at a time.** Others wait their turn; see [queue follow-up messages](#queue-follow-up-messages). * **Restore rewinds everything after it.** Restoring a checkpoint rewinds that thread's conversation and the project's files, including changes other threads made after it. * **Nothing is lost when the sandbox sleeps.** Threads are saved after every turn and survive the sandbox sleeping or being replaced. ## When you step away [#when-you-step-away] After five minutes without interaction, an idle Playground tab pauses its live connections and preview so the hosted sandbox can sleep. Running agent turns and checkpoint saves finish first. Interacting with the preview counts as activity. Return to the tab or choose **Resume playground** to reconnect. Your chat and unsent prompt remain. The hosted sandbox can sleep after its additional 15-minute inactivity period. Local Docker containers continue until you stop the local stack. ## Save to main and stage [#save-to-main-and-stage] Playground works on its own branch of your repository, so its changes stay out of `main` until you save them. **Sync with main** above the chat asks the agent to move work between the two: | Action | What the agent does | | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | | **Get latest from main** | Merges everything saved to `main` into this playground | | **Save to main** | Merges this playground into `main` so new work starts from it; it does not stage or publish anything | | **Stage** on a checkpoint | Brings the checkpoint up to date with `main`, checks it, pushes it, and [stages](/docs/build/staging) that commit | **Restore** on a checkpoint rewinds that thread's conversation and the project's files to it. ## Continue in your own agent [#continue-in-your-own-agent] **Open in your agent** shows the commands that hand the project to Codex or Claude Code on your computer. Your agent checks out the repository; when it saves to `main`, bring that work back into Playground with **Get latest from main**. Once the project has published quests or staging builds, the instructions pick up that work. The agent reads the project and its saved brief, summarizes what exists, and asks what to change, without running brand or campaign discovery again. ## Queue follow-up messages [#queue-follow-up-messages] While the agent works, press Enter or choose **Queue** to hold your next message. Queued messages appear above the message box and go out one at a time as each turn finishes. Remove a queued message if it no longer applies. A selected element or captured logs are attached when you queue the message. Only one thread runs at a time. While another thread works, the message box offers **Queue** instead of sending, and the message goes out once that thread's turn ends. Choosing **Stop**, restoring a checkpoint, or a failed send pauses the queue, because the queued messages may no longer apply. Choose **Send next** to resume. ## Send a request from another page [#send-a-request-from-another-page] Some Console pages offer **Send to Build** beside **Copy prompt**: the example requests on an empty **Quests**, **Rewards**, **Leaderboards**, **Referrals** or **Trackers** page, and the [X search preview](/docs/build/trackers#preview-an-x-search). It needs permission to build the project. 1. Choose **Send to Build**. **Developers → Build** opens in **Test** on a new thread, with the request in the message box under **Prepared from …**. 2. Review or edit the request. Nothing is sent until you send it, or queue it while another thread works. 3. Send it. The thread is named after the request. Choose **Discard** instead to empty the message box. A request that hasn't been sent is dropped when you reload the page; send it again from the page that wrote it. A project whose code Domino doesn't host has no playground, so Build shows the request with **Copy request** to paste into your own agent. ## Attach files [#attach-files] Attach files with the paperclip, by pasting a screenshot, or by dropping files on the message box. A message can carry up to five files of up to 5 MB each, and can contain only attachments. Remove a file from the message box before sending if you change your mind. The agent receives the path of each file in its sandbox, so it can use the file directly, for example by copying a logo into your app. | File | What the agent gets | | ------------------------------------ | ------------------------------------------------------------------- | | PNG, JPEG, GIF and WebP images | The path, and the image itself when the selected model reads images | | Text and JSON files | The path, and the full contents | | Anything else, such as PDFs and SVGs | The path only | Attachments are kept outside your repository and are not saved in checkpoints unless the agent copies them into the project. If an upload fails, nothing is sent and your message keeps its files. Queued messages keep their attachments. ## Point to a change in the preview [#point-to-a-change-in-the-preview] Choose **Select**, then click an element in the preview. The element appears above your message box. Describe the change and send your message; the agent receives its selector, visible text, and a compact markup summary. The selected click does not open links or submit forms. Press **Escape** to cancel selection, or remove the attachment before sending. Input values are excluded. | Preview control | What it does | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Back** and **Forward** | Move between pages you opened in the preview. | | Address | Shows the page the preview is on. Type a path such as `/rewards` and press Enter to open it, or Escape to cancel. Addresses outside your preview are not opened. | | **Reload** | Reloads the current page. | | **Desktop** | Fits the preview to the available pane. | | **Tablet · 768px** | Uses a 768-pixel viewport. | | **Mobile · 390px** | Uses a 390-pixel viewport. | | **Console** | Shows up to 100 recent browser messages and uncaught errors. | | **Add to chat** | Attaches up to 20 recent console entries to your next message. Review them before sending. | | **Clear** | Clears the captured console entries. | On narrow screens, **Forward** is hidden. Changing the device width keeps the app running. A fixed viewport wider than the pane scrolls horizontally. These controls change viewport width, not the browser's operating system or touch behavior. Element selection and logs need a connected development preview. If they are unavailable, wait for development to start and choose **Reload preview**. Staged previews support resizing but do not capture elements or logs. Captured logs stay in this browser until you attach and send them. Reloading the preview or navigating to another document clears them. They do not include server logs or the contents of nested frames. > [!DEV] > Element selection and logs work with existing hosted repositories without a package upgrade. A custom content security policy can block the bridge; allow the same-origin `/.domino/preview-tools.js` script in development if you need these tools. ## Upgrade an older project [#upgrade-an-older-project] The preview needs Domino CLI 1.0.0 or newer. Projects created from earlier starters build quests the API no longer accepts. Instead of starting the preview, Playground shows **Upgrade with AI**. The agent upgrades `@domino-sdk/relay` and `@domino-sdk/relay-cli` and applies the required migrations. When it finishes, choose **Start the preview**. Your dependencies change only when you choose the upgrade. See [When Vite is ready but the preview does not start](/docs/build/development#when-vite-is-ready-but-the-preview-does-not-start) for other startup failures. ## Where next [#where-next] - [Hosted apps](/docs/concepts/hosting) — how the repository, previews, and staging fit together. - [Stage and share](/docs/build/staging) — staging builds and who can open them. - [Preview from your own computer](/docs/build/development) — run the preview on your own device instead.