Set up a workspace and its local apps
3 minute read · Projects & Git
Workspace settings holds the configuration for every project in a workspace: where each app lives on this computer, how it starts, which tools the workspace shows, and the instructions and skills your agents follow. It replaces the former per-project settings.
- Open Workspace settings
- Configure each local app
- Choose the workspace tools
- Share instructions and skills
- What moved or was removed
Open Workspace settings
Use any of these:
- the gear button Workspace settings in the project toolbar;
- right-click the workspace icon in the rail and choose Workspace settings;
- type
/settingsin a project chat; - Cmd+K, then comma on macOS or Ctrl+K, then comma on Windows and Linux.
The window has three sections: Local app, Tools and Instructions & skills. Save workspace applies the Tools and Instructions & skills sections; Cancel leaves without saving them. The footer reminds you that tools, instructions and skills apply to every project in this workspace.
Configure each local app
Local app shows a card for every project folder in the workspace.
| Field | Use it for |
|---|---|
| Name | The project's name in Vortex. |
| Local folder | The folder on this computer. Change… points the project at another existing folder, and Attach folder adds one to a project that has none. |
| Move local folder… | Moves the project's files to a new parent folder on the same disk. The project, chats and settings are kept, and existing files at the destination are never overwritten. Cancel move stops before it starts. |
| Startup settings → Local server | Start with Vortex runs the app's command. Already running (Herd / local server) only checks and opens the saved address; manage that server in Herd or its own terminal. |
| Run app / Local address | The start command, such as npm run dev, and the address Preview opens, such as http://localhost:3000. |
| Run tests / Build | Commands used by checks and the agent. |
Commands are detected automatically; change them only when needed. Save app saves that card. A card can also start the app and show its progress and errors in place. The folder binding belongs to this computer: on another computer, choose that computer's checkout. See runtime and Preview and another computer.
Choose the workspace tools
Tools chooses which project tools appear in this workspace: Files and Browser are always available; Version history (Git), Local app and Terminal can be turned on or off. Vortex can mark tools as Suggested after checking the folders. Enabling a tool does not install or start anything, and turning one off does not delete files.
Share instructions and skills
Workspace instructions hold rules and context for every project and chat in the workspace, such as conventions, the checks to run and what must not change. Select skills from your personal skills library to add reusable guidance.
Under Context files, list project-relative files, such as docs/conventions.md, that agents should read for a particular project. Instructions and skills guide the agent; they do not grant permissions or provide missing tools. Keep passwords and tokens out of instructions.
If you used separate project instructions before, they were combined into the workspace instructions, each under its project's name. Review them once and remove anything that no longer applies.
What moved or was removed
The former project settings for code hosting, publishing, background workers, environment files and pinned connections are no longer part of Vortex. Git still works with the repository's own remotes and your system Git credentials; see Git and manual commits. Saved databases, SSH hosts, FTP connections, API collections and Signals open from Tools in the workspace rail or from Vortex Search; see connections.
A plain chat without a project has no workspace project settings to edit. Open or attach a project when the task needs its folder, commands or instructions. See workspaces and projects.