Create a project from GitHub

Start from GitHub when you don't have a local checkout, you're setting up from your phone, or you're starting a brand-new repository. boxes.dev will clone your selected repositories into a new Template box and configure Git access so agents can pull and push.

Cloning copies committed code and Git LFS files. It won't install dependencies, bring over environment files or secrets, or check that your app runs. You'll get your app working with an agent on the Template box, then save a snapshot so devboxes start from the finished environment.

To bring over local edits, environment files, secrets, or database contents as part of setup, use local-folder setup instead.

Connect and choose repositories

1. Sign in on the boxes.dev website and choose Create from GitHub. If you already have projects, choose New project first.
2. Connect your GitHub account. If prompted, choose Connect on GitHub and give boxes.dev access to the personal account or organization that owns the repository.
3. Choose Single repository, Multiple repositories, or Create new. You can include up to 20 repositories in one project.

If a repository is missing, check that the GitHub App installation includes it. An organization owner may need to approve access. Archived, read-only, and unavailable repositories cannot be selected.

Create new will open GitHub's repository-creation page, with Private selected by default. Finish creating it there and return to boxes.dev. If your installation covers only selected repositories, grant access to the new one when prompted. Canceling setup or deleting the boxes.dev project will not delete the GitHub repository.

Connect your GitHub account before choosing repositories for the new project. Select the image to enlarge it.

Review the new project

Check the repository paths and devbox size before continuing. The devbox size is the Instance type field: it will apply to the Template box and all of this project's devboxes, and cannot be changed after creation. A single repository occupies the project root; with several, each has its own direct child folder. Review any warning that a repository is already in another project before creating a duplicate.

Automatic GitHub access is selected by default: your Template box and devboxes will pull and push as your connected GitHub account, with no SSH key to register. Complete any Update GitHub access request. If you prefer SSH, follow the SSH steps below.

The optional Devbox startup script will run before each new devbox's first agent prompt. The suggested commands will update its checkout from the repositories' default branches. Edit them to fit your workflow or leave the field blank.

When the review looks right, choose Create project to create the project and start cloning.

Get the application running

When cloning finishes, open the project in the desktop app or the mobile app and prepare the environment with an agent. If you haven't connected a coding agent yet, do that first — see Connect Codex and Claude.

1. Choose the Get … running action, named for your project: for a project called my-app, it reads Get my-app running. It opens a Template box thread with a prepared setup prompt.
2. The prepared prompt asks the agent to install dependencies, start your app, check that it works, and save a snapshot. Review it, add anything specific to your app, and send it.
3. Provide any missing secrets in Project settings → Environment files in the desktop app (Environment files and secrets), or edit files or use the terminal with the Template box selected. Avoid pasting secret values into the conversation.
4. When the agent finishes, open your app with the Template box selected and try an important workflow. If it needs more work, continue in the same thread and ask the agent to take a new snapshot after fixing it.

Ask the agent to verify tool versions and the project's normal build or test command from a new terminal session. Setup should work without temporary shell changes. Its summary should name the checks that passed, services it started, and anything still blocked by missing access or secrets.

If you leave before sending the setup prompt, find it in the thread list. Once the environment is ready, continue with your first task.

Use SSH for Git access

In the project review, choose Use an SSH key for GitHub pull/push access instead. Setup will generate a key on the Template box and show its public key. Add that public key in your GitHub account's SSH-key settings, return to boxes.dev, and select Verify. The key needs access to every selected repository. If your organization uses SAML SSO, authorize the key for that organization too.

The private key stays on the Template box and will be copied to its devboxes. An account SSH key can access repositories allowed by your GitHub account, beyond those selected for this project. Remove the public key in GitHub when you no longer need it; deleting a boxes.dev project or disconnecting GitHub will not remove it for you.

Return to unfinished setup

Choose Continue setup under Setups in progress on the website or in the desktop app. This will reopen the existing project and any pending SSH verification. Setup started this way can't be resumed with the terminal commands from local-agent setup; use Continue setup.

If cloning has finished and you still need to get the app working, reopen the setup thread from the thread list and continue that conversation.

If a project name belongs to another unfinished setup, choose Go to other setup to resume it or Use another name to create a separate project. If the saved setup can no longer be resumed, follow the displayed delete-and-recreate instructions.