OrbStack Docs

https://docs.orbstack.dev
Admin
OrbStack is a fast, light, and simple way to run containers and Linux machines, offering a...
Tokens:27,985
Snippets:529
Trust Score:9.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Cloud-init Configuration Example (cloud-config)

Source: https://docs.orbstack.dev/machines/cloud-init

This example demonstrates a Cloud-init configuration in YAML format. It includes creating groups, installing packages, and writing a file to the machine.

```yaml
#cloud-config

# create group 'admingroup' with member 'root', and empty group 'cloud-users'
groups:
  - admingroup: [root]
  - cloud-users

# install package 'git'
packages:
  - git

# write file '/etc/cltest' with content 'it works!'
write_files:
- content: |
    it works!
  path: /etc/cltest

```

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

### Start Nginx Service in Ubuntu

Source: https://docs.orbstack.dev/machines

Installs and starts the Nginx web server using systemd on an Ubuntu Linux machine within OrbStack. Ensure you have root privileges or use sudo.

```bash
apt install nginx
systemctl start nginx
```

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

### Create and Use Podman in OrbStack Linux Machine

Source: https://docs.orbstack.dev/faq

This example demonstrates how to create a Linux machine within OrbStack, install Podman, and run a container using Podman. This is a workaround for direct Podman support.

```bash
orb create ubuntu
orb sudo apt install podman
orb sudo podman run -it --rm -p 80:80 docker.io/docker/getting-started
```

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

### Create Machine and Run Setup Script

Source: https://docs.orbstack.dev/machines

Automates the creation of a new Ubuntu machine and immediately executes a setup script named 'setup.sh' within it using the OrbStack CLI.

```bash
orb create ubuntu new-ubuntu && orb -m new-ubuntu ./setup.sh
```

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

### Create Fedora Machine with Specific Version

Source: https://docs.orbstack.dev/machines/distros

Example of creating a new machine with Fedora version 43.

```bash
orb create fedora:43
```

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

### Create openSUSE Machine with Tumbleweed Version

Source: https://docs.orbstack.dev/machines/distros

Example of creating a new machine with the Tumbleweed version of openSUSE.

```bash
orb create opensuse:tumbleweed
```

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

### Install OrbStack via Homebrew

Source: https://docs.orbstack.dev/headless

Use Homebrew to install the OrbStack cask.

```bash
brew install orbstack
```

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

### Get OrbStack CLI Help

Source: https://docs.orbstack.dev/machines/commands

Run `orb help` to display general help information for the OrbStack CLI.

```bash
orb help
```

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

### Install Traefik Ingress Controller with Helm

Source: https://docs.orbstack.dev/kubernetes

Install the Traefik Ingress controller using Helm. Ensure Helm is installed first.

```bash
# Install Helm first: https://helm.sh/docs/intro/install/
helm repo add traefik https://traefik.github.io/charts
helm repo update
helm install traefik traefik/traefik
```

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

### Create Debian Machine with Specific Version

Source: https://docs.orbstack.dev/machines/distros

Example of creating a new machine with Debian version 12 (Bookworm).

```bash
orb create debian:bookworm
```

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

### Automatic Package Installation

Source: https://docs.orbstack.dev/features/debug

OrbStack prompts for package installation when an unrecognized command is executed.

```bash
❯ emacs
emacs: command not found
  * install package 'emacs'? [y/N]
```

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

### Install Istio with Custom CNI Flags

Source: https://docs.orbstack.dev/kubernetes

Install Istio using `istioctl` or Helm, specifying custom CNI directories for integration with OrbStack's Kubernetes environment.

```bash
--set values.cni.cniBinDir=/var/lib/rancher/k3s/data/current/bin/ --set values.cni.cniConfDir=/var/lib/rancher/k3s/agent/etc/net.d
```

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

### Create Alpine Linux Machine with Edge Version

Source: https://docs.orbstack.dev/machines/distros

Example of creating a new machine with the edge version of Alpine Linux.

```bash
orb create alpine:edge
```

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

### Create Devuan Machine with Specific Version

Source: https://docs.orbstack.dev/machines/distros

Example of creating a new machine with Devuan version Daedalus.

```bash
orb create devuan:daedalus
```

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

### Run a Local Web Server in Linux

Source: https://docs.orbstack.dev/machines/network

Start a simple HTTP server in a Linux machine to serve files from the current directory. Accessible from macOS on localhost.

```bash
python3 -m http.server 8000
```

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

### Start Default Linux Shell

Source: https://docs.orbstack.dev/machines/commands

Run `orb` with no arguments to open a shell in the default Linux machine.

