murmur workspace create

Creates a workspace for the repositories you choose and starts building its custom image. Murmur switches the workspace to the new image after verification succeeds. See Customize your Workspace. As in the dashboard, the starting image, timeouts, placement, environment, and access settings come from your tenant’s creation defaults. The command never replaces an existing workspace.

Synopsis

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.

Repositories, as space-separated URL[=BRANCH] entries. It offers the current repository’s origin remote. This question is skipped when you pass --repo.
Workspace name. It offers the repository’s name when there is exactly one.
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 would use a different workspace, the command prints instructions for selecting the new one with --workspace. The MURMUR_WORKSPACE environment variable takes precedence over the config file.

Requirements

Tenant configuration from murmur 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

murmur workspace create

Create a workspace for one repository

murmur workspace create api --repo https://github.com/acme/api

Pin base branches and skip the image

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:

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 "<question>": 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`.
`workspace name <name> is reserved: ...`	`murmur` and names beginning with `murmur-` are reserved for Murmur.	Choose another name.
`create workspace <name>: it already exists`	A workspace with that name exists. It is left unchanged.	Choose another name.
`INVALID_ARGUMENT`	`repo <name> is listed twice; ...`: two entries name one repository, in any spelling. Nothing was created.	Name each repository once.
`INVALID_ARGUMENT`	`repos <URL> and <URL> both check out into <dir>; ...`: 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.
`INVALID_ARGUMENT`	`repos <URL> and <URL> check out into <dir> and <dir>, 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.
`repository <n>: "=" must be followed by a branch name`	An entry ends with `=`.	Add the branch, or drop the `=` to use the default branch.
`repository <n>: 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 <URL> (name one as <URL>=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` and `murmur 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 <name>'s custom image (retry with `murmur workspace build-image <name>`): ...	The workspace was created, but the image service did not start.	Fix the cause the message ends with (see `murmur workspace build-image`), then run `murmur workspace build-image <name>`.

murmur workspace build-image: start building a workspace’s custom image
murmur defaults: the template a new workspace starts from
murmur login: sign in and select your tenant
Customize your Workspace: how the custom image is built
Workspaces: concept overview
workspace: every workspace field

Getting started

Core concepts

Integrations

Guides

murmur workspace create

Synopsis

Arguments

Prompts

Where the workspace is recorded

Requirements

Examples

Answer the prompts

Create a workspace for one repository

Pin base branches and skip the image

Choose an environment when the default is disabled

Errors

​Synopsis

​Arguments

​Prompts

​Where the workspace is recorded

​Requirements

​Examples

​Answer the prompts

​Create a workspace for one repository

​Pin base branches and skip the image

​Choose an environment when the default is disabled

​Errors

​Related

Synopsis

Arguments

Prompts

Where the workspace is recorded

Requirements

Examples

Answer the prompts

Create a workspace for one repository

Pin base branches and skip the image

Choose an environment when the default is disabled

Errors

Related