Projects and workspaces
A project is a folder with your mock services, collections and environments, kept as plain files you can commit to Git. A workspace groups projects on the Projects page, for example one workspace per client or per team. The workspace is only a label: a project stays in its own folder, and nothing moves on disk when you group it.
The Projects page
Open http://127.0.0.1:7777 (or run zyvra ui) to see every project Zyvra knows. Each card shows the project’s name, the end of its folder path, whether it is running and how many of its services are.
- New project creates a folder with a starter
zyvra.yamland adds it to the workspace you are looking at. - Open existing adds a folder that already has a
zyvra.yaml, for example one you cloned from Git. - Search looks in every workspace, and says which workspace each result is in.
- Remove from Zyvra (the menu on a card) forgets the project. Its files stay on disk, and you can add the folder again later.
Workspaces
Every project is in a workspace. There is always a Default workspace; a project starts there until you move it. You can rename Default, but not delete it.
| To do this | Do this |
|---|---|
| Create a workspace | New workspace on the Projects page. |
| Rename or delete one | The ⋯ button next to the workspace list. |
| Move a project | The menu on its card, then Move to workspace. |
| Switch workspace | The workspace list at the top of the page. Zyvra remembers your choice. |
Deleting a workspace sends its projects back to Default. No project file is touched.
A workspace name is 1 to 60 characters and unique (upper and lower case count as the same). Workspaces are kept in Zyvra’s own settings folder on your computer, not in your project files, so they are not part of what you commit, and nobody else sees them.
Project names are unique in a workspace
Two projects in one workspace cannot have the same name. Zyvra refuses to create, open or move a project into a workspace that already has one with that name, and says which. The same name in different workspaces is fine, so you can have a billing project for each client.
Where new projects are created
If you leave the Folder field empty, a new project goes to:
<your home folder>/.Zyvra/<workspace>/<project name>For example ~/.Zyvra/acme/billing for a project called Billing in a workspace called Acme (the workspace name is turned into lowercase letters, digits and dashes). On Windows the folder is %USERPROFILE%\.Zyvra. The dialog shows the exact folder before you create the project. If that folder already holds a project Zyvra no longer lists, a number is added (billing-2).
Type a folder yourself to put the project anywhere, for example inside an existing repository. Zyvra uses exactly that folder. It never creates a project in a folder that already has a zyvra.yaml; open it instead.
Projects you created before workspaces keep the folder they have.
Switching projects while you work
Inside a project, the switcher at the top of the sidebar shows the workspace you are in. Open it, pick a workspace, then a project. Each project shows its folder and how many of its services run. All projects takes you back to the Projects page.
Where Zyvra keeps the list
The list of projects and workspaces is in Zyvra’s settings folder: ~/Library/Application Support/zyvra on macOS, ~/.config/zyvra on Linux and %AppData%\zyvra on Windows. It holds only where your projects are, which workspace each is in, and which you trusted to run scripts. See uninstalling for how to remove it.