Projects & Setup | Ghostable Desktop | Ghostable Menu Projects & Setup Groups and projects ------------------- Launcher groups are local organization only. They are not Ghostable teams, billing seats, or repository permissions, and changing a group does not modify project files. Use them to mirror the way you already think about clients, organizations, or product areas. Each project record stores a local folder path. Renaming or removing a launcher entry does not rename or delete the repository on disk. Add a repository ---------------- 1. Select the plus button in the Project Launcher. 2. Create or choose a group. 3. Add a project and select its repository folder. 4. Choose **Open**. Ghostable checks the selected folder for a `.ghostable/ghostable.yaml` manifest. A configured repository opens normally; a repository without that manifest opens the setup guide. Set up Ghostable ---------------- The guided setup collects project and local-device details, then lets you choose which adoption steps to perform: - Name the first shared environment and choose its environment type. - Import an existing local `.env` file as the initial encrypted baseline. - Create or update `.env.example`. - Add managed Ghostable guidance to `AGENTS.md`. - Copy a structured adoption prompt covering schema, annotations, example files, hygiene, drift, and optional CI. - Name the device identity created for this project. The first device becomes owner Initial setup creates the project's first device identity and owner authority. The private identity is stored outside the repository; only public records and encrypted project state are written under `.ghostable/`. Adopt an existing project ------------------------- When a repository already has environment files, choose one authoritative baseline before importing. Review the file for local-only credentials, stale keys, and values that should never become shared development defaults. Setup can import the baseline and generate an example file, but it does not decide which values are safe for your team. After setup, inspect every variable, add validation rules, and run Review before committing. Do not commit plaintext Commit `.ghostable/` and a reviewed `.env.example`. Keep real `.env` files ignored. Ghostable encrypts shared values; Git cannot protect a plaintext secret that was committed first. Commit project state -------------------- Review the generated files, then commit the `.ghostable/` directory through the repository's normal branch and review process. Signed activity, encrypted values, access grants, schemas, and project policy travel with that commit. Review the initial state Copy ``` $ git status --short $ git diff -- .ghostable .env.example AGENTS.md $ git add .ghostable .env.example AGENTS.md $ git commit -m "Initialize Ghostable" ``` Open an existing project ------------------------ Adding an already-configured repository to the launcher does not grant access. This Mac also needs a valid project device identity and environment grants. If the repository was cloned onto a new machine, follow the [team onboarding and device join workflow](https://ghostable.dev/docs/3.x/getting-started/team-onboarding) before expecting encrypted values to open. On this page [ ![Ghostable](https://ghostable.dev/images/logo-dark.svg) ![Ghostable](https://ghostable.dev/images/logo-light.svg) ](https://ghostable.dev) Desktop [ CLI 3.x ](https://ghostable.dev/docs/3.x) [ Desktop ](https://ghostable.dev/docs/desktop) CLI 3.x introduction Documentation local first no login encrypted repository plaintext hosted service Installation Documentation brew homebrew npm npx linux windows PATH version update Start a new project Getting Started setup seed dotenv owner initialize Adopt an existing project Getting Started existing env import authoritative source adopt Onboard a team member Getting Started join request approve roles offboarding pull request Repository and storage Core Concepts .ghostable git conflict merge worktree private identity metadata Environments Core Concepts protected production preview staging push sync pull replace run mask-output Variables and promotions Core Concepts var promote copy context annotation key Access and devices Core Concepts identity reader writer grantor owner revoke rotate leave delete Daily development workflow Workflows pull diff validate review clean daily Review and secret scanning Workflows scan sarif github suppress secrets drift Hygiene and rotation Workflows rotation stale unused suppression environment key Automation credentials Automation & CI GHOSTABLE\_CI\_TOKEN ci deploy credential powershell revoke replace Continuous integration Automation & CI GitHub Actions fork pull request JSON stdout stderr exit codes mask-output Deployments Automation & CI Forge Vapor Cloud provider CLI dry-run preserve remote keys temporary files Validation Reference schema required nullable regex min max different\_from Command reference Reference --help --json NO\_COLOR flags aliases exit code automation Configuration Reference ghostable.yaml activity mode auditEnvironments scan ignores deployTarget dotenv syntax Security Reference cryptography XChaCha20 Poly1305 HKDF user presence threat model Backups & Offline Reference recovery offline restore clone key identity Agent integration Reference AGENTS.md capabilities allowlist coding agent Troubleshooting Reference no project found revoked identity stale policy user presence invalid CI token provider CLI git conflict diagnostics Ghostable Desktop overview Desktop Installation Desktop Projects and setup Desktop Interface tour Desktop Environments and variables Desktop Local environment files Desktop Validation and review Desktop Activity Desktop Access and automation Desktop Project settings Desktop Application settings Desktop Licensing and updates Desktop Security and storage Desktop Troubleshooting Desktop No results found