### Example: nginx Authorization

Source: https://exe.dev/docs/login-with-exe

An example Nginx configuration demonstrating how to allow access only to specified email addresses using the `X-ExeDev-Email` header.

```APIDOC
## Example: nginx Authorization

The following `nginx` configuration allows only specified email addresses to access a protected location:

```nginx
server {
    listen 80;
    server_name _;

    location / {
        # Check if X-ExeDev-Email header matches allowed addresses
        set $allowed "false";
        if ($http_x_exedev_email = "alice@example.com") {
            set $allowed "true";
        }
        if ($http_x_exedev_email = "bob@example.com") {
            set $allowed "true";
        }

        # Return 403 if not allowed
        if ($allowed = "false") {
            return 403 "Access denied. Please log in with an authorized account.";
        }

        # Serve content for authorized users
        root /var/www/html;
        index index.html;
        try_files $uri $uri/ =404;
    }
}
```
```

--------------------------------

### Manage GitHub Actions Runner systemd Service

Source: https://exe.dev/docs/use-case-gh-action-runner

These commands manage the systemd service for the GitHub Actions runner. 'sudo cp' copies the service file to the systemd directory, 'sudo systemctl daemon-reload' reloads systemd configurations, and 'sudo systemctl enable --now' enables the service to start on boot and starts it immediately. 'sudo systemctl status' verifies the service is running.

```bash
sudo cp /home/exedev/actions-runner/gh-actions-runner.service /etc/systemd/system/
```

```bash
sudo systemctl daemon-reload
```

```bash
sudo systemctl enable --now gh-actions-runner.service
```

```bash
sudo systemctl status gh-actions-runner.service
```

--------------------------------

### Development: Mocking Authentication Headers with mitmdump

Source: https://exe.dev/docs/login-with-exe

This example demonstrates how to use `mitmdump` to mock authentication headers for development purposes. It sets up a reverse proxy to your local server and injects `X-Exedev-Email` and `X-Exedev-Userid` headers into requests.

```bash
mitmdump \
  --mode reverse:http://localhost:8000 \
  --listen-port 3000 \
  --set modify_headers='/~q/X-Exedev-Email/user@example.com' \
  --set modify_headers='/~q/X-Exedev-Userid/usr1234'
```

--------------------------------

### Run Alpine Docker Container and Echo 'hello'

Source: https://exe.dev/docs/faq/docker

This snippet demonstrates how to launch a Docker container using the 'alpine:latest' image, execute the 'echo hello' command within it, and automatically remove the container upon completion. It requires Docker to be installed and configured.

```bash
docker run --rm alpine:latest echo hello
```

--------------------------------

### Manage GitHub Actions Runner systemd service (Bash)

Source: https://exe.dev/docs/all

These commands manage the systemd service for the GitHub Actions runner. They reload the systemd daemon, enable and start the service, and display its status. This ensures the runner is active and configured correctly.

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now gh-actions-runner.service
sudo systemctl status gh-actions-runner.service
```

--------------------------------

### Create systemd Service File for GitHub Actions Runner

Source: https://exe.dev/docs/use-case-gh-action-runner

This snippet creates a systemd service file named 'gh-actions-runner.service'. It defines the service to run the GitHub Actions runner, specifying user, working directory, and restart behavior. This ensures the runner automatically starts and restarts.

```bash
cat > /home/exedev/actions-runner/gh-actions-runner.service << 'EOF'
[Unit]
Description=GitHub Actions Runner
After=network.target

