Create a Codespace with gh codespace create Defaults

A Codespace you created in a hurry sits on the default machine size and idle timeout, and you find out when the bill arrives. gh codespace create lets you set repository, branch and lifecycle up front, then check GitHub built what you asked for. The examples use GitHub CLI 2.87.3, installed on this machine, and take about five minutes plus the image build.

You need:

• The gh command and an authenticated GitHub account.
• Access to the repository.
• Codespaces availability for that account or organisation.

This command creates a remote development environment. Treat machine size, idle timeout and retention period as operational and cost decisions, not harmless labels.

1. Check the command before creating anything

Read the installed help and confirm the account is the one you mean to use:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh codespace create --help
Create a codespace

If you have not authenticated, use gh auth login and complete its prompts. Check the selected account with gh auth status. Do not copy a command from another terminal session until you have checked its repository owner and account.

2. Create a Codespace from a branch

Use the repository's full owner/name and an existing branch. Replace both placeholders before pressing Enter:

$ gh codespace create \
    --repo OWNER/REPOSITORY \
    --branch BRANCH_NAME \
    --display-name project-dev \
    --idle-timeout 30m \
    --retention-period 72h \
    --status

• --repo and --branch. Identify the repository and select its branch.
• Display name. Limited to 48 characters.
• Idle timeout. How long inactivity is allowed before the Codespace is stopped.
• Retention period. How long it may remain after stopping before automatic deletion, with a maximum of 30 days.
• --status. Shows the status of post-create commands and dotfiles.

There is no useful fixed output to paste into a runbook: the name and provisioning messages depend on the repository and GitHub account. Wait for the command to finish.

This command normally needs no sudo. GitHub authentication and repository permissions are the relevant access checks, and local root privileges grant neither.

3. Verify the created resource

List your Codespaces and filter by repository:

$ gh codespace list --repo OWNER/REPOSITORY
NAME                         DISPLAY NAME   REPOSITORY           BRANCH  STATE
example-quiet-otter-abc123   project-dev    OWNER/REPOSITORY     BRANCH  Available

Output columns vary with the CLI version and account data. The useful checks are repository, branch, display name and state. If more than one row matches, use the unique name in the first column for the next command.

$ gh codespace view --codespace CODESPACE_NAME --json name,repository,state,machineName,idleTimeoutMinutes,retentionPeriodDays
{"name":"CODESPACE_NAME","repository":"OWNER/REPOSITORY","state":"Available","machineName":"basicLinux32gb","idleTimeoutMinutes":30,"retentionPeriodDays":3}

The installed gh codespace view supports those JSON field names. The actual machine name and resource state will differ.

4. Choose machine and location deliberately

Pass --machine when the repository needs particular hardware:

$ gh codespace create \
    --repo OWNER/REPOSITORY \
    --branch BRANCH_NAME \
    --machine MACHINE_NAME \
    --location WestEurope \
    --display-name project-dev

The installed manual accepts a hardware specification through --machine. Its listed location values are EastUs, SouthEastAsia, WestEurope and WestUs2. If you omit --location, the location is determined automatically. Do not invent a machine name: get one offered for the repository and account, then pass it exactly.

5. Set dev container and permission choices

If the repository has more than one dev container configuration, select the intended file explicitly:

$ gh codespace create \
    --repo OWNER/REPOSITORY \
    --branch BRANCH_NAME \
    --devcontainer-path .devcontainer/devcontainer.json

The path is the devcontainer.json file used for creation. Check that it exists in the selected branch and review its lifecycle commands before you start a remote environment.

By default, the command can prompt when the Codespace requests additional permissions. --default-permissions suppresses that prompt and accepts the additional permissions the Codespace requested.

6. Use the browser shortcut and know the undo path

--web creates the Codespace from a browser. It cannot be combined with --display-name, --idle-timeout or --retention-period:

$ gh codespace create --repo OWNER/REPOSITORY --branch BRANCH_NAME --web

Use this mode when you want GitHub's browser flow to handle the remaining choices, and do not add the conflicting flags to the same command.

For a normal correction, stop the Codespace when you are finished and use the edit or management commands to change supported settings. The create command is not an edit operation, and rerunning it creates another request.