{"id":13581490,"url":"https://github.com/recode-sh/cli","last_synced_at":"2026-01-12T00:06:34.858Z","repository":{"id":55377066,"uuid":"497984058","full_name":"recode-sh/cli","owner":"recode-sh","description":"A CLI to create remote development environments in your cloud provider account in seconds","archived":false,"fork":false,"pushed_at":"2022-11-18T08:10:41.000Z","size":14498,"stargazers_count":609,"open_issues_count":5,"forks_count":9,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-12-22T18:04:04.392Z","etag":null,"topics":["aws","cli","golang","recode"],"latest_commit_sha":null,"homepage":"https://recode.sh","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/recode-sh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-05-30T14:46:28.000Z","updated_at":"2024-12-19T09:25:08.000Z","dependencies_parsed_at":"2023-01-22T02:16:29.895Z","dependency_job_id":null,"html_url":"https://github.com/recode-sh/cli","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recode-sh%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recode-sh%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recode-sh%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recode-sh%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/recode-sh","download_url":"https://codeload.github.com/recode-sh/cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247470353,"owners_count":20944146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","cli","golang","recode"],"created_at":"2024-08-01T15:02:03.340Z","updated_at":"2025-04-06T10:32:31.145Z","avatar_url":"https://github.com/recode-sh.png","language":"Go","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/1233275/172015327-7234ec48-fe57-4a7b-b48e-baf5e6d67aab.png\" alt=\"recode\" width=\"180\" height=\"180\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ch1 align=\"center\"\u003eRecode\u003c/h1\u003e\n    \u003cp align=\"center\"\u003eRemote development environments defined as code. Running in your cloud provider account.\u003cbr/\u003e Currently available on \u003ca href=\"https://github.com/recode-sh/aws-cloud-provider\"\u003eAmazon Web Services\u003c/a\u003e and Visual Studio Code.\u003c/p\u003e\n\u003c/p\u003e\n\n\u003cblockquote align=\"left\"\u003e\n  ... you can think of it as a desktop version of Gitpod / Coder / GitHub Codespaces less polished and with less features but 100% free, 100% open-source and 100% community-driven\n\u003c/blockquote\u003e\n\n```bash\nrecode aws start recode-sh/workspace --instance-type t2.medium\n```\n\nhttps://user-images.githubusercontent.com/1233275/172346442-d6fef09c-2ef0-4633-8d72-e20bef8fc1a9.mp4\n\n\u003cimg width=\"1136\" alt=\"vscode\" src=\"https://user-images.githubusercontent.com/1233275/172015213-0ba516b6-fe24-4bd4-8ad4-d876c6188f3c.png\"\u003e\n\n\u003cblockquote align=\"left\"\u003e\n  ... see the \u003ca href=\"https://github.com/recode-sh/workspace\"\u003erecode-sh/workspace\u003c/a\u003e repository for an example of development environment configuration\n\u003c/blockquote\u003e\n\n## Table of contents\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n    - [Login](#login)\n    - [Start](#start)\n    - [Stop](#stop)\n    - [Remove](#remove)\n    - [Uninstall](#uninstall)\n- [Development environments configuration](#development-environments-configuration)\n    - [Tip: the --rebuild flag](#-tip-the---rebuild-flag)\n    - [Tip: Docker \u0026 Docker compose](#-tip-docker--docker-compose)\n    - [User configuration](#user-configuration)\n    - [Project configuration](#project-configuration)\n        - [What if I don't have an user configuration?](#-what-if-i-dont-have-an-user-configuration)\n    - [Recode configuration](#recode-configuration)\n        - [Base image (recode-sh/base-dev-env)](#base-image-recode-shbase-dev-env)\n        - [Visual Studio Code extensions](#visual-studio-code-extensions)\n        - [Multiple repositories](#multiple-repositories)\n        - [Build arguments (RECODE_INSTANCE_OS and RECODE_INSTANCE_ARCH)](#build-arguments-recode_instance_os-and-recode_instance_arch)\n        - [Hooks](#hooks)\n- [Frequently asked questions](#frequently-asked-questions)\n    - [How does it compare with GitPod / Coder / Codespaces / X?](#-how-does-it-compare-with-gitpod--coder--codespaces--x)\n    - [How does it compare with Vagrant / VSCode remote SSH / Container extensions?](#-how-does-it-compare-with-vagrant--vscode-remote-ssh--container-extensions)\n    - [Why using Docker as a VM and not something like NixOS, for example?](#-why-using-docker-as-a-vm-and-not-something-like-nixos-for-example)\n    - [Given that my dev env will run in a container does it mean that it will be limited?](#-given-that-my-dev-env-will-run-in-a-container-does-it-mean-that-it-will-be-limited)\n- [The future](#the-future)\n- [License](#license)\n\n## Requirements\n\nThe Recode binary has been tested on Linux and Mac. Support for Windows is theoretical ([testers needed](https://github.com/recode-sh/cli/issues/4) 💙).\n\nBefore using Recode, the following dependencies need to be installed:\n\n- [Visual Studio Code](https://code.visualstudio.com/) (currently the sole editor supported).\n\n- [OpenSSH Client](https://www.openssh.com/) (used to access your development environments).\n\n## Installation\n\nThe easiest way to install Recode is by running the following command in your terminal:\n\n```bash\ncurl -sf https://raw.githubusercontent.com/recode-sh/cli/main/install.sh | sh -s -- -b /usr/local/bin latest\n```\n\nThis command could be run as-is or by changing:\n\n  - The installation directory by replacing `/usr/local/bin` with your **preferred path**.\n  \n  - The version installed by replacing `latest` with a **[specific version](https://github.com/recode-sh/cli/releases)**.\n\nOnce done, you could confirm that Recode is installed by running the `recode` command:\n\n```bash\nrecode --help\n```\n\n## Usage\n\n```console\nTo begin, run the command \"recode login\" to connect your GitHub account.\t\n\nFrom there, the most common workflow is:\n\n  - recode \u003ccloud_provider\u003e start \u003crepository\u003e  : to start a development environment for a specific GitHub repository\n  - recode \u003ccloud_provider\u003e stop \u003crepository\u003e   : to stop a development environment (without removing your data)\n  - recode \u003ccloud_provider\u003e remove \u003crepository\u003e : to remove a development environment AND your data\n  \n\u003crepository\u003e may be relative to your personal GitHub account (eg: cli) or fully qualified (eg: my-organization/api).\n\nUsage:\n  recode [command]\n\nAvailable Commands:\n  aws         Use Recode on Amazon Web Services\n  completion  Generate the autocompletion script for the specified shell\n  help        Help about any command\n  login       Connect a GitHub account to use with Recode\n\nFlags:\n  -h, --help    help for recode\n  -v, --version version for recode\n\nUse \"recode [command] --help\" for more information about a command.\n```\n\n### Login\n\n```bash\nrecode login\n```\nTo begin, you need to run the `login` command to connect your GitHub account.\n\nRecode requires the following permissions:\n\n  - \"*Public SSH keys*\" and \"*Repositories*\" to let you access your repositories from your development environments.\n\t\n  - \"*GPG Keys*\" and \"*Personal user data*\" to configure Git and sign your commits (verified badge).\n\n**All your data (including the OAuth access token) are only stored locally in `~/.config/recode/recode.yml` (or in `XDG_CONFIG_HOME` if set).**\n\nThe source code that implements the GitHub OAuth flow is located in the [recode-sh/api](https://github.com/recode-sh/api) repository.\n\n### Start\n\n```bash\nrecode \u003ccloud_provider\u003e start \u003crepository\u003e\n```\nThe `start` command creates and starts a development environment for a specific GitHub repository.\n\nIf a development environment is stopped, it will only be started. If a development environment is already started, only your code editor will be opened.\n\nAn `--instance-type` flag could be passed to specify the instance type that will power your development environment. (*See the corresponding cloud provider repository for default / valid values*).\n\n#### Examples\n\n```bash\nrecode aws start recode-sh/workspace\n```\n\n```bash\nrecode aws start recode-sh/workspace --instance-type t2.medium\n```\n\n### Stop\n\n```bash\nrecode \u003ccloud_provider\u003e stop \u003crepository\u003e\n```\nThe `stop` command stops a started development environment.\n\nStopping means that the underlying instance will be stopped but **\u003cins\u003eyour data will be conserved\u003c/ins\u003e**. You may want to use this command to save costs when the development environment is not used.\n\n#### Example\n\n```bash\nrecode aws stop recode-sh/workspace\n```\n\n### Remove\n\n```bash\nrecode \u003ccloud_provider\u003e remove \u003crepository\u003e\n```\n\nThe `remove` command removes an existing development environment.\n\nRemoving means that the underlying instance **\u003cins\u003eand all your data\u003c/ins\u003e** will be **\u003cins\u003epermanently removed\u003c/ins\u003e**.\n\n#### Example\n\n```bash\nrecode aws remove recode-sh/workspace\n```\n\n### Uninstall\n\n```bash\nrecode \u003ccloud_provider\u003e uninstall\n```\n\nThe `uninstall` command removes all the infrastructure components used by Recode from your cloud provider account. (*See the corresponding cloud provider repository for details*).\n\n**Before running this command, all development environments need to be removed.**\n\n#### Example\n\n```bash\nrecode aws uninstall\n```\n\n## Development environments configuration\n\nIf you think about all the projects you've worked on, you may notice that you've:\n\n  - a set of configuration / tools used for all your projects (eg: a preferred timezone / locale, a specific shell...);\n  \n  - a set of configuration / tools specific for each project (eg: docker compose, go \u003e= 1.18 or node.js \u003e= 14).\n\nThis is what Recode has tried to mimic with *user* and *project* configuration.\n\n#### 💡 Tip: the `--rebuild` flag\n\n```bash\nrecode aws start recode-sh/workspace --rebuild\n```\n\nIf you update the configuration of an existing development environment, you could use the `--rebuild` flag of the `start` command to rebuild it without having to delete it first.\n\n#### 💡 Tip: Docker \u0026 Docker compose\n\nDocker and Docker compose are already preinstalled in all development environments so you don't have to install them.\n\n### User configuration\n\nUser configuration corresponds to the set of configuration / tools used for all your projects. To create an user configuration, all you need to do is to:\n\n  1. Create a \u003cins\u003e**repository**\u003c/ins\u003e named `.recode` in your personal GitHub account.\n  \n  2. Add a file named `dev_env.Dockerfile` in it.\n\nThe file `dev_env.Dockerfile` is a regular Dockerfile except that: \n\n  - it must derive from `recode-sh/base-dev-env` (more below);\n  \n  - the user configuration needs to be applied to the user `recode`.\n\nOtherwise, you are free to do what you want with this file and this repository. You could see an example with dotfiles in [recode-sh/.recode](https://github.com/recode-sh/.recode) and use it as a GitHub repository template: \n\n```Dockerfile\n# User's dev env image must derive from recodesh/base-dev-env.\n# See https://github.com/recode-sh/base-dev-env/blob/main/Dockerfile for source.\nFROM recodesh/base-dev-env:latest\n\n# Set timezone\nENV TZ=America/Los_Angeles\n\n# Set locale\nRUN sudo locale-gen en_US.UTF-8\nENV LANG=en_US.UTF-8\nENV LANGUAGE=en_US:en \nENV LC_ALL=en_US.UTF-8\n\n# Install Zsh\nRUN set -euo pipefail \\\n  \u0026\u0026 sudo apt-get --assume-yes --quiet --quiet update \\\n  \u0026\u0026 sudo apt-get --assume-yes --quiet --quiet install zsh \\\n  \u0026\u0026 sudo rm --recursive --force /var/lib/apt/lists/*\n\n# Install OhMyZSH and some plugins\nRUN set -euo pipefail \\\n  \u0026\u0026 sh -c \"$(curl --fail --silent --show-error --location https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)\" \\\n  \u0026\u0026 git clone --quiet https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions \\\n  \u0026\u0026 git clone --quiet https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting\n\n# Change default shell for user \"recode\"\nRUN set -euo pipefail \\\n  \u0026\u0026 sudo usermod --shell $(which zsh) recode\n\n# Add all dotfiles to home folder\nCOPY --chown=recode:recode ./dotfiles/.* $HOME/\n```\n\n### Project configuration\n\nProject configuration corresponds to the set of configuration / tools specific for each project. As you may have guessed, to create a project configuration, all you need to do is to:\n\n  1. Create a \u003cins\u003e**directory**\u003c/ins\u003e named `.recode` in your project's repository.\n  \n  2. Add a file named `dev_env.Dockerfile` in it.\n\nThe file `dev_env.Dockerfile` is a regular Dockerfile except that: \n\n  - it must derive from `user_dev_env` (your user configuration);\n  \n  - the user configuration needs to be applied to the user `recode`.\n\nOtherwise, you are free to do what you want with this file and this directory. You could see an example in [recode-sh/workspace](https://github.com/recode-sh/workspace):\n\n```Dockerfile\n# Project's dev env image must derive from \"user_dev_env\"\n# (ie: github_user_name/.recode/dev_env.Dockerfile)\nFROM user_dev_env\n\n# VSCode extensions that need to be installed (optional)\nLABEL sh.recode.vscode.extensions=\"golang.go, zxh404.vscode-proto3, ms-azuretools.vscode-docker\"\n\n# GitHub repositories that need to be cloned (optional) (default to the current one)\nLABEL sh.recode.repositories=\"cli, agent, recode, aws-cloud-provider, base-dev-env, api, .recode, workspace\"\n\n# Reserved args (RECODE_*). Provided by Recode.\n# eg: linux\nARG RECODE_INSTANCE_OS\n# eg: amd64 or arm64\nARG RECODE_INSTANCE_ARCH\n\nARG GO_VERSION=1.18.2\n\n# Install Go and dev dependencies\nRUN set -euo pipefail \\\n  \u0026\u0026 cd /tmp \\\n  \u0026\u0026 LATEST_GO_VERSION=$(curl --fail --silent --show-error --location \"https://golang.org/VERSION?m=text\") \\\n  \u0026\u0026 if [[ \"${GO_VERSION}\" = \"latest\" ]] ; then \\\n        GO_VERSION_TO_USE=\"${LATEST_GO_VERSION}\" ; \\\n     else \\\n        GO_VERSION_TO_USE=\"go${GO_VERSION}\" ; \\\n     fi \\\n  \u0026\u0026 curl --fail --silent --show-error --location \"https://go.dev/dl/${GO_VERSION_TO_USE}.${RECODE_INSTANCE_OS}-${RECODE_INSTANCE_ARCH}.tar.gz\" --output go.tar.gz \\\n  \u0026\u0026 sudo tar --directory /usr/local --extract --file go.tar.gz \\\n  \u0026\u0026 rm go.tar.gz \\\n  \u0026\u0026 /usr/local/go/bin/go install golang.org/x/tools/cmd/goimports@latest \\\n  \u0026\u0026 /usr/local/go/bin/go install github.com/google/wire/cmd/wire@latest \\\n  \u0026\u0026 /usr/local/go/bin/go install github.com/golang/mock/mockgen@latest\n\n# Add Go to path\nENV PATH=$PATH:/usr/local/go/bin:$HOME/go/bin\n\n...\n```\n#### 💡 What if I don't have an user configuration?\n\nIf you don't have an user configuration, **the [recode-sh/.recode](https://github.com/recode-sh/.recode) repository will be used as a default one**.\n\nThat's why you will have `zsh` configured as default shell in your project.\n\n### Recode configuration\n\nAs you may have noticed from previous sections, some commands in the `dev_env.Dockerfile` files (like the `LABEL` ones) are specific to Recode. This section will try to explain them.\n\n#### Base image ([recode-sh/base-dev-env](http://github.com/recode-sh/base-dev-env))\n\nAs you may have understood, all the development environments derive directly or indirectly from `recode-sh/base-dev-env`. You could see the source of this Docker image in the [recode-sh/base-dev-env](https://github.com/recode-sh/base-dev-env) repository:\n\n```Dockerfile\n# All development environments will be Ubuntu-based\nFROM ubuntu:22.04\n\nARG DEBIAN_FRONTEND=noninteractive\n\n# RUN will use bash\nSHELL [\"/bin/bash\", \"-c\"]\n\n# We want a \"standard Ubuntu\"\n# (ie: not one that has been minimized\n# by removing packages and content\n# not required in a production system)\nRUN yes | unminimize\n\n# Install system dependencies\nRUN set -euo pipefail \\\n  \u0026\u0026 apt-get --assume-yes --quiet --quiet update \\\n  \u0026\u0026 apt-get --assume-yes --quiet --quiet install \\\n  apt-transport-https \\\n  build-essential \\\n  ca-certificates \\\n  curl \\\n  git \\\n  gnupg \\\n  locales \\\n  lsb-release \\\n  man-db \\\n  manpages-posix \\\n  nano \\\n  sudo \\\n  tzdata \\\n  unzip \\\n  vim \\\n  wget \\\n  \u0026\u0026 rm --recursive --force /var/lib/apt/lists/*\n\n# Install the Docker CLI. \n# The Docker daemon socket will be mounted from instance.\nRUN set -euo pipefail \\\n  \u0026\u0026 curl --fail --silent --show-error --location https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor --output /usr/share/keyrings/docker-archive-keyring.gpg \\\n  \u0026\u0026 echo \"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release --codename --short) stable\" | tee /etc/apt/sources.list.d/docker.list \u003e /dev/null \\\n  \u0026\u0026 apt-get --assume-yes --quiet --quiet update \\\n  \u0026\u0026 apt-get --assume-yes --quiet --quiet install docker-ce-cli \\\n  \u0026\u0026 rm --recursive --force /var/lib/apt/lists/*\n\n# Install Docker compose\nRUN set -euo pipefail \\\n  \u0026\u0026 LATEST_COMPOSE_VERSION=$(curl --fail --silent --show-error --location \"https://api.github.com/repos/docker/compose/releases/latest\" | grep --only-matching --perl-regexp '(?\u003c=\"tag_name\": \").+(?=\")') \\\n  \u0026\u0026 curl --fail --silent --show-error --location \"https://github.com/docker/compose/releases/download/${LATEST_COMPOSE_VERSION}/docker-compose-$(uname --kernel-name)-$(uname --machine)\" --output /usr/libexec/docker/cli-plugins/docker-compose \\\n  \u0026\u0026 chmod +x /usr/libexec/docker/cli-plugins/docker-compose\n\n# Install entrypoint script\nCOPY ./recode_entrypoint.sh /\nRUN chmod +x /recode_entrypoint.sh\n\n# Configure the user \"recode\" in container.\n# Triggered during build on instance.\n# \n# We want the user \"recode\" inside the container to get \n# the same permissions than the user \"recode\" in the instance \n# (to access the Docker daemon, SSH keys and so on).\n# \n# To do this, the two users need to share the same UID/GID.\nONBUILD ARG RECODE_USER_ID\nONBUILD ARG RECODE_USER_GROUP_ID\nONBUILD ARG RECODE_DOCKER_GROUP_ID\n\nONBUILD RUN set -euo pipefail \\\n  \u0026\u0026 RECODE_USER_HOME_DIR=\"/home/recode\" \\\n  \u0026\u0026 RECODE_USER_WORKSPACE_DIR=\"${RECODE_USER_HOME_DIR}/workspace\" \\\n  \u0026\u0026 RECODE_USER_WORKSPACE_CONFIG_DIR=\"${RECODE_USER_HOME_DIR}/.workspace-config\" \\\n  \u0026\u0026 groupadd --gid \"${RECODE_USER_GROUP_ID}\" --non-unique recode \\\n  \u0026\u0026 useradd --gid \"${RECODE_USER_GROUP_ID}\" --uid \"${RECODE_USER_ID}\" --non-unique --home \"${RECODE_USER_HOME_DIR}\" --create-home --shell /bin/bash recode \\\n  \u0026\u0026 cp /etc/sudoers /etc/sudoers.orig \\\n  \u0026\u0026 echo \"recode ALL=(ALL) NOPASSWD:ALL\" | tee /etc/sudoers.d/recode \u003e /dev/null \\\n  \u0026\u0026 groupadd --gid \"${RECODE_DOCKER_GROUP_ID}\" --non-unique docker \\\n  \u0026\u0026 usermod --append --groups docker recode \\\n  \u0026\u0026 mkdir --parents \"${RECODE_USER_WORKSPACE_CONFIG_DIR}\" \\\n  \u0026\u0026 mkdir --parents \"${RECODE_USER_WORKSPACE_DIR}\" \\\n  \u0026\u0026 mkdir --parents \"${RECODE_USER_HOME_DIR}/.ssh\" \\\n  \u0026\u0026 mkdir --parents \"${RECODE_USER_HOME_DIR}/.gnupg\" \\\n  \u0026\u0026 mkdir --parents \"${RECODE_USER_HOME_DIR}/.vscode-server\" \\\n  \u0026\u0026 chown --recursive recode:recode \"${RECODE_USER_HOME_DIR}\" \\\n  \u0026\u0026 chmod 700 \"${RECODE_USER_HOME_DIR}/.gnupg\"\n\nONBUILD WORKDIR /home/recode/workspace\nONBUILD USER recode\n\nONBUILD ENV USER=recode\nONBUILD ENV HOME=/home/recode\nONBUILD ENV EDITOR=/usr/bin/nano\n\nONBUILD ENV RECODE_WORKSPACE=/home/recode/workspace\nONBUILD ENV RECODE_WORKSPACE_CONFIG=/home/recode/.workspace-config\n\n# Only for documentation purpose.\n# Entrypoint and CMD are always set by the \n# Recode agent when running the dev env container.\nONBUILD ENTRYPOINT [\"/recode_entrypoint.sh\"]\nONBUILD CMD [\"sleep\", \"infinity\"]\n\n# Set default timezone\nENV TZ=America/Los_Angeles\n\n# Set default locale\n# /!\\ locale-gen must be run as root\nRUN locale-gen en_US.UTF-8\nENV LANG=en_US.UTF-8\nENV LANGUAGE=en_US:en\nENV LC_ALL=en_US.UTF-8\n```\n\nAs you can see, nothing fancy here. \n\nRecode is built on `ubuntu` with `docker` and `docker compose` pre-installed. An user `recode` is created and configured to be used as the default user. Root privileges are managed via `sudo`.\n\nYour repositories will be cloned in `/home/recode/workspace`. A default timezone and locale are set.\n\n*(To learn more, see the [recode-sh/base-dev-env](https://github.com/recode-sh/base-dev-env) repository)*.\n\n#### Visual Studio Code extensions\n\nIn order to require Visual Studio Code extensions to be installed in your development environment, you need to add a `LABEL` named `sh.recode.vscode.extensions` in your *user's* or *project's* `dev_env.Dockerfile`.\n\n*(As you may have guessed, if this label is added to your user configuration, all your projects will have the listed extensions installed).*\n\nAn extension is identified using its publisher name and extension identifier (`publisher.extension`). You can see the name on the extension's detail page.\n\n##### Example\n\n```Dockerfile\nLABEL sh.recode.vscode.extensions=\"golang.go, zxh404.vscode-proto3, ms-azuretools.vscode-docker\"\n```\n\n#### Multiple repositories\n\nIf you want to use multiple repositories in your development environment, you need to add a `LABEL` named `sh.recode.repositories` in your *project's* `dev_env.Dockerfile`.\n\n**In this case, we recommend you to create an empty repository that will only contain the `.recode` directory (as an example, see the [recode-sh/workspace](https://github.com/recode-sh/workspace) repository).**\n\n*(As you may have guessed, if this label is added to your user configuration it will be ignored).*\n\nRepositories may be set as relative to the current one (eg: `cli`) or fully qualified (eg: `recode-sh/cli`).\n\n##### Example\n\n```Dockerfile\nLABEL sh.recode.repositories=\"cli, agent, recode, aws-cloud-provider, base-dev-env, api, .recode, workspace\"\n```\n\n#### Build arguments (`RECODE_INSTANCE_OS` and `RECODE_INSTANCE_ARCH`)\n\nGiven the nature of this project, you need to take into account the fact that the characteristics of the instance used to run your development environment may vary depending on the one chosen by the final user.\n\nAs an example, an user may want to use an AWS graviton powered instance to run your project and, as a result, your *project's* `dev_env.Dockerfile` must be ready to be built for `ARM`.\n\nTo ease this process, Recode will pass to your `dev_env.Dockerfile` files two build arguments `RECODE_INSTANCE_OS` and `RECODE_INSTANCE_ARCH` that will contain both the current operating system (`linux`) and architecture (eg: `amd64`) respectively.\n\n##### Example\n\n```Dockerfile\n# Reserved args (RECODE_*). Provided by Recode.\n\n# eg: linux\nARG RECODE_INSTANCE_OS\n\n# eg: amd64 or arm64\nARG RECODE_INSTANCE_ARCH\n```\n\n#### Hooks\n\nHooks are shell scripts that will be run during the lifetime of your development environment. To be able to add a hook in a project, all you have to do is to add a directory named `hooks` in your `.recode` **directory**.\n\n##### First Hook\n\nBefore adding your first hook, the following things must be taken into account:\n\n - In the case of development environments **with only one repository**, hooks will only be run if a `dev_env.Dockerfile` file is set.\n \n - In the case of development environments **with multiple repositories**, all the hooks will be run, one after the other.\n \n - **The working directory of your scripts will be set to the root folder of their respective repository before running**.\n\n##### Init\n\nThe `init` hook is run once, **during the first start of your development environment**. You could use it to download your project dependencies, for example.\n\nCurrently, it's the sole hook available. To activate it, you need to add an `init.sh` file in your project's `hooks` directory.\n\n##### Example (taken from the [recode-sh/cli](https://github.com/recode-sh/cli/tree/main/.recode) repository)\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\nlog () {\n  echo -e \"${1}\" \u003e\u00262\n}\n\nlog \"Downloading dependencies listed in go.mod\"\n\ngo mod download\n```\n\n## Frequently asked questions\n\n#### \u003e How does it compare with GitPod / Coder / Codespaces / X?\n\n- 100% Free.\n- 100% Open-source.\n- 100% Private (run on your own cloud provider account).\n- 100% Cost-effective (run on simple VMs not on Kubernetes).\n- 100% Desktop.\n- 100% Multi regions.\n- 100% Customizable (from VM characteristics to installed runtimes).\n- 100% Community-driven (see below).\n\n... and 0% VC-backed. 0% Locked-in. 0% Proprietary config files.\n\n#### \u003e How does it compare with Vagrant / VSCode remote SSH / Container extensions?\n\n- Remote development environments defined as code (with support for user and project configuration).\n- Automatic infrastructure / VM provisionning for multiple cloud providers.\n- Fully integrated with GitHub (private and multiple repositories, verified commits...).\n- Support the pre-installation of VSCode extensions.\n- Doesn't require a VM or Docker to be installed locally.\n- Doesn't tied to a specific code editor.\n\n#### \u003e Why using Docker as a VM and not something like NixOS, for example?\n\nI'm aware that containers are not meant to be used as a VM like that (forgive me for that 🙏) but, at the time of writing, Docker is still the most widely used tool among developers to configure their environment (even if it may certainly change in the future).\n\n#### \u003e Given that my dev env will run in a container does it mean that it will be limited?\n\nMostly not. \n\nGiven the scope of this project (a private instance running in your own cloud provider account), Docker is mostly used for configuration purpose and not to \"isolate\" the VM from your environment.\n\nAs a result, your development environment container will run in **[privileged mode](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)** in the **[host network](https://docs.docker.com/network/host/)**.\n\n## The future\n\nThis project is **100% community-driven**, meaning that except for bug fixes \u003cins\u003e**no more features will be added**\u003c/ins\u003e. \n\nThe only features that will be added are the ones that will be [posted as an issue](https://github.com/recode-sh/cli/issues/new) and that will receive a significant amount of upvotes **(\u003e= 10 currently)**.\n\n## License\n\nRecode is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","funding_links":[],"categories":["Go","cli","Uncategorized"],"sub_categories":["Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecode-sh%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frecode-sh%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecode-sh%2Fcli/lists"}