Workspaces

A workspace is one git repository with an orca-workspace.yaml file in it. It describes everything a developer needs to work on your team's projects on their own computer. A new developer installs Orca, joins the workspace, and from then on any project is one click away on the Workspace page, or one sentence to an AI tool: "spin up billing".

This page explains what a workspace is and how the pieces fit together. The pages after it cover each part in detail.

#What a workspace holds

One repository describes the whole local environment:

The workspace repo is usually small: orca-workspace.yaml, the shared services' compose.yaml and their config files, and optionally a certificate and an orca.yaml for links and post-start commands.

#The mental model

Think of the workspace as two layers.

The environment is the same for everyone and is applied when you join: the network, the gateway on your team's domain, the shared services and every route. After joining, https://mail.local.acme.dev works on your machine the same way it does on a colleague's.

The projects are a menu. Joining doesn't clone any of them. Each project card on the Workspace page shows whether it's Running, Cloned or Not cloned, and you set up only the ones you work on. Setting one up clones it, writes its .env, fills in secrets, runs its setup command once, starts the shared services it needs and starts it.

The workspace file is the single source of truth. When a team lead adds a project or a hostname and pushes, everyone's Orca pulls the change the next time it starts.

#What happens when you join

Joining runs five steps, shown as they happen:

1. Get the workspace: clone the repo, to ~/code/<repo name> unless you choose a folder.
2. Create the shared network, if it doesn't exist yet.
3. Set up the gateway on the workspace's domain, with its certificate, and start it.
4. Start the shared services from the workspace's compose file.
5. Add the routes for the shared services and every project.

Nothing else on your machine changes. See Join and use a workspace for the details.

#What happens when you set up a project

Setting up a project runs seven steps:

1. Clone the repository, or use the checkout that's already there.
2. Create the .env file from the project's template, such as .env.example.
3. Fill in secrets from your team's secret manager.
4. Create its database, when its orca.yaml requires one: a database and a user of its own on the team's shared server.
5. Run the setup command, such as just setup, once per machine.
6. Start the shared services it uses.
7. Start the project, and show its URLs.

If a secret is still missing after step 3, Orca stops before starting anything and asks you to fill it in. See Set up a project and Secrets.

#With an AI tool

With Orca connected to your AI tool, a developer can say "spin up the CRM" or "set up billing and give me its URL". The tool looks the project up in the workspace, sets it up with the same steps and answers with its URLs. If secrets are missing, it names them and sends you to the Workspace page to fill them in. Orca tells AI tools never to ask for secrets in the chat.

#Who it's for

• Developers join once and set up projects as they need them. Start with Join and use a workspace.
• Team leads and platform engineers write the workspace file and keep it current. Start with Create a workspace.
• Teams with a hand-run reverse proxy, such as an HAProxy, nginx or Traefik stack every developer clones, can move it into a workspace. See Migrate from a reverse proxy.

#Where next

#Related

• Gateway: how hostnames, certificates and the landing page work.
• orca.yaml reference: a project's own routes, links and hooks.
• Worktree instances: run every branch of a project side by side.