Projects & setup
Import a repository or start fresh, then record and cold-prove the environment every thread will use.
A project is a home for its threads, Knowledgebase, and settings. You can import an existing GitHub repository or start fresh without one; a project without a repository can still build its first app in a thread.
Choose how to start
| Start from | What happens |
|---|---|
| Import a repository | Enter a GitHub URL or choose a repository you can access, then give the project a name and a team. Private repositories need the appropriate GitHub access. |
| Start fresh | Name a project without attaching a repository. Describe what you want to build in its first thread; connect a repository when it is time to publish there. |
See GitHub & authentication for repository access.
From clone scan to a working recipe
For an imported repository, setup starts with a clone scan: the repository's own docs, package scripts, service files, and likely runnable apps. The setup thread checks those clues against the actual code, installs dependencies, brings up any required services, and records the app commands and ports in the project's run config. Each app gets its own command; shared services, migrations, and seeds go in the setup prelude. You can follow the setup work in the thread rather than writing a setup script yourself.
A running app in today's sandbox is not enough. The recipe is tested cold from a fresh clone of the branch, with the recorded run config, committed files, and project variables — not an untracked file or a one-off manual command. A successful cold build becomes the cold-baked snapshot every new thread boots from. That is why a later thread can start in a prepared environment instead of rediscovering the install. See Run config & snapshots.
Checks and doctors
Setup reports checks on what it actually ran, including whether each recorded app starts and serves a usable page. If the preview cannot display an app because of its framing policy, a Preview Doctor can fix the preview setting. If it stops at a sign-in wall, an Auth Doctor can add a development-only way through. If login works locally but fails through the preview address, a Proxy-trust Doctor can address that difference. The offer card shows the affected app and the observed reason; you choose whether to start a dedicated fix thread. These fixes are proposed in a pull request rather than silently changing your app.
Starting without a repository
A fresh project can build before it has a remote repository. When you connect it to GitHub, Connect can create the GitHub repository and save the thread's work there; you do not have to create an empty repository in advance. If GitHub needs permission first, the publishing flow presents Connect GitHub, then Ship it once access is granted. Ship it creates the repository and opens the pull request for the finished work. The destination setting also allows Darting-managed repositories, so the GitHub grant is specific to shipping new repositories to GitHub. See Ship it & pull requests.
Secrets
Put development variables needed by the sandbox in project settings; production values for a hosted app are separate. Credentials agents should use without reading belong in the secrets vault instead. Secrets & environment explains the two environments; the vault & login browser covers vaulted credentials and sign-in sessions.