```bash
orb
```

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

### Install Helm Repositories and Deploy Applications

Source: https://docs.orbstack.dev/benchmarks

Adds Traefik and Grafana Helm repositories and installs them into a fresh Kubernetes cluster. This is part of the battery benchmark for Kubernetes.

```bash
helm repo add traefik https://traefik.github.io/charts
helm repo add grafana https://grafana.github.io/helm-charts
helm repo update
helm install traefik traefik/traefik
helm install grafana grafana/grafana
```

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

### Create Alma Linux Machine with Specific Version

Source: https://docs.orbstack.dev/machines/distros

Example of creating a new machine with Alma Linux version 8.

```bash
orb create alma:8
```

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

### Enable Multi-architecture Support on Ubuntu

Source: https://docs.orbstack.dev/machines

Enables multi-architecture support on Ubuntu by adding the amd64 architecture, configuring repositories for both arm64 and amd64, and installing the necessary 64-bit C library.

```bash
sudo dpkg --add-architecture amd64
# Fix repos
echo 'deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports lunar main restricted universe multiverse
deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports lunar-updates main restricted universe multiverse
deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports lunar-security main restricted universe multiverse
deb [arch=amd64] http://archive.ubuntu.com/ubuntu lunar main restricted universe multiverse
deb [arch=amd64] http://archive.ubuntu.com/ubuntu lunar-updates main restricted universe multiverse
deb [arch=amd64] http://archive.ubuntu.com/ubuntu lunar-security main restricted universe multiverse' | sudo tee /etc/apt/sources.list

# Install libraries
sudo apt update
sudo apt install libc6:amd64
```

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

### Install Ingress-NGINX

Source: https://docs.orbstack.dev/kubernetes

Apply the official Ingress-NGINX controller configuration to your Kubernetes cluster.

```bash
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.1/deploy/static/provider/cloud/deploy.yaml
```

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

### Start Specific Linux Shell

Source: https://docs.orbstack.dev/machines/commands

Specify a machine and user to open a shell in a particular Linux environment.

```bash
orb -m my-machine -u my-user
```

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

### Install Packages with dctl

Source: https://docs.orbstack.dev/features/debug

Install additional tools within the Debug Shell environment using the dctl package manager.

```bash
dctl install nvim
```

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

### Run Open edX Development Environment

Source: https://docs.orbstack.dev/benchmarks

Installs and provisions a heavy set of services for local Open edX development. Excludes image pull time to reduce network noise.

```bash
# Exclude image pull time to reduce network noise
make pull
time make dev.provision
```

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

### Debug x86 Programs with QEMU and GDB

Source: https://docs.orbstack.dev/machines

Installs QEMU user-mode static translation and runs an x86 executable with a debug server enabled. It then connects to this debug server using GDB in another terminal to debug the emulated process.

```bash
sudo apt install qemu-user-static
qemu-x86_64-static -g 1234 ./hello

# in another terminal
gdb ./hello
target remote :1234
continue
```

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

### Start Debug Shell via CLI

Source: https://docs.orbstack.dev/features/debug

Initiate a debug session for a specific container using its name or ID.

```bash
orb debug <container name or ID>
```

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

### Create Multi-Platform Buildx Builder

Source: https://docs.orbstack.dev/docker/images

Use `docker buildx create` to set up a builder for parallel multi-platform image builds. Ensure it's set as the default builder with `docker buildx install`.

```bash
# Create a parallel multi-platform builder
docker buildx create --name mybuilder --use
# Make "buildx" the default
docker buildx install
# Build for multiple platforms
docker build --platform linux/amd64,linux/arm64 .
```

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

### Test Sound Playback

Source: https://docs.orbstack.dev/features/sound

Use this command to test audio playback from your Linux machine. Ensure you have the `alsa-utils` package installed.

```bash
speaker-test -t wav -c 2
```

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

### Update OrbStack Manually

Source: https://docs.orbstack.dev/headless

Update the installation using Homebrew with the greedy flag.

```bash
brew upgrade --greedy orbstack
```

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

### Connect to Mac Servers from Linux

Source: https://docs.orbstack.dev/machines/network

Access servers running on your Mac from a Linux machine using the `host.orb.internal` hostname. Example shown for a MySQL server.

```bash
mysql -h host.orb.internal -u root
```

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

### Link Mac Commands for Linux Use

Source: https://docs.orbstack.dev/machines

Creates symbolic links for specified Mac commands (e.g., adb, fastboot) within the Linux environment, allowing them to be run as if installed on Linux.