[Service]
Type=simple
User=exedev
WorkingDirectory=/home/exedev/actions-runner
ExecStart=/home/exedev/actions-runner/run.sh
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF
```

--------------------------------

### Show Help Information (CLI)

Source: https://exe.dev/docs/all

Displays help information for the CLI. This command is fundamental for understanding available options and usage patterns.

```bash
help
```

--------------------------------

### Create New VM (CLI)

Source: https://exe.dev/docs/all

Creates a new virtual machine with various configuration options. Users can specify custom images, environment variables, names, and more. Email notifications can be disabled.

```bash
new
```

```bash
new --name=b --image=ubuntu:22.04
```

```bash
new --env FOO=bar --env BAZ=qux
```

```bash
new --json
```

```bash
new --no-email
```

```bash
new --prompt
```

--------------------------------

### API: List VMs with JSON Output

Source: https://exe.dev/docs/all

Demonstrates using the exe.dev API via SSH to list VMs and parse the JSON output using `jq`. This allows for programmatic access to VM information.

```bash
$ssh exe.dev ls --json | jq '.vms[0]'
```

--------------------------------

### Browse Documentation (CLI)

Source: https://exe.dev/docs/all

Allows users to browse documentation directly from the command line. It accepts a 'slug' argument to navigate to specific documentation sections.

```bash
doc [slug]
```

--------------------------------

### Add SSH Key (CLI)

Source: https://exe.dev/docs/cli-ssh-key

Adds a new SSH key to the user's account. Requires the public key as an argument. Examples show adding a key from a local file or directly from the command line.

```bash
ssh-key add 'ssh-ed25519 AAAA... my-laptop'
cat ~/.ssh/id_exe.pub | ssh exe.dev ssh-key add
```

--------------------------------

### Custom Domains

Source: https://exe.dev/docs/all

Instructions on how to point your own domain at an exe.dev VM, including DNS record configurations for subdomains and apex domains.

```APIDOC
## Custom Domains

### Description
Enables users to use their own domain names with their exe.dev VMs. TLS certificates are issued automatically.

### Configuration

1.  **Subdomains (CNAME)**
    *   For non-apex domains (e.g., `app.example.com`), create a CNAME record:
        ```
        app.example.com  CNAME  vmname.exe.xyz
        ```

2.  **Apex Domains (ALIAS + CNAME)**
    *   For apex domains (e.g., `example.com`), two DNS records are required:
        *   **ALIAS** (or ANAME) record on the apex pointing to `exe.xyz`:
            ```
            example.com  ALIAS  exe.xyz
            ```
        *   **CNAME** record on `www` pointing to your VM:
            ```
            www.example.com  CNAME  vmname.exe.xyz
            ```
```

--------------------------------

### List VMs (CLI)

Source: https://exe.dev/docs/all

Lists existing virtual machines. Supports filtering by name or pattern and provides options for detailed output or JSON formatting.

```bash
ls [-l] [name|pattern]
```

```bash
ls --json
```

```bash
ls -l
```

--------------------------------

### Copy VM (CLI)

Source: https://exe.dev/docs/all

Creates a copy of an existing virtual machine. This command is useful for creating backups or setting up similar environments.

```bash
cp
```

--------------------------------

### File Transfer using scp

Source: https://exe.dev/docs/all

This snippet illustrates how to copy files to or from an exe.dev VM using the scp command. It shows the basic syntax for transferring a local file to the VM.

```bash
scp <local-file> <vmname>.exe.xyz:.
```

--------------------------------

### Configure Subdomain with CNAME

Source: https://exe.dev/docs/all

Sets up a CNAME record for non-apex domains to point to your VM on exe.dev. This is a common DNS configuration for subdomains.

```dns
app.example.com  CNAME  vmname.exe.xyz
```

--------------------------------

### Create VM Share Link

Source: https://exe.dev/docs/all

Generates a shareable link for a VM. Users can access the VM after registering and logging in. Access can be revoked for users, but not the link itself.

```bash
share add-link <vm>
```

--------------------------------

### Configure Apex Domain with ALIAS and CNAME

Source: https://exe.dev/docs/all

Configures apex domains by using an ALIAS record pointing to exe.xyz and a CNAME record for 'www' pointing to your VM. This is necessary for root domains.

```dns
example.com  ALIAS  exe.xyz
www.example.com  CNAME  vmname.exe.xyz
```

--------------------------------

### Create Marimo Instance on exe.dev (Shell)

Source: https://exe.dev/docs/use-case-marimo

This command initiates the creation of a new Marimo notebook instance on the exe.dev platform. It specifies the Docker image to use for the Marimo environment. The output provides URLs for accessing the notebook via HTTPS and SSH.

```shell
ssh exe.dev new --image=ghcr.io/marimo-team/marimo:latest-sql
```

--------------------------------

### Login with exe Authentication

Source: https://exe.dev/docs/all

Leverage exe.dev's authentication system in your applications to identify users accessing services through the HTTP proxy. Includes details on authentication headers and special URLs.

```APIDOC
## Login with exe Authentication

