> ## Documentation Index > Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt > Use this file to discover all available pages before exploring further. # murmur workspace create > Create a workspace from your tenant's creation defaults with a name and repositories, then start building its custom image. Creates a [workspace](https://docs.murmur.dev/concepts/workspaces.md) for the repositories you choose and starts building its custom [image](https://docs.murmur.dev/concepts/images.md). Murmur switches the workspace to the new image after verification succeeds. See [Customize your Workspace](https://docs.murmur.dev/customize-your-workspace.md#when-you-create-a-workspace). As in the dashboard, the starting image, timeouts, placement, environment, and access settings come from your tenant's [creation defaults](https://docs.murmur.dev/cli/defaults.md). The command never replaces an existing workspace. ## Synopsis ```bash theme={null} murmur workspace create [--repo URL[=BRANCH]]... [--skip-image] [--environment ENVIRONMENT_NAME] [NAME] ``` Omit `NAME` to use interactive prompts. In scripts, pass `NAME` and use `--repo` to select repositories; the command cannot prompt without a terminal. ## Arguments | Name | Type | Required | Description | | - | - | - | - | | `NAME` | string | no | The workspace name: a lowercase letter, then up to 62 lowercase letters, digits, and hyphens. `murmur` and names beginning with `murmur-` are reserved. Prompted for when omitted. | | `--repo` | string | no | A repository agents clone, as `URL` or `URL=BRANCH`. Repeat it for several. Any GitHub spelling works (HTTPS or SSH, with or without `.git`); the workspace stores the canonical `https://github.com/OWNER/REPO` URL. `BRANCH`, everything after the first `=`, is the base branch agents start from. Without it, the command reads the default branch from the remote. | | `--environment` | string | no | Use only this environment, replacing the default environment list. Without this flag, a disabled default requires you to select a replacement. | | `--skip-image` | bool | no | Create the workspace without starting the service that builds its custom image. Agents boot the starting image from the creation defaults. Default: `false`. | The command reads a repository's default branch with `git ls-remote`, so your own git credentials apply: a private repository needs git access to it from your machine, or an explicit `=BRANCH`. ## Prompts Without `NAME`, the command asks three questions. Press Enter to accept the value in brackets. 1. **Repositories**, as space-separated `URL[=BRANCH]` entries. It offers the current repository's `origin` remote. This question is skipped when you pass `--repo`. 2. **Workspace name.** It offers the repository's name when there is exactly one. 3. **Automatically create a custom image for this workspace?** Defaults to yes. This question is skipped with `--skip-image`. If the configured environment is disabled and `--environment` is omitted, the command also asks you to select a replacement environment in the terminal. This question has no default: enter a name explicitly. If input ends before a question is answered, the command fails without creating anything. ## Where the workspace is recorded The command saves the new workspace in the current repository's `.murmur/murmur.yaml` if that is the active config file and it has no `workspace` value. It leaves other config files and existing workspace values unchanged. If later [spawns](https://docs.murmur.dev/cli/spawn.md) would use a different workspace, the command prints instructions for selecting the new one with `--workspace`. The [`MURMUR_WORKSPACE`](https://docs.murmur.dev/configuration/murmur-yaml#environment-variable-overrides) environment variable takes precedence over the config file. ## Requirements * Tenant configuration from [`murmur login`](https://docs.murmur.dev/cli/login), a repository file, or an explicit configuration file. * Permission to create workspaces. Every tenant member has it. An agent running on a Murmur VM does not, so agents create workspaces only from a developer's machine, as that developer. ## Examples ### Answer the prompts ```bash theme={null} murmur workspace create ``` ### Create a workspace for one repository ```bash theme={null} murmur workspace create api --repo https://github.com/acme/api ``` ### Pin base branches and skip the image ```bash theme={null} murmur workspace create web \ --repo git@github.com:acme/web.git=develop \ --repo https://github.com/acme/shared=main \ --skip-image ``` ## Choose an environment when the default is disabled An enabled configured default is kept without asking you to choose an environment. If the environment listing confirms that the default is disabled, an interactive terminal offers enabled alternatives visible to you, shared with all workspaces, and matching the template's placement substrate. In scripts, the command lists these candidates and requires an explicit override: ```bash theme={null} murmur workspace create api --environment my-environment ``` An explicit `--environment` uses exactly that environment and replaces the entire default environment list, including fallback environments. The CLI skips environment discovery and preserves the template’s image, placement, cloud identity, grants, and other settings. Choose an environment with machine resources and cost appropriate for your workload. An enabled alternative is not necessarily compatible with the entire workspace: after applying the selection, the CLI submits the completed workspace through `SetResource`. The server validates image, architecture, disk requirements, and resource-use policies before saving, and reports any errors. When you select a replacement at the terminal prompt, only disabled entries are replaced. Environments that are not disabled retain their fallback order: earlier entries are preferred. A record missing from the listing is not treated as disabled. If no alternatives are available, ask an administrator to enable a compatible environment. Workspace creation never substitutes or re-enables an environment automatically. ## Errors | Code | Meaning | What to do | | - | - | - | | `a workspace NAME is required when stdin is not a terminal` | The command cannot prompt. | Pass `NAME` and the repositories with `--repo`. | | `a workspace name is required; an empty NAME names no workspace` | `NAME` is an empty string, such as an unset shell variable in quotes. | Pass a workspace name. In a terminal, omit `NAME` to be asked for one. | | `read "": EOF` | Input ended before the question was answered. Nothing was created. | Answer each question, or pass `NAME` and `--repo`. | | `config file not found` | No home or repository configuration was found. | Run [`murmur login`](https://docs.murmur.dev/cli/login). | | `workspace name is reserved: ...` | `murmur` and names beginning with `murmur-` are reserved for Murmur. | Choose another name. | | `create workspace : it already exists` | A workspace with that name exists. It is left unchanged. | Choose another name. | | `INVALID_ARGUMENT` | `repo is listed twice; ...`: two entries name one repository, in any spelling. Nothing was created. | Name each repository once. | | `INVALID_ARGUMENT` | `repos and both check out into ; ...`: the two repositories would be cloned into one directory, such as `acme/app` on two hosts. Nothing was created. | Keep one of them. See [Repo fields](https://docs.murmur.dev/catalog/workspace.md#repo-fields). | | `INVALID_ARGUMENT` | `repos and check out into and , one inside the other; ...`: one repository would be cloned inside the other's directory, such as `org/sub` and `group/sub/repo`. Nothing was created. | Keep one of them. See [Repo fields](https://docs.murmur.dev/catalog/workspace.md#repo-fields). | | `repository : "=" must be followed by a branch name` | An entry ends with `=`. | Add the branch, or drop the `=` to use the default branch. | | `repository : a workspace repository names only its base branch (URL=BRANCH)` | An entry uses spawn's `URL=BASE:WORKING` form. | Name only the base branch. | | `read the default branch of (name one as =BRANCH): ...` | The remote could not be read with your git credentials, or it is empty and has no default branch. | Pass the branch as `URL=BRANCH`. | | `this control plane has no workspace creation defaults, ...` | The platform has no workspace template to start from. | Write the whole workspace with [`murmur defaults workspace`](https://docs.murmur.dev/cli/defaults) and [`murmur set`](https://docs.murmur.dev/cli/set), as the message shows. | | `PERMISSION_DENIED` | You may not create workspaces, for example when running as an agent on a Murmur VM. | Run the command as yourself, or ask for a role that grants `workspace.create`. | | ``start building workspace 's custom image (retry with `murmur workspace build-image `): ...`` | The workspace was created, but the image service did not start. | Fix the cause the message ends with (see [`murmur workspace build-image`](https://docs.murmur.dev/cli/workspace-build-image#errors)), then run `murmur workspace build-image `. | ## Related * [`murmur workspace build-image`](https://docs.murmur.dev/cli/workspace-build-image): start building a workspace's custom image * [`murmur defaults`](https://docs.murmur.dev/cli/defaults): the template a new workspace starts from * [`murmur login`](https://docs.murmur.dev/cli/login): sign in and select your tenant * [Customize your Workspace](https://docs.murmur.dev/customize-your-workspace.md): how the custom image is built * [Workspaces](https://docs.murmur.dev/concepts/workspaces.md): concept overview * [workspace](https://docs.murmur.dev/catalog/workspace.md): every workspace field This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.