Skip to main content
Newly for Mac only. This isn’t available in the web app at app.newly.app.
In Newly for Mac, a chat can run in one of two places. A Remote chat runs in the cloud, like every chat in the web app. A Local chat runs on your Mac. This page covers what’s different about Local chats. For the basics of projects and chats, see Projects, chats, Remote and Local.

​
What Local means

When you start a chat in the Mac app, you choose where it runs:
  • Remote: “Runs in the cloud, accessible on any device.”
  • Local: “Runs on your computer, Device must stay awake.”
The first chat in a new project starts as Local. You can pick Remote instead. Things to know about Local chats:
  • Your Mac has to stay awake. If your Mac sleeps or loses its connection, the chat list shows Disconnected and the chat parks. Nothing is lost, and your next message resumes it. See Parked chats and limits.
  • They don’t count toward the limit on running chats. That limit applies to Remote chats only. See Parked chats and limits.
  • Some features are only in Local chats: your own Claude or Codex login, Design mode, and previews on your Mac’s own simulator.

​
Set up your Mac for local previews

After the first-launch tour, the Mac app offers a one-time Local setup. It installs Xcode (about 7 GB), finishes Xcode setup, and downloads the iOS Simulator runtime (about 8 GB). If your Mac already has these, the step is skipped. You can choose Set this up later. Until setup is done, previews in Local chats use the cloud simulators, which need nothing installed. To switch a Local chat’s preview to your Mac’s own simulator, select Use this Mac in the preview pane. If setup isn’t finished, the pane walks you through Set up iOS preview (“One-time setup, about 15 GB total”). The Android emulator has its own setup steps. Your Mac needs Apple silicon and macOS 14 or later. See The web app and Newly for Mac.

​
Choose the agent

In a Local chat you can pick which agent does the work:
Newly Agent uses credits in Local chats too. Only turns on your own Claude or Codex login are free of Newly credits, and they work even when your Newly balance is 0. See How credits work.

​
Connect Claude or Codex

Claude and Codex become selectable once they’re connected. You can:
  • sign in to Claude Code or Codex on your Mac, or
  • add a key in Settings → Credentials: Claude Code token, Anthropic API key, or OpenAI API key (Codex). These are stored in your macOS Keychain.

​
Model and effort

With Claude or Codex selected, you also pick a Model and an Effort level. The lists come from the tool installed on your Mac. A chat’s model is fixed once its first turn has run, and the picker shows “Fixed for this chat”. To use a different model, start a new chat. With Newly Agent, Newly chooses the model. You don’t pick a model or effort.

​
Switching agent mid-chat

If you switch agent partway through a chat, the chat shows a divider, “Continued with” followed by the agent’s name, so you can see where the change happened.

​
Design mode

Design mode is only in Local chats. Use it to plan how your screens look before any app code is written.
1

Choose Design

Select Design in the prompt box and describe the screens you want.
2

Review the design

The agent draws the screens. Open Design in the preview pane to see them, and ask for changes in the chat.
3

Approve

When you’re happy, select Approve on the “Ready to lock in this design?” card in the chat. The card changes to “Design approved”.
4

Build it

Select Build it. The agent switches to Build mode and builds the app from the approved design.
For the other modes, see Build, Plan, Ask and Design.

​
Work in your own folder

The code for a Local chat on a Newly project lives in a copy that the Mac app manages and recreates each time the chat starts or resumes. Don’t edit that copy yourself. To work in a folder you control, choose Open Existing Project in the project menu and pick a folder on your Mac. The agent then edits files in that folder, so you can open it in your own editor at the same time. Saved versions are git commits inside the folder. The folder’s full path can’t contain spaces. If it does, the app shows “Project folders cannot contain spaces. Choose a folder whose full path has no spaces.” Rename or move the folder and try again. See Where your code lives.

​
Store screenshots and app icons

In Local chats, the agent can capture store screenshots and create app icon candidates. For AI-generated art, add your own OpenAI API key as the Screenshot art key in Settings → Credentials. If you already connected Codex with an OpenAI API key, that key is used automatically.
  • App icons need the key.
  • Screenshot sets use your app’s brand gradient as the background if there’s no key.
Images and videos the agent creates show up under Media in the preview pane, with Images and Video tabs. For store requirements, see App name, icon, bundle ID and version.

​
Website import

To rebuild an existing website as a mobile app, the Mac app needs a browser installed. With a chat open, find Set up website import in Settings → Publishing and select Install. It’s optional and downloads about 150 MB, one time.

​
Moving a chat between your Mac and the cloud

With Developer mode on, you can move a chat between your Mac and the cloud. See Settings and Developer mode.

Projects, chats, Remote and Local

Where your work runs.

Using the cloud simulators

Previews that need nothing installed.

How credits work

What uses credits and what doesn’t.

Settings and Developer mode

Credentials, Publishing and Developer mode.