README.md

Eleven

Code sandboxes with automatic HTTPS and long running processes. Running in VMs in your cloud provider account.
Currently available on Amazon Web Services and Hetzner.

... use it as a remote development environment, to test some code or even to deploy your app. It's up to you!

eleven aws init hello-world --runtimes [email protected] --repositories eleven-sh/hello-world

... now that this sandbox is created, you can connect to it with your preferred editor:

eleven aws edit hello-world

... finally, now that you have finished working on your application, you may want to deploy it:

me@home:~$ ssh eleven/hello-world # or use your editor's integrated terminal

eleven@hello-world:~/workspace/hello-world$ node index.js # test that your app starts (optional)
Server running at http://127.0.0.1:8000/
^C (Control-C)

eleven@hello-world:~/workspace/hello-world$ forever node index.js
Forever: command started. Run "forever stop" in current path to stop.

eleven@hello-world:~/workspace/hello-world$ exit
Connection to 34.202.238.110 closed.

... add an A record pointing to your sandbox's public IP address for the domain that you want to use, then run:

me@home:~$ eleven aws serve hello-world 8000 --as hello.eleven.sh
Success! The port "8000" is now reachable at: https://hello.eleven.sh

me@home:~$ curl https://hello.eleven.sh
Hello World

Table of contents

• Requirements
• Installation (and update)
• Usage
  • Login
  • Init
    • --instance-type
    • --runtimes
    • --repositories
  • Edit
  • Serve
  • Unserve
  • Remove
  • Uninstall
• Long running processes (Forever)
  • Start
  • Stop
• Frequently asked questions
  • What do you mean by "code sandbox"?
  • What will be created in my cloud account?
  • How much will it cost me?
• License

Requirements

The Eleven CLI has been tested on Linux and MacOS. Support for Windows is theoretical (testers needed 💙).

Before using Eleven, the following dependencies need to be installed:

• OpenSSH Client (used to access your sandboxes).

Before running the edit command, one of the following editors need to be installed:

• Microsoft Visual Studio Code (currently the sole editor supported).

Installation (and update)

The process required to install the Eleven CLI vary depending on your operating system:

• On Linux and MacOS, the easiest way to install it is by running the following command in your terminal:

  curl -sf https://raw.githubusercontent.com/eleven-sh/cli/main/install.sh | sh -s -- -b /usr/local/bin latest

  This command could be run as-is or by changing:

  • The installation directory by replacing /usr/local/bin with your preferred path.

  • The version installed by replacing latest with a specific version.

• On Windows, the easiest way is by running the following Powershell script:

  irm https://raw.githubusercontent.com/eleven-sh/cli/main/install.ps1 | iex

Once done, you could confirm that Eleven is installed by running the eleven command:

eleven --help

Update

The command used to install Eleven could also be used to update it to another version.

Usage

To begin, run the command "eleven login" to connect your GitHub account.	

From there, the most common workflow is:

  - eleven <cloud_provider> init <sandbox_name>   : to initialize a new sandbox

  - eleven <cloud_provider> edit <sandbox_name>   : to connect your preferred editor to a sandbox

  - eleven <cloud_provider> remove <sandbox_name> : to remove an existing sandbox

Usage:
  eleven [command]

Available Commands:
  aws         Use Eleven on Amazon Web Services
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  hetzner     Use Eleven on Hetzner
  login       Connect a GitHub account

Flags:
  -h, --help      help for eleven
  -v, --version   version for eleven

Use "eleven [command] --help" for more information about a command.

Login

eleven login

To begin, you need to run the login command to connect your GitHub account.

Eleven requires the following permissions:

• "Public SSH keys" and "Repositories" to let you access your repositories from your sandboxes.

• "Personal user data" to configure Git.

All your data (including the OAuth access token) are only stored locally in ~/.config/eleven/eleven.yml (or in XDG_CONFIG_HOME if set).

The source code that implements the GitHub OAuth flow is located in the eleven-sh/api repository.

Init

eleven <cloud_provider> init <sandbox_name> [--instance-type=<instance_type> --runtimes=<runtimes> --repositories=<repositories>]

The init command initializes a new sandbox.

To choose the type of instance that will run the sandbox, use the --instance-type flag.

To install some runtimes in the sandbox, use the --runtimes flag.

To clone some GitHub repositories in the sandbox, use the --repositories flag.

--instance-type

Valid and default values for the --instance-type flag vary depending on the cloud provider used. (See the corresponding cloud provider repository to learn more).

--runtimes

The following runtimes could be installed in all sandboxes:

• docker (latest only)

• php or [email protected] (e.g., [email protected])

• java (latest only)

• node or [email protected] (e.g., [email protected]) (via nvm)

• python or [email protected] (e.g., [email protected]) (via pyenv)

• ruby or [email protected] (e.g., [email protected]) (via rvm)

• rust or [email protected] (e.g., [email protected]) (via rustup)

• go or [email protected] (e.g., [email protected])

• clang (latest only)

All runtimes will default to @latest if the version is not set.

--repositories

Repositories may be fully qualified (e.g., eleven-sh/api) or without an account name (e.g., my-repo). Your personal account is assumed for repositories without an account name.

Examples

eleven aws init eleven-api

eleven aws init eleven-api --instance-type m4.large --runtimes [email protected],docker --repositories repo,organization/repo

Edit

eleven <cloud_provider> edit <sandbox_name>

The edit command connects your preferred editor to a sandbox.

Example

eleven aws edit eleven-api

Serve

eleven <cloud_provider> serve <sandbox_name> <port> [--as=<domain_name>]

The serve command allows TCP traffic on a port in a sandbox.

To reach the port through a domain name (via HTTP(S)), use the --as flag.

If you want to use more than one domain for a port, you could run the serve command multiple times with different domain names.

Examples

eleven aws serve eleven-api 8000

eleven aws serve eleven-api 8000 --as eleven.sh
eleven aws serve eleven-api 8000 --as www.eleven.sh

Unserve

eleven <cloud_provider> unserve <sandbox_name> <port>

The unserve command disallows TCP traffic on a port in a sandbox.

Once TCP traffic is disallowed, the port becomes unreachable from outside.

Example

eleven aws unserve eleven-api 8000

Remove

eleven <cloud_provider> remove <sandbox_name> [--force]

The remove command removes an existing sandbox.

The sandbox will be PERMANENTLY removed along with ALL your un-pushed work.

There is no going back, so please be sure before running this command.

The --force flag could be used to remove without confirmation.

Examples

eleven aws remove eleven-api

eleven aws remove eleven-api --force

Uninstall

eleven <cloud_provider> uninstall

The uninstall command removes all the infrastructure components used by Eleven from your cloud provider account. (See the corresponding cloud provider repository for details).

All your sandboxes must be removed before running this command.

Example

eleven aws uninstall

Long running processes (Forever)

In order to ease the process of managing long running processes, a CLI named forever is available inside your sandboxes.

(Except for the name, this CLI doesn't have anything in common with the one available on npm).

Start

forever <command>

The forever command starts the passed command in the current path and relaunches it in case of exit or after instance restart.

You cannot have more than one command running per path.

Examples

forever node index.js

forever docker compose up

Stop

forever stop

The stop command stops a command started in the current path.

Frequently asked questions

> What do you mean by "code sandbox"?

In the context of Eleven, a "code sandbox" is nothing more than a VM, configured and ready-to-use, running in your cloud provider account.

It's called "code sandbox" because the code that you will run in it will be 100% isolated from your local computer (unlike containers).

> What will be created in my cloud account?

The infrastructure components that will be created in your account will vary depending on the cloud provider used.

See the "Infrastructure components" section of the corresponding cloud provider repository to learn more (e.g., here for AWS and here for Hetzner).

> How much will it cost me?

Eleven is 100% free. However, using a VM in your cloud provider account is not.

See the "Infrastructure costs" section of the corresponding cloud provider repository to learn more (e.g., here for AWS and here for Hetzner).

License

Eleven is available as open source under the terms of the MIT License.