### Description
Utilizes exe.dev's authentication system to identify users accessing your services via the HTTP proxy, simplifying authorization management.

### Authentication Headers
When a user is authenticated, the following headers are added to requests to your VM:

*   `X-ExeDev-UserID`: A stable, unique identifier for the user.
*   `X-ExeDev-Email`: The user's email address.

*Note*: These headers are only present for authenticated users. Unauthenticated requests to public proxies will not have these headers.

### Special Authentication URLs

*   **Login**: `https://vmname.exe.xyz/__exe.dev/login?redirect={path}`
    *   Redirects the user to the login page and then back to the specified path upon successful login.

*   **Logout**: `POST https://vmname.exe.xyz/__exe.dev/logout`
    *   Logs the user out by removing the cookie for your domain.

### Development Example (mitmdump)
For development, an HTTP proxy can add these headers:

```bash
mitmdump \
  --mode reverse:http://localhost:8000 \
  --listen-port 3000 \
  --set modify_headers='/~q/X-Exedev-Email/user@example.com' \
  --set modify_headers='/~q/X-Exedev-Userid/usr1234'
```

### Example: nginx Authorization
An `nginx` configuration to allow access based on `X-ExeDev-Email` header:

```nginx
server {
    listen 80;
    server_name _;

    location / {
        set $allowed "false";
        if ($http_x_exedev_email = "alice@example.com") {
            set $allowed "true";
        }
        if ($http_x_exedev_email = "bob@example.com") {
            set $allowed "true";
        }

        if ($allowed = "false") {
            return 403 "Access denied. Please log in with an authorized account.";
        }

        root /var/www/html;
        index index.html;
        try_files $uri $uri/ =404;
    }
}
```
```

--------------------------------

### Specify SSH Key via Command Line

Source: https://exe.dev/docs/faq/ssh-key

This command demonstrates how to explicitly specify the private key file to use when connecting to the 'exe.dev' host. It's useful for one-off connections or when you don't want to modify your SSH configuration file.

```bash
ssh -i ~/.ssh/id_ed25519_exe exe.dev
```

--------------------------------

### Create New Resource via SSH

Source: https://exe.dev/docs/api

Executes the 'new' command on exe.dev via SSH, typically used for creating new resources. The command is designed to output results in JSON format, facilitating integration with automated workflows.

```bash
ssh exe.dev new --json
```

--------------------------------

### Restart VM (CLI)

Source: https://exe.dev/docs/all

Restarts a specified virtual machine. The command accepts the VM name and can output results in JSON format.

```bash
restart <vmname>
```

```bash
restart --json
```

--------------------------------

### exe.dev Authentication Login URL

Source: https://exe.dev/docs/all

Provides the URL for users to log in via exe.dev's authentication system. After successful login, users are redirected to the specified path.

```url
https://vmname.exe.xyz/__exe.dev/login?redirect={path}
```

--------------------------------

### Share VM via Email

Source: https://exe.dev/docs/all

Allows sharing a VM with specific email addresses. Recipients receive an email and can access the VM via a unique URL after logging in.

```bash
share add <vm> <email>
```

--------------------------------

### Rename VM (CLI)

Source: https://exe.dev/docs/all

Renames an existing virtual machine by providing its current and new names. JSON output is available.

```bash
rename <oldname> <newname>
```

```bash
rename --json
```

--------------------------------

### Show VM Shares

Source: https://exe.dev/docs/cli-share

Displays the current sharing status for a specified virtual machine. Supports JSON output for programmatic access and QR code generation for shareable links.

```bash
share show <vm>
share show <vm> --json
share show <vm> --qr
```

--------------------------------

### Development: Using an HTTP Proxy

Source: https://exe.dev/docs/login-with-exe

If you're using an agent to develop on your exe.dev VM, you can use an HTTP proxy to add authentication headers for testing purposes.

```APIDOC
## Development: Using an HTTP Proxy

