Shell Integration

Automatically start SkyBox containers when you cd into a project directory.

Overview

The SkyBox shell hook integrates with your shell to detect when you navigate into a SkyBox project directory. When enabled, it automatically starts the container in the background, so your development environment is ready by the time you need it.

Benefits:

• No manual skybox up needed
• Container starts silently in the background
• Does not block your shell prompt
• Only triggers on actual directory changes

Installation

Bash

Add the hook to your ~/.bashrc:

echo 'eval "$(skybox hook bash)"' >> ~/.bashrc
source ~/.bashrc

Zsh

Add the hook to your ~/.zshrc:

echo 'eval "$(skybox hook zsh)"' >> ~/.zshrc
source ~/.zshrc

Configuration

The shell hook only auto-starts containers for projects with auto_up enabled. By default, this is disabled (opt-in).

Enable for a Specific Project

Edit ~/.skybox/config.yaml directly:

projects:
  my-project:
    remote: work
    auto_up: true

Enable Globally

To auto-start all projects by default:

defaults:
  auto_up: true

projects:
  my-project:
    remote: work

Per-project settings override the global default:

defaults:
  auto_up: true  # Enable for all projects

projects:
  my-project:
    remote: work
    auto_up: false  # Disable for this specific project

How It Works

1. Hook Registration

   • Bash: Appends to PROMPT_COMMAND
   • Zsh: Registers a precmd hook via add-zsh-hook

2. Directory Change Detection

   • Tracks the previous directory in _SKYBOX_PREV_DIR
   • Only triggers when $PWD differs from the previous directory

3. Project Resolution

   • Checks if the current directory is inside ~/.skybox/Projects/
   • Extracts the project name from the path

4. Auto-Start Logic

   • Verifies auto_up is enabled for the project
   • Checks if the container is already running
   • If not running, spawns skybox up <project> --no-prompt in the background

5. Background Execution

   • The skybox up process runs detached from your shell
   • Output is logged to ~/.skybox/logs/auto-up.log
   • Your shell prompt returns immediately

Troubleshooting

Check the Log File

All auto-up activity is logged:

cat ~/.skybox/logs/auto-up.log

Example output:

[2026-02-03T10:30:00.000Z] [my-project] Auto-starting container...
[2026-02-03T10:30:05.000Z] [my-project] Container started successfully

Verify the Hook Is Active

Bash:

echo "$PROMPT_COMMAND"
# Should contain: _skybox_hook

Zsh:

typeset -f _skybox_hook
# Should output the function definition

Container Not Starting?

1. Check if auto_up is enabled:

   Check your ~/.skybox/config.yaml and look for auto_up: true under your project:

   skybox config

2. Verify you are in a SkyBox project directory:

   pwd
   # Should be inside ~/.skybox/Projects/<project-name>

3. Check if skybox is in your PATH:

   which skybox

4. Try running the check manually:

   skybox hook-check

   This is the hidden command the hook calls. It should exit silently if everything is working.

Disable the Hook Temporarily

To disable shell integration without removing it:

unset -f _skybox_hook

This lasts until you open a new shell.

See Also

• Daily Development - Manual startup workflow
• skybox up - Start a development container
• Configuration - SkyBox config reference