```bash
# Link commands
mac link adb
mac link fastboot

# Then run them as usual
adb devices
fastboot devices
```

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

### Checkpoint and Restore Docker Containers

Source: https://docs.orbstack.dev/docker

Create a snapshot of a running container's state using `docker checkpoint create` and restore it later with `docker start --checkpoint`. This feature is enabled by default in OrbStack's experimental mode.

```bash
# Create a checkpoint of a running container
docker checkpoint create my-container chk1

# Restore the container from the checkpoint
docker start --checkpoint chk1 my-container
```

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

### Expose Deployment as NodePort Service and Access

Source: https://docs.orbstack.dev/kubernetes

Create a Kubernetes deployment, expose it as a NodePort service, and access it via localhost.

```bash
$ kubectl create deployment nginx --image nginx
$ kubectl expose deploy/nginx --type=NodePort --port=80
$ kubectl get svc
NAME       TYPE           CLUSTER-IP        EXTERNAL-IP    PORT(S)
nginx      NodePort       192.168.194.217   <none>         80:32042/TCP

$ curl -I localhost:32042
HTTP/1.1 200 OK
Server: nginx/1.25.2
```

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

### Create a Linux Machine

Source: https://docs.orbstack.dev/headless

Provision a new Linux machine using the orb command.

```bash
orb create ubuntu ci-runner
```

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

### Create New Ubuntu Machine

Source: https://docs.orbstack.dev/machines/commands

Use the `orb create` subcommand to provision a new Ubuntu machine with a specified name.

```bash
orb create ubuntu my-machine
```

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

### Debug Remote Container

Source: https://docs.orbstack.dev/features/debug

Use a previously defined Docker context to start a debug session on a remote host.

```bash
orb debug -c servy <container name or ID>
```

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

### Set Resource Limits for a New Machine

Source: https://docs.orbstack.dev/machines

Creates a new Ubuntu machine named 'my-machine' with specified memory, CPU, and disk limits using the OrbStack CLI.

```bash
orb create --memory 4G --cpus 2 --disk 64G ubuntu my-machine
```

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

### View Machine Boot Logs

Source: https://docs.orbstack.dev/machines

Retrieves and displays the boot logs and console output for a specified OrbStack machine.

```bash
orb logs ubuntu
```

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

### Forward Port 80 for Nginx

Source: https://docs.orbstack.dev/docker/network

Use the `-p` flag to forward a container port to the host. This example forwards port 80 from an Nginx container to the host.

```bash
docker run --rm -p 80:80 nginx
```

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

### Run and Build x86 and ARM64 Containers

Source: https://docs.orbstack.dev/docker

Use the --platform flag to specify the architecture when running or building Docker images. This is particularly useful on Apple Silicon Macs for emulating x86_64 images.

```bash
# Run an x86 container
docker run -it --rm --platform linux/amd64 alpine
# Run an arm64 container
docker run -it --rm --platform linux/arm64 alpine

# Build for x86
docker build --platform linux/amd64 .
# Build for arm64
docker build --platform linux/arm64 .
```

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

### Create an Intel (x86) Linux Machine

Source: https://docs.orbstack.dev/machines

Creates a new Ubuntu Linux machine named 'new-ubuntu' specifically for the Intel (x86_64/amd64) architecture on Apple Silicon using the '--arch amd64' flag.

```bash
orb create --arch amd64 ubuntu new-ubuntu
```

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

### Get Machine IP Address

Source: https://docs.orbstack.dev/machines/network

Display network interface details for a Linux machine to find its IP address. The IPv4 and IPv6 addresses can be used for inter-machine connections.

```bash
ip addr
```

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

### Migrate Docker Data via Command Line

Source: https://docs.orbstack.dev/install

Use this command to migrate your Docker Desktop data, including containers, volumes, and images, to OrbStack. This is an optional step performed after installation.

```bash
orb docker migrate
```

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

### Create Machine with Cloud-init User Data

Source: https://docs.orbstack.dev/machines/cloud-init

Use the `-c` or `--user-data` flag with the `orb create` command to specify a Cloud-init user data file for machine provisioning.

```bash
orb create ubuntu my-machine -c user-data.yml
```

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

### Create Machine with Default Password

Source: https://docs.orbstack.dev/machines

Creates a new Ubuntu machine and sets a default password for the user during creation.

```bash
orb create --set-password ubuntu new-ubuntu
```

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

### Connect to Linux Machine from Mac

Source: https://docs.orbstack.dev/machines/network

Access a server running on a Linux machine from your Mac using the machine's IP address. Example uses `curl` to connect to a web server.

```bash
curl 198.19.249.204
```

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

