Working with projects
Create projects from scratch or from a GitHub repo, organize them, and browse their files.
A project is one git repository plus its Machine configuration. It's the container for everything — sessions, secrets, connected tools, deployments, and members. This guide covers creating and managing them from the dashboard.
Create a project
Start fresh or import
From your projects list, choose New project, then pick how it starts:
- Start fresh — Machine creates and manages a new git repository for you. Good when you're building something new and don't already have a repo.
- Import a repository — connect GitHub and select an existing repo. Machine works against your repository directly; sessions branch from it and land work through review.
Connect GitHub (for imports)
If you're importing, you'll connect the GitHub App to the org or account that owns the repo, then pick the repository. Machine only gets access to the repos you grant, and uses short-lived, per-session credentials when an agent works.
Open the project
The project home is your launch pad: the session composer to start work, plus tiles for the project's features — sessions, changes, connected tools, secrets, deployments, and more.
Organize your projects
From the projects list you can:
- Search by name, repository URL, or branch to find a project fast.
- Rename a project to keep things tidy.
- Archive a project you're done with — it's hidden from the main list without deleting the underlying repository.
- Switch accounts, or use the all accounts view to see every project you can access across the accounts you belong to.
Browse project files
Open a project's Files to browse its repository — navigate the tree, view a file's contents, search by filename or content, and look at a file's commit history. It's a read-oriented view of the repo as it stands on the default branch; agents make changes on their own branches inside sessions.
A project works best when it's focused — one product, service, or idea per project. Smaller, well-scoped repos give agents tighter context and faster sandboxes than one giant monorepo.
Next: Running a session · Customizing your project · Projects concept.