Skip to content

About

Generate reproducible Codespaces from a single JSON file — also works with local VS Code + Docker.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

codespacegen logo

GitHub Release GitHub Release Date GitHub Actions Workflow Status GitHub Actions Workflow Status GitHub License GitHub go.mod Go version

日本語版はこちら

codespacegen is a CLI that generates the following three files for Codespaces and Dev Container.

  • Dockerfile
  • devcontainer.json
  • docker-compose.yaml

Install with curl

The latest release is downloaded automatically and installed into /usr/local/bin.

curl -fsSL https://raw.githubusercontent.com/taka1156/codespacegen/master/scripts/install.sh | bash

To change the install destination:

curl -fsSL https://raw.githubusercontent.com/taka1156/codespacegen/master/scripts/install.sh | INSTALL_DIR=$HOME/.local/bin bash

After installation, csg is also available as a shortcut alias for codespacegen.

Release with GitHub Actions

Main generated assets:

  • codespacegen_linux_amd64.tar.gz
  • codespacegen_linux_arm64.tar.gz
  • codespacegen_darwin_amd64.tar.gz
  • codespacegen_darwin_arm64.tar.gz
  • codespacegen_windows_amd64.exe
  • checksums.txt

Architecture

  • Domain: rules and models
    • internal/domain/entity
    • internal/domain/service
  • App: composition and orchestration
    • internal/app
  • Input adapters (CLI/JSON/defaults)
    • internal/input
  • Infra (interactive prompt I/O, file writing)
    • internal/infra
    • internal/infra/filewriter
  • Workflows (use cases)
    • internal/workflow/collect
    • internal/workflow/assemble
    • internal/workflow/generate
    • internal/workflow/initialize
  • Artifact generation
    • internal/generator
  • i18n resources
    • internal/i18n
  • Entry point: CLI
    • cmd/codespacegen

Dependencies only point inward.

Usage

Run

go run ./cmd/codespacegen

By default, files are generated under .devcontainer.

Show version

Run the version subcommand to display the current version of the binary.

codespacegen version

Initialize codespacegen.json

Run the init subcommand to generate a codespacegen.json template.

codespacegen init

The generated file serves as a starting point for customizing base images and VS Code extensions.

Option Default Description
-output . Output directory for codespacegen.json

Update codespacegen

Run the update subcommand to self-update the binary to the latest release from GitHub.

codespacegen update

If the binary is already up to date, a message is printed and the command exits successfully.

Option Default Description
-lang (auto-detect) Language for CLI messages (en or ja). Defaults to system locale

Main options

Option Default Description
-output .devcontainer Output directory
-name (interactive, required) Project name. Prompted every time and mapped to the name field in devcontainer.json
-language (interactive, empty on Enter) Programming language key. Prompted every time. Any profileName defined in the langs array of codespacegen.json (or the file specified by -image-config) can be used. If empty, no language-specific setting is used and alpine:latest is selected
-service (interactive, app on Enter) Docker Compose service name. Prompted every time and reflected in both devcontainer.json and docker-compose.yaml
-workspace-folder (interactive, /workspace on Enter) Workspace path inside the container. Prompted every time
-timezone (interactive, default from common.timezone or UTC) Timezone inside the container. Prompted every time and reflected in ENV TZ and timezone setup in the Dockerfile
-image-config codespacegen.json Local path or https:// URL for base image definitions. Supports top-level common defaults plus a langs array for per-language entries. image is required when runCommand or linuxPackages is specified
-port (interactive, no ports on Enter) Port mapping. For example, 3000 is normalized to 3000:3000, and 8080:3000 is also accepted. Prompted every time
-compose-file docker-compose.yaml Compose file name
-force false Overwrite existing files
-lang (auto-detect) Language for CLI messages (en or ja). Defaults to system locale
-headless false Skip all interactive prompts. All required values must be supplied via flags

Base image definitions are separated into codespacegen.json at the repository root.

  • If the JSON file exists: values are loaded from the file

In addition, extension IDs from codespacegen.json (common.vscodeExtensions and per-language vscodeExtensions) are appended.

codespacegen.json format

You can attach the JSON Schema in editors that support JSON Schema validation and completion.

{
	"$schema": "./codespacegen.schema.json",
	"langs": [
		{
			"profileName": "go",
			"image": "golang:1.24-alpine"
		}
	]
}

If codespacegen.json is at the repository root, ./codespacegen.schema.json points to the bundled schema file in this repository.

Language entries (langs array)

Each entry in langs requires profileName and supports the following fields (image is required when runCommand or linuxPackages is specified):

{
	"langs": [
		{
			"profileName": "go",
			"image": "golang:1.24-alpine",
			"vscodeExtensions": ["golang.Go"]
		},
		{
			"profileName": "moonbit",
			"image": "ubuntu:24.04",
			"runCommand": "curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash",
			"vscodeExtensions": ["moonbit.moonbit-lang"]
		},
		{
			"profileName": "gcc",
			"image": "ubuntu:24.04",
			"linuxPackages": ["gcc", "make", "git", "binutils", "libc6-dev"],
			"vscodeExtensions": ["ms-vscode.cpptools"]
		}
	]
}

The runCommand value is injected as a RUN step in the Dockerfile:

RUN curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash

linuxPackages specifies Linux system packages. They are merged with the default package list and installed by the package manager appropriate for the base image (e.g. apt for Debian/Ubuntu, apk for Alpine).

Shared defaults with common

{
	"common": {
		"timezone": "Asia/Tokyo",
		"locale": {
			"lang": "ja_JP.UTF-8",
			"language": "ja_JP:ja",
			"lcAll": "ja_JP.UTF-8"
		},
		"vscodeExtensions": [
			"MS-CEINTL.vscode-language-pack-ja",
			"streetsidesoftware.code-spell-checker"
		]
	},
	"langs": [
		{
			"profileName": "go",
			"image": "golang:1.24-alpine",
			"vscodeExtensions": ["golang.Go"]
		}
	]
}

Merge behavior:

  • common is applied first as the base; per-language entries can only append vscodeExtensions
  • vscodeExtensions are merged in order and de-duplicated
  • timezone and locale can only be set in common; they are not available in per-language entries
  • If timezone is not set in flags or common, UTC is used

Example:

go run ./cmd/codespacegen \
	-output .devcontainer \
	-name "My Codespace" \
	-language go \
	-service app \
	-workspace-folder /workspace \
	-timezone Asia/Tokyo \
	-compose-file docker-compose.yaml \
	-force

Example using a remote JSON URL:

go run ./cmd/codespacegen -image-config https://example.com/my-base-images.json -language go -force
  • Only https:// URLs are supported. http:// is rejected
  • If the JSON is missing or not specified, built-in Alpine defaults are used

Example exposing a port:

go run ./cmd/codespacegen -language go -port 3000 -force

If -port is not specified, the CLI prompts for a port interactively during execution.

The generated docker-compose.yaml looks like this, with ports added only when a port is provided.

services:
		app:
			build: .
			tty: true
			volumes:
				- ../:/workspace

Tests

go test ./...

About

Generate reproducible Codespaces from a single JSON file — also works with local VS Code + Docker.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages