Merge Docs Changes

docs/app/docs/cli_reference/devbox.md

@@ -16,6 +16,7 @@ devbox [flags]
 ## SEE ALSO
 
 * [devbox add](./devbox_add.md)	 - Add a new package to your devbox
+* [devbox cloud](./devbox_cloud.md) - [Preview] Create and manage a remote dev environment with Devbox Cloud
 * [devbox generate](devbox_generate.md)  - Generate supporting files for your project
 * [devbox info](devbox_info.md)  - Display package and plugin info
 * [devbox init](./devbox_init.md)	 - Initialize a directory as a devbox project

docs/app/docs/cli_reference/devbox_cloud.md

@@ -0,0 +1,24 @@
+# devbox cloud
+
+Commands for managing remote development environments with Devbox Cloud. 
+
+:::note
+Devbox Cloud is currently available as an Open Beta and under active development. If you encounter any issues, please report them at https://github.com/jetpack-io/devbox/issues
+:::
+
+```bash
+devbox cloud [subcommand] [flags]
+```
+
+## Options
+
+```bash
+  -h, --help            help for generate
+  -q, --quiet   Quiet mode: Suppresses logs.
+```
+
+## SEE ALSO
+
+* [devbox](devbox.md)	 - Instant, easy, predictable development environments
+* [devbox cloud forward](devbox_cloud_forward.md)	 - [Preview] Port forwards a local port to a remote devbox cloud port
+* [devbox cloud shell](devbox_cloud_shell.md)	 - [Preview] Shell into a cloud environment that matches your local devbox environment

docs/app/docs/cli_reference/devbox_cloud_forward.md

@@ -0,0 +1,37 @@
+# devbox cloud forward
+Port forwards a local port to a remote devbox cloud port. 
+
+## Synopsis
+
+
+
+```bash
+# Connect remote port 3000 to an automatically assigned local port
+$ devbox cloud forward :3000
+Port forwarding 54653:3000
+To view in browser, visit http://localhost:54653
+```
+```bash
+# Connect remote port 3000 to local port 3000
+$ devbox cloud forward 3000:3000
+Port forwarding 3000:3000
+To view in browser, visit http://localhost:3000
+```
+```bash
+# Close all open port-forwards
+$ devbox cloud forward stop
+```
+
+Usage:
+  devbox cloud forward \<local-port\>:\<remote-port\> | :\<remote-port\> | stop | list [flags]
+  devbox cloud forward [command]
+
+Available Commands:
+  list        Lists all port forwards managed by devbox
+  stop        Stops all port forwards managed by devbox
+
+Flags:
+  -h, --help   help for forward
+
+Global Flags:
+  -q, --quiet   suppresses logs.

docs/app/docs/cli_reference/devbox_cloud_shell.md

@@ -0,0 +1,26 @@
+# devbox cloud shell
+[Preview] Shell into a remote environment on Devbox Cloud. 
+
+
+## Synopsis
+When run in a directory with a `devbox.json` file, this command will start a VM, sync your local files, and create an environment using the packages and configuration in your `devbox.json`. 
+
+If a `devbox.json` file is not detected in your current directory, the Devbox CLI will attempt to find a `devbox.json` file in parent directories, and return an error if one is not located. 
+
+To authenticate with Devbox Cloud, you must have a Github Account with a linked SSH key. Devbox will attempt to automatically detect your Github username and public key, and prompt you if one cannot be identified,
+
+For more details on how to use Devbox Cloud, consult the [Getting Started Guide](../devbox_cloud/getting_started.md)
+
+
+```bash
+# Start a Cloud Shell
+devbox cloud shell
+```
+
+## Options
+```text
+  -c, --config string     path to directory containing a devbox.json config file
+  -h, --help              help for shell
+  -u, --username string   Github username to use for ssh
+  -q, --quiet             suppresses logs. 
+```

docs/app/docs/devbox_cloud/beta_faq.md