### Create a New Ubuntu Linux Machine

Source: https://docs.orbstack.dev/machines

Creates a new Ubuntu Linux machine named 'new-ubuntu' using the OrbStack CLI. Supports specifying distribution versions and architectures.

```bash
orb create ubuntu new-ubuntu
# An older version
orb create ubuntu:jammy new-ubuntu
# Intel machine on Apple Silicon
orb create --arch amd64 ubuntu new-ubuntu
```

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

### Log in to the default machine

Source: https://docs.orbstack.dev/machines/ssh

Connect to the default Linux machine using the SSH client.

```bash
ssh orb
```

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

### Attach a Volume to a Container

Source: https://docs.orbstack.dev/docker/file-sharing

Mount a pre-existing volume into a container at a specified path. Use the volume name as the source.

```bash
docker run -v foo:/data alpine ls /data
```

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

### Test Microphone Recording and Playback

Source: https://docs.orbstack.dev/features/sound

Record audio from the microphone and play it back. Press Ctrl-C to stop recording. OrbStack might request microphone access on the first use.

```bash
arecord out.wav    # Ctrl-C to stop
aplay out.wav
```

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

### Export and Import OrbStack Machines

Source: https://docs.orbstack.dev/machines

Exports the 'ubuntu' machine to a compressed archive file 'ubuntu.tar.zst' for backup or transfer. Imports the archive into a new machine named 'new-name'.

```bash
orb export ubuntu ubuntu.tar.zst
# To import a machine from a file:
orb import -n new-name ubuntu.tar.zst
```

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

### Create Ubuntu Machine with Specific Version

Source: https://docs.orbstack.dev/machines/distros

Use the 'orb create' command to create a new machine with a specific distribution version, such as Ubuntu 24.04 LTS (Noble).

```bash
orb create ubuntu:noble
```

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

### Run Command in Linux

Source: https://docs.orbstack.dev/machines/commands

Prefix a command with `orb` to execute it within the default Linux machine.

```bash
orb uname -a
```

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

### Run Command on macOS

Source: https://docs.orbstack.dev/machines/commands

Prefix a command with `mac` to execute it on your macOS system.

```bash
mac uname -a
```

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

### Switch Docker Context to Docker Desktop

Source: https://docs.orbstack.dev/install

Switch your Docker CLI context back to Docker Desktop. This is useful when running OrbStack and Docker Desktop side-by-side or when reverting.

```bash
# Switch to Docker Desktop
docker context use desktop-linux
```

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

### Run Nginx with Host Networking

Source: https://docs.orbstack.dev/docker/network

Utilize host networking with `--net=host` to avoid port forwarding. Servers in the container are accessible on `localhost`.

```bash
docker run --rm --net=host nginx
```

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

### Compile and Run macOS Executables from Linux

Source: https://docs.orbstack.dev/machines

Compiles a C program for macOS using the 'mac' prefix and then runs the resulting executable directly within the Linux environment. This leverages binfmt_misc for running Mach-O binaries.

```bash
# Compile a C program for macOS
mac gcc -o foo foo.c
# Run it ("mac" prefix not needed)
./foo
```

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

### Connect to Mac Server from Container

Source: https://docs.orbstack.dev/docker/network

Use the `host.docker.internal` domain within a container to connect to a server running on the macOS host.

```bash
docker run --rm mysql mysql -h host.docker.internal -u root
```

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

### List Serial and UART Devices

Source: https://docs.orbstack.dev/features/usb

View all serial and UART ports currently forwarded to Linux.

```bash
orb serial list
```

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

### Configure Remote Docker Context

Source: https://docs.orbstack.dev/features/debug

Create a Docker context to connect to a remote host via SSH and verify connectivity.

```bash
docker context create servy --docker host=ssh://user@192.168.1.100
# list running containers on the remote host
docker -c servy ps
```

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

### Run Mac Commands from Linux

Source: https://docs.orbstack.dev/machines

Aliases common Mac commands for direct use within Linux machines. Use the 'mac' prefix for explicit execution of Mac commands.

```bash
# open foo.txt in the default Mac text editor
open foo.txt
# copy `ps` output to Mac clipboard
ps | pbcopy
```

```bash
mac uname -a
```

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

### Manage USB Passthrough via CLI

Source: https://docs.orbstack.dev/features/usb

Use these commands to list, inspect, attach, and detach USB devices from the terminal.

```bash
# List connected USB devices
orb usb list

# Show details for a device
orb usb info <id>

# Attach a device to Linux
orb usb attach <id>

# Detach a device
orb usb detach <id>
```
Tokens:
Raw