skybox init

Interactive setup wizard for configuring SkyBox.

Usage

skybox init

Arguments

This command takes no arguments.

Options

Option	Description
--dry-run	Preview what would happen without executing

Description

The init command walks you through the initial SkyBox configuration:

1. Dependency Check - Verifies Docker and Node.js are installed
2. Mutagen Installation - Extracts the bundled Mutagen binary for file synchronization (if not already installed)
3. Remote Server Configuration - Sets up SSH connection to your remote server
4. Editor Selection - Configures your preferred code editor
5. Encryption Default - Optionally enable encryption for new projects by default

If SkyBox is already configured, you'll be asked whether to reconfigure.

Dependency Requirements

• Docker - Required for running containers
• Node.js - Required for the SkyBox CLI and devcontainer-cli

Mutagen Installation

Mutagen is bundled with SkyBox and extracted automatically during setup. In development mode (running from source), SkyBox falls back to downloading from GitHub if the bundled asset is not found.

When downloading (dev mode only), SkyBox verifies the binary's integrity using SHA256 checksum — the download is verified against the official SHA256SUMS file before writing to disk.

Remote Configuration

The wizard configures your first remote server. You can add more remotes later with skybox remote add.

The wizard allows you to:

• Enter a name for the remote (e.g., "production", "personal")
• Select an existing SSH host from your ~/.ssh/config
• Add a new server with hostname, username, and SSH key
• Test the SSH connection
• Optionally copy your SSH key to the server using ssh-copy-id
• Set the remote base path for storing projects (default: ~/code)

SSH fields are validated as you enter them. Hostnames, usernames, key paths, and remote paths are checked for invalid characters (such as newlines or shell metacharacters) and will prompt you to re-enter if invalid.

SSH Key Authentication

SkyBox supports both passwordless and passphrase-protected SSH keys.

When you select a passphrase-protected key during setup, SkyBox loads it into ssh-agent so you only need to enter your passphrase once per session. The behavior varies by platform:

• macOS — You are offered the option to save the passphrase to the macOS Keychain. When enabled (useKeychain: true in config), the passphrase persists across reboots and you won't be prompted again.
• Linux — The passphrase is held in ssh-agent for the duration of your current login session. You will need to re-enter it after logging out or rebooting.

If no ssh-agent is running, SkyBox will inform you and provide instructions to start one:

eval $(ssh-agent)

TIP

If you already have your key loaded in ssh-agent (check with ssh-add -l), SkyBox will detect it and skip the passphrase prompt.

Editor Options

SkyBox has built-in support for these editors:

Editor	Command
Cursor	cursor
VS Code	code
VS Code Insiders	code-insiders
Zed	zed
Other	custom command

Vim (vim), Neovim (nvim), and any custom editor command are also supported.

Examples

# Run the setup wizard
skybox init

Example Session

Welcome to skybox setup!

Checking dependencies...
  Docker installed
  Node.js available

Installing mutagen...
  Mutagen installed

Configure remote server
? Remote name: production
? Select SSH host: my-server (192.168.1.100)
  SSH connection successful

? Remote code directory: ~/code
  Remote directory exists

Configure editor
? Preferred editor: Cursor

Setting up skybox...
  Created ~/.skybox
  Saved configuration

  skybox is ready!

Next steps:
  Push a local project: skybox push ./my-project
  Clone from remote: skybox clone <project-name>
  Browse remote projects: skybox browse

Configuration File

After running init, SkyBox creates a configuration file at ~/.skybox/config.yaml containing:

• Remote server configurations (supports multiple remotes)
• Default editor
• Sync settings and ignore patterns
• Registered projects with remote associations

See Also

• skybox remote - Add more remote servers
• skybox config - View and modify configuration
• skybox editor - Change the default editor later
• skybox browse - View projects on remote server
• skybox push - Push a local project to remote