--- title: "The Omaterm Manual" author: "DHH" url: "https://learn.omacom.io/4/the-omaterm-manual" --- # Welcome Omaterm is a headless Arch setup for quickly getting servers, agent environments, and dev boxes setup with all the basic developing tooling you'd want along with services like GitHub, Tailscale, and SSH. It's done in the same omakase style as [Omarchy](https://omarchy.org), and is designed to be as familiar as possible for someone already running Omarchy. ## Installation 1. Download [Arch ISO](https://archlinux.org/download/) 2. Boot from ISO and run `archinstall`. 3. Reboot then run: `curl -fsSL https://omaterm.org/install | bash` Now you'll have a box ready for work! ## Services During the setup, you'll be asked whether you'd like to authenticate with GitHub and Tailscale. Doing so means the box will actually be useful for working on code, pushing it to production, and accessing the machine from anywhere in the world on your private network. ## AI Assistance Much of that work may well be happening with AI assistance. By default, Omaterm installs `opencode` and `claude`. They're accessible on `c` and `cx` respectively. # Navigation Tmux is launched automatically after setup when you connect (or you can launch it with the `t` alias after initial install). This is how you get the most out of multitasking on a remote Omaterm box, as you can't use client-side terminal features like Ghostty's splits, tabs, or new windows. All the navigation you'll do in tmux starts with the prefix key, which is set to the standard `Ctrl + B`. You can create new windows (which work like tabs) on `Prefix C`, new sessions (which work like new windows) on `Prefix Shift+C`. ... # Tools ## Neovim Neovim is configured with LazyVim and uses an terminal-derived color scheme, so your client terminal's look will the reflected on the Omaterm box, even when it changes live. You can start neovim with the `n` alias. (If you're connected to the box via TTY, like through Proxmox, you also have access to plain vim, which can be started with the `v` alias.) ## Mise Mise lets you install multiple versions of the same development environments. By default, you'll have access to Ruby and Node when the box is booted. But you can just run, say, `mise use -g go`, and you'll have access to the latest go. ## Docker Docker is setup to be sudoless and comes with both buildx and compose. There's a `d` alias to start it, so `d ps` will show you all the containers you currently have running. You can also run LazyDocker using the `lzd` alias. This gives you a full control-panel TUI for your Docker setup. # Services ## GitHub GitHub integration is offered during installation, so you'll have access to the `gh` command to checkout private repositories for doing real work. And git itself is configured with name/email identification during signup, so you can make commits right away. ## Tailscale [Tailscale](https://tailscale.com/) is an excellent way to access your Omaterm box over the internet without exposing it directly to the internet. Their free offering for personal use is very generous. You'll be offered to connect your box to your Tailnet during initial setup. ## SSH Omaterm starts an SSH server on your box by default, but it'll just use the regular password authentication until you run `omaterm-ssh-key`, which will accept your public key as a paste, then the box is locked down to only accept SSH keys (and not regular passwords). # Shell Omaterm runs on bash, but comes with a host of helpful tools to make the most of it. ## fzf [fzf](https://junegunn.github.io/fzf/) gives you fuzzy finding of files via the `ff` alias. Go to any directory, type `ff`, and you'll be able to fuzzy find your way to any file in that tree, while seeing a preview of the files you're narrowing down on the right-hand side. You can use `Ctrl + R` to use fzf to fuzzy find through your command history. This tool is also used by Neovim when you type `Space Space`. ## Zoxide [Zoxide](https://github.com/ajeetdsouza/zoxide) is a replacement for cd. It remembers the directories you've been in, so you can more easily jump to them next time. Say you do `cd ~/Work/basecamp` once. Next time, you can just do `cd basecamp` (or even just `cd base`), and Zoxide will take you directly there. ## eza [eza](https://eza.rocks/) is a replacement for ls. It gives you directory listings with more information, color, and icons. By default, eza has been aliased as ls. You can also use `lt` to get a listing of two-deep levels of nesting. `lsa` gives you a listing including hidden files. And `lta` a nested listing with hidden files. ## btop [btop](https://github.com/aristocratos/btop) lets you see system load in terms of processes, network, and CPU in a single TUI. It's configured with TTY coloring, so your client live themeing will match correctly. ## tldr [tldr](https://tldr.sh/) provides the short'n'sweet version of what `man` normally gives you. Great way to checkout the essentials, like `tldr fzf` or `tldr eza` to learn about these shell tools. # AI ### OpenCode [OpenCode](https://opencode.ai/) is an AI agent harness, like Claude Code or Gemini CLI, that works with all the commercial and open-weight models. Best way to use it is via the `c` alias, which you invoke once you're inside the directory you want to work on with AI. ### Claude Code Claude Code is installed via the AUR and gives you native access to the Anthropic Claude models. It's bound in run-dangerously mode to the `cx` alias. ### Other harnesses You can install any of the other major AI CLIs using yay, like: - yay -S gemini-cli - yay -S openai-codex - yay -S github-copilot-cli # Hotkeys ## Tmux Start Tmux with `t`. Enter command mode with `Ctrl + B` (called the prefix). | Hotkey | Function | | ------------------------------- | ------------------------------------- | | `Ctrl + B` | Prefix key (required before commands) | | `Prefix D` | Detach from session | | `Prefix :` | Open command prompt | | `Prefix ?` | List all key bindings | | `Alt + R` | Reload tmux config | ### Windows | Hotkey | Function | | ------------------------------- | ------------------------------------- | | `Prefix C` | New window (same directory) | | `Prefix R` | Rename window | | `Prefix &` | Kill window | | `Prefix N` | Next window | | `Prefix P` | Previous window | | `Prefix 0-9` | Go to window by number | | `Prefix W` | Choose window from list | ### Panes | Hotkey | Function | | ------------------------------- | ------------------------------------- | | `Prefix [pipe]` | Split horizontally (same directory) | | `Prefix -` | Split vertically (same directory) | | `Prefix Arrow keys` | Navigate between panes | | `Prefix Z` | Toggle pane zoom (fullscreen) | | `Prefix X` | Kill pane | | `Prefix Q` | Show pane numbers | | `Prefix O` | Cycle through panes | | `Prefix Space` | Cycle pane layouts | | `Prefix Shift + Left` | Resize pane left (by 10) | | `Prefix Shift + Right` | Resize pane right (by 10) | | `Prefix Shift + Up` | Resize pane up (by 10) | | `Prefix Shift + Down` | Resize pane down (by 10) | ### Sessions | Hotkey | Function | | ------------------------------- | ------------------------------------- | | `Prefix Shift + C` | New session | | `Prefix Shift + X` | Kill session | | `Prefix Shift + R` | Rename session | | `Prefix S` | Choose session from list | | `Prefix (` | Previous session | | `Prefix )` | Next session | ### Scrollback copy mode | Hotkey | Function | | ------------------------------- | ------------------------------------- | | `Prefix [` | Enter copy mode | | `V` (in copy mode) | Begin selection | | `Y` (in copy mode) | Copy selection and exit | | `Prefix ]` | Paste from buffer | ## Neovim (w/ lazyvim) ### Navigation | Hotkey | Function | | ------------------------ | ------------------------------- | | `Space` | Show command options | | `Space Space` | Open file via fuzzy search | | `Space E` | Toggle sidebar | | `Space G G` | Show git controls | | `Space S G` | Search file content | | `Ctrl + W W` | Jump between sidebar and editor | | `Ctrl + Left/right arrow` | Change size of sidebar | | `Shift + H` | Go to left file tab | | `Shift + L` | Go to right file tab | | `Space B D` | Close file tab | ### While in sidebar | Hotkey | Function | | ------------------------ | ------------------------------- | | `A` | Add new file in parent dir | | `Shift + A` | Add new subdir in parent dir | | `D` | Delete highlighted file/dir | | `M` | Move highlighted file/dir | | `R` | Rename highlighted file/dir | | `?` | Show help for all commands | [See all the Neovim hotkeys configured by LazyVim](https://www.lazyvim.org/keymaps).