Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ona.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Dotfiles apply your personal configurations (shell settings, aliases, editor preferences, tools) to every Ona environment on startup. Your customizations layer on top of the team’s standardized Dev Container, so you get a consistent base with your own workflow.

​
Configure your dotfiles repository

Point Ona at a Git repository containing your dotfiles. Every new environment will clone it and run your install script automatically. Via CLI: 
ona user dotfiles set --repository https://github.com/<your-user>/dotfiles
Via Web UI: Navigate to Settings > Preferences and enter the repository URL. If you do not have a dotfiles repository yet, see GitHub’s dotfiles guide or awesome-dotfiles for examples.

​
How dotfiles are installed

When an environment starts, Ona:
  1. Clones your dotfiles repository to ~/dotfiles
  2. Runs the first matching script it finds:
    • install.sh or install
    • bootstrap.sh or bootstrap
    • setup.sh or setup
If none of these files exist, the repository is cloned but no script runs. You are limited to one dotfiles repository per user.

​
Update dotfiles in a running environment

Changes pushed to your dotfiles repository apply to new environments only. To update a running environment: 
cd ~/dotfiles && git pull && ./install.sh
Replace install.sh with whichever script your repository uses.

​
Iterate on your dotfiles

To test changes without creating new environments each time:
  1. Start an environment from your dotfiles repository
  2. Edit files and re-run your install script to validate
  3. Run ona environment devcontainer rebuild to reset the environment state if needed

​
Change the default shell

Add this to your install script to switch to zsh (or any other shell): 
sudo chsh "$(id -un)" --shell "/usr/bin/zsh"
This modifies /etc/passwd, which persists across terminal sessions within the same environment.

​
Best practices

  • Keep install scripts fast. Every second adds to environment startup time.
  • Run non-interactively. The install script runs without a TTY. Commands that prompt for input (e.g., read, interactive installers) will hang the environment.
  • Make scripts self-contained. Check for dependencies before installing them, since Dev Container images vary across projects:
FZF_VERSION="0.60.3"
if ! command -v fzf >/dev/null 2>&1; then
    curl -L "https://github.com/junegunn/fzf/releases/download/v${FZF_VERSION}/fzf-${FZF_VERSION}-linux_amd64.tar.gz" | tar xzf -
    sudo mv fzf /usr/local/bin
fi
echo "source <(fzf --zsh)" >> "$HOME/.zshrc"
  • Do not store secrets in dotfiles. Use Ona secrets instead.

​
Troubleshooting

Check the environment logs under “Creating Dev Container” for errors. A common cause:
fatal: repository 'https://github.com/user/dotfiles-does-not-exist/' not found
Verify the repository URL in Settings > Preferences points to an existing, accessible repository.
Clone errors appear in the environment logs, but install script failures may not. Reproduce the error manually:
cd ~/dotfiles
./install.sh
If the script works in some projects but not others, the failing project’s Dev Container image is likely missing a dependency your script needs. Make your script self-contained by checking for and installing missing dependencies (see the fzf example above).
The install script runs in a non-interactive shell without a TTY. Commands that expect terminal input will block indefinitely.To diagnose:
  1. Remove your dotfiles repository from Settings > Preferences
  2. Start a fresh environment
  3. Clone your dotfiles and run the install script manually to find the blocking command
  4. Fix the script, push, and re-add the repository URL