@@ -0,0 +1,54 @@
+---
+title: Devbox Cloud Open Beta FAQ
+---
+
+### What do I need to use Devbox Cloud?
+
+To use Devbox Cloud from your Browser, you will need a Github Account. 
+
+To use Devbox Cloud from your CLI, you will need: 
+
+* A Github account with linked SSH keys
+* Devbox 0.3.0 or later 
+
+### Does my project need to use Devbox to use Devbox Cloud?
+
+While you can open any Github Repo in a Devbox Cloud Shell, you will need a `devbox.json` to install packages or configure the environment. You can create a `devbox.json` in your shell by running `devbox init`
+
+### Can I use my own IDE or editor with Devbox Cloud?
+
+Yes! You can use your own tools when you start Devbox Cloud from the terminal. See our [Getting Started Guide](getting_started.md) for more details
+
+### Do I have to pay to use Devbox Cloud during the Open Beta?
+
+Devbox Cloud is free to use during the Open Beta period, subject to the restrictions listed below. We expect to continue offering a free tier for personal use after the Open Beta period, but we will offer Paid Plans that provide more resources, concurrency, and persistence. 
+
+### What are the resource limits for Devbox Cloud VMs
+
+* **CPU**: 1 Core, shared
+* **RAM**: 1 GB
+* **SSD**: 8 GB
+
+If you need additional resources for your project, please reach out to us for **[Early Access](https://jetpack-io.typeform.com/devbox-cloud)**
+
+### I want to request more resources, persistence, or a different OS for my VM
+
+Future releases will add more flexibility and features as part of our paid plans. If you'd like to sign up for early access to these plans, please sign up for **[Early Access](https://jetpack-io.typeform.com/devbox-cloud)**
+
+### What OS does Devbox Cloud use?
+
+Alpine Linux 3.17.1, running on a x86-64 platform
+
+### How many VM's can I run concurrently?
+
+You can have up to 3 concurrent VMs per Github Account. 
+
+### How long will my Devbox Cloud Shell stay alive for?
+
+VMs will stay alive for up to 5 minutes after a user disconnects. After that point, the VM and all data will be deleted.
+
+### Where will Devbox run my VM?
+
+Devbox VMs are run as Fly Machines in local Data Centers. To minimize latency, Devbox Cloud will attempt to create a Fly Machine as close to your current location as possible. 
+
+

docs/app/docs/devbox_cloud/browser_getting_started.md

@@ -0,0 +1,47 @@
+---
+title: Getting Started From Your Browser
+---
+
+In addition to using [Devbox Cloud from your terminal](getting_started.md), you can use Devbox Cloud to preview Github projects directly in your browser. The Devbox Cloud Shell comes with the Devbox CLI preinstalled, so you can easily install your projects dependencies or run projects that include a `devbox.json`
+
+![Devbox Cloud Browser](../../static/img/devbox_cloud_browser.png)
+
+### Getting Started
+
+:::note
+If you are trying to open a private repository in Devbox Cloud, you will first have to install the [**Devbox Cloud app**](https://github.com/apps/devbox-cloud) from the Github Marketplace. This gives Devbox Cloud permissions to clone your repositories to the cloud VMs
+:::
+
+1. Navigate to the Github Repo that you want to preview in Devbox Cloud
+2. Copy the URL, and prepend it with `https://devbox.sh/`. For example, to open the Devbox repo, you would enter [https://devbox.sh/github.com/jetpack-io/devbox](http://devbox.sh/github.com/jetpack-io/devbox)
+3. Follow the prompts to sign in with your Github Account.
+4. Your project should now launch in a terminal session in your browser
+   1. If the project has a `devbox.json` in the root directory, then Devbox will automatically install your packages and launch you into a devbox shell.
+   2. If the project does not have a `devbox.json`, a blank one will be automatically created using `devbox init`. You can add packages to the VM using `devbox add`.
+
+
+### Opening a specific branch of a project
+
+You can open a specific branch of your project using the `branch` query parameter. This is useful when you want to preview a PR or WIP changes for your project. 
+
+For example: https://devbox.sh/github.com/org/repo?branch=staging would clone the `staging` branch of your project, and open it in your Cloud Shell.
+
+
+### Opening a subfolder of a project
+
+You can start your Devbox Cloud Shell in a subfolder of your project, using the `folder` query parameter. This can be useful when working with a monorepo where your project's `devbox.json` lives in a subfolder. 
+
+For example: https://devbox.sh/github.com/jetpack-io/devbox-examples?folder=development/ruby will start your terminal in the Ruby example in the Devbox Examples repo, load the configuration from the `devbox.json` in that folder, and then start a Devbox Shell.
+
+
+### Open in Devbox Badge
+
+If your project uses Devbox, you can make it easy for developers to test your project in Devbox Cloud by adding the `Open in Devbox` badge to your repo
+
+[![Open In Devbox.sh](https://jetpack.io/img/devbox/open-in-devbox.svg)](https://devbox.sh/github.com/jetpack-io/devbox)
+
+Add the following code to your README.md:
+
+```md
+[![Open In Devbox.sh](https://jetpack.io/img/devbox/open-in-devbox.svg)](https://devbox.sh/{path_to_repo})
+```

docs/app/docs/devbox_cloud/getting_started.md

@@ -0,0 +1,184 @@
+# Getting Started from your Terminal
+
+Devbox Cloud is a new way to create and run your Devbox Project in an isolated cloud environment. 
+
+Use cases for Devbox Cloud include: 
+* Testing out Packages or Scripts in an Isolated Linux Environment -- Preview different combinations or environments in a remote VM
+* Easy Preview Environments for your project -- Developers or contributors can quickly test your project in a cloud development environment, using the same packages and configuration.
+* Develop in a consistent environment from any Machine -- Log on to your Cloud Shell from anywhere, and develop in a consistent Dev environment anywhere in the world. Our VMs are deployed at the edge using Fly.io to provide a low-latency environment
+
+:::note
+Devbox Cloud is currently in Beta and under active development. 
+::: 
+
+## How It Works
+
+### Prerequisites
+Devbox Cloud Shell requires the following: 
+
+* **Devbox 0.3.0 or higher.** If you do not have Nix installed on your machine, Devbox will install it with the default configuration for your OS.
+* **A Github Account with an SSH Key Configured**. This is used by Devbox to authenticate and connect you to your Cloud VM.
+
+
+### Step 1: Authenticate with Github
+
+Devbox provides an easy password-less login flow using the SSH keys attached to your Github Account. If you do not have SSH keys configured with Github, follow the instructions here: [Connecting to Github with SSH](https://docs.github.com/en/enterprise-server@3.4/authentication/connecting-to-github-with-ssh/about-ssh)
+
+When you run `devbox cloud shell`, Devbox will first attempt to infer your Github username from your local environment, and prompt you if a username cannot be found. 
+
+Once Devbox has your username, it will authenticate you over SSH using the private/public key pair associated with your Github Account. 
+
+:::note
+All authentication is handled via SSH. Devbox never reads or stores your private key.
+:::  
+
+### Step 2: Launch your Devbox Shell in a Cloud VM
+
+Once you are authenticated, Devbox will provision and start your Cloud Shell: 
+1. First, we will provision a VM within your region and connect using SSH. 
+2. Your local project files will be synced to the VM using Mutagen
+3. Once your files are updated, Devbox will install your dependencies and start a `devbox shell` for your project
+
+<!-- Diagram goes here -->
+
+If you are using Devbox for the first time, this process may take over 1 minute to complete, depending on the size and number of your project's dependencies. Subsequent sessions will reuse your VM, and should boot up and start in a few seconds
+
+#### Example: Initialize a Python Project in Cloud Shell
+
+Let's create a simple project that uses Python 3.10 with Poetry to manage our packages. We'll start by running `devbox init` in our project directory, and then adding the packages:
+
+```bash
+devbox init 
+```
+```bash
+devbox add python310 poetry
+```
+
+This should create a devbox.json in your directory that looks like the following: 
+
+```json
+{
+  "packages": [
+    "poetry",
+    "python310"
+  ],
+  "shell": {
+    "init_hook": null
+  },
+  "nixpkgs": {
+    "commit": "52e3e80afff4b16ccb7c52e9f0f5220552f03d04"
+  }
+}
+```
+Now you can start your Cloud Shell by running `devbox cloud shell`
+
+```md
+Devbox Cloud
+Remote development environments powered by Nix
+
+✓ Created a virtual machine in Sunnyvale, California (US)
+✓ File syncing started
+✓ Connecting to virtual machine
+
+
+Installing nix packages. This may take a while... done.
+Starting a devbox shell...
+...
+
+(devbox) ~/src/devbox-cloud-test 💫 watching for changes
+❯
+```
+
+You are now connected to your remote shell
+
+
+### Step 3: Sync your Local Changes to Devbox Cloud
+
+When you start your cloud session, your files are kept locally, and synchronized with your Devbox Cloud VM when changes are detected. This means you can use your favorite tools and editors to develop your project, while running in an isolated cloud environment. 
+
+#### Example: Add a Simple Flask App
+
+Let's add a simple Flask "Hello World" to our project to test the syncing.  
+
+1. On your local machine, create a pyproject.toml file with the following: 
+
+  ```toml
+  [tool.poetry]
+  name = "devbox-cloud-test"
+  version = "0.1.0"
+  description = ""
+  authors = ["Your Name <you@example.com>"]
+  packages = [{include = "devbox_cloud_test"}]
+
+  [tool.poetry.dependencies]
+  python = "^3.10"
+  Flask = "^2.2.2"
+
+
+  [build-system]
+  requires = ["poetry-core"]
+  build-backend = "poetry.core.masonry.api"
+  ```
+
+1. Create a file locally called `hello.py`, with the following contents:
+
+  ```python
+    from flask import Flask
+
+    app = Flask(__name__)
+
+    @app.route('/')
+    def index():
+        return '<h1>Hello from Devbox Cloud!</h1>'
+  ```
+
+1. These files will be automatically synced to your Devbox Cloud Shell, meaning you can install and run the Flask server remotely: 
+
+```bash
+poetry install
+poetry run flask --app hello run
+```
+
+This should start your Flask app with the development server:
+
+```bash
+ * Serving Flask app 'hello'
+ * Debug mode: off
+WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
+ * Running on http://127.0.0.1:5000
+Press CTRL+C to quit
+```
+
+### Step 4: Test your Services with Port-forwarding
+
+Once your service is running, you may want to test it with your browser or local tools, or you may want to expose services running on your remote shell to your local machine. 
+
+ You can do this using `devbox cloud forward :<remote_port>`, which will forward ports from your cloud instance to your local machine. If you provide just the remote port, Devbox will forward it to a randomly assigned local port.
+
+You can view the full list of port-forwards on your machine using `devbox cloud forward ls`. You can also terminate port=forwarding with `devbox cloud forward termiante`. 
+
+#### Example: Port-forwarding our Flask App
+
+Our Flask app in the example above is listening on port 5000 of the remote machine. Using `devbox cloud forward`, we can access that service from our localhost:
+
+```bash
+devbox cloud forward 5000:5000
+
+Port forwarding 5000:5000
+To view in browser, visit http://localhost:5000
+```
+
+Now if we curl `localhost:5000`, we should see our message:
+
+```bash
+curl localhost:5000
+<h1>Hello from Devbox Cloud!</h1>
+```
+
+## Next Steps
+
+* Learn how to activate **[Devbox Cloud Shell in your Browser](browser_getting_started.md)**
+* Try out one of our **[Examples](../devbox_examples/index.md)** in Devbox Cloud Shell
+* Learn more about the **[Devbox Cloud Shell Open Beta](index.md)**
+* Join the **[Discord Community](https://discord.gg/jetpack-io)**
+* File an Issue or Contribute on our **[Github Repo](https://github.com/jetpack-io/devbox)**