If you're using an agent to develop on your exe.dev VM itself, your server might be listening, for example, on http://localhost:8000/, and nothing is providing these headers. Use an http proxy to add the headers for testing. For example:

```
mitmdump \
  --mode reverse:http://localhost:8000 \
  --listen-port 3000 \
  --set modify_headers='/~q/X-Exedev-Email/user@example.com' \
  --set modify_headers='/~q/X-Exedev-Userid/usr1234'
```
```

--------------------------------

### API Access via SSH

Source: https://exe.dev/docs/all

Programmatic access to the exe.dev API is provided via SSH, allowing users to run commands like `ls` and `new` directly from scripts.

```APIDOC
## API Access via SSH

### Description
Provides programmatic access to the exe.dev platform through SSH, enabling automation and scripting.

### Usage
Run commands using `ssh exe.dev <command> --json`. The `--json` flag ensures machine-readable output.

### Example
Listing VMs and retrieving details for the first VM:

```bash
$ssh exe.dev ls --json | jq '.vms[0]'
{
  "image": "boldsoftware/exeuntu",
  "ssh_dest": "bloggy.exe.xyz",
  "status": "running",
  "vm_name": "bloggy"
}
```
```

--------------------------------

### share add-link

Source: https://exe.dev/docs/cli-share

Creates a shareable link for a Virtual Machine.

```APIDOC
## POST /share/add-link

### Description
Generates a unique, shareable link for a VM, allowing access based on the link's permissions (public or private).

### Method
POST

### Endpoint
`/share/add-link <vm>`

### Parameters
#### Path Parameters
- **vm** (string) - Required - The identifier of the virtual machine.

#### Query Parameters
- **--json** (boolean) - Optional - Output in JSON format.
- **--qr** (boolean) - Optional - Display QR code for the shareable URL.

### Request Example
```
share add-link my-vm --qr
```

### Response
#### Success Response (200)
- **link** (string) - The generated shareable URL for the VM.

#### Response Example
```json
{
  "link": "https://example.com/share/link-token-12345"
}
```
```

--------------------------------

### share show

Source: https://exe.dev/docs/cli-share

Shows current shares for a specified Virtual Machine.

```APIDOC
## GET /share/show

### Description
Retrieves a list of current shares for a given VM.

### Method
GET

### Endpoint
`/share/show <vm>`

### Parameters
#### Path Parameters
- **vm** (string) - Required - The identifier of the virtual machine.

#### Query Parameters
- **--json** (boolean) - Optional - Output in JSON format.
- **--qr** (boolean) - Optional - Display QR code for the shareable URL.

### Request Example
```
share show my-vm --json
```

### Response
#### Success Response (200)
- **shares** (array) - A list of share details.
  - **user** (string) - The user the VM is shared with.
  - **url** (string) - The URL for accessing the shared VM.

#### Response Example
```json
{
  "shares": [
    {
      "user": "user@example.com",
      "url": "https://example.com/share/vm-id"
    }
  ]
}
```
```

--------------------------------

### Authenticate gh CLI with a Personal Access Token

Source: https://exe.dev/docs/faq/github-token

This snippet demonstrates how to authenticate the GitHub CLI (`gh`) using a personal access token. It involves creating a file with the token, piping it to `gh auth login`, and then setting up Git credentials. This method is useful for scripting or automated environments.

```bash
$ cat > token
(paste the token and hit ctrl-d)
$ gh auth login --with-token < token
$ gh auth setup-git
$ git clone https://github.com/USER/REPO
```