Creating a New Project

This guide walks through creating projects with SkyBox, whether starting from scratch or bringing an existing codebase.

Prerequisites

Before creating projects, ensure SkyBox is configured:

bash

skybox init

This sets up your remote server connection and preferred editor.

Option 1: Push an Existing Project

The most common workflow is pushing a local project to SkyBox for containerized development.

Step 1: Push Your Project

bash

skybox push ./my-project

Or specify a custom name:

bash

skybox push ./my-project my-app

Step 2: What Happens

Git Check - SkyBox verifies the project is a git repository (offers to initialize if not)
Remote Creation - Creates the project directory on your remote server
Local Copy - Copies files to ~/.skybox/Projects/<project-name>
Sync Setup - Establishes two-way sync with Mutagen
Initial Sync - Waits for all files to sync to remote

Step 3: Start Development

After push completes, start the container:

bash

skybox up my-project

Option 2: Clone from Remote

If a project already exists on your remote server (perhaps pushed from another machine), clone it locally.

Step 1: Browse Available Projects

bash

skybox browse

This shows all projects in your remote code directory:

Remote projects (myserver:~/code):

  backend-api
    Branch: main

  frontend-app
    Branch: feature/auth

Step 2: Clone the Project

bash

skybox clone backend-api

Step 3: What Happens

Remote Check - Verifies the project exists on remote
Local Directory - Creates ~/.skybox/Projects/backend-api
Sync Session - Creates Mutagen sync session
Initial Sync - Downloads all files from remote
Optional Start - Prompts to start the dev container

Option 3: Create a New Project with `skybox new`

The skybox new command creates a project on the remote server from scratch, with full template selection:

bash

skybox new

SkyBox walks you through the full setup:

Creates the project on the remote server
Prompts for template selection (see below)
Generates devcontainer configuration
Sets up sync and optionally starts the container

This is the recommended way to start a brand new project.

Option 4: Start from a Template (Existing Directory)

When pushing a project that has no devcontainer.json, SkyBox automatically offers template selection during skybox up.

Step 1: Create Project Directory

bash

mkdir ~/code/new-app
cd ~/code/new-app
git init

Step 2: Push to SkyBox

bash

skybox push .

Step 3: Start and Select Template

bash

skybox up new-app

SkyBox detects no devcontainer.json and offers templates:

? Select a template:
── Built-in ──
  Node.js — Node (latest) with npm/yarn + Common Utils + Docker
  Bun — Bun (latest) + Common Utils + Docker
  Python — Python (latest) with pip/venv + Common Utils + Docker
  Go — Go (latest) + Common Utils + Docker
  Generic — Debian with Common Utils + Docker
── Your Templates ──
  Create new template

Available Templates

Template	Base Image	Includes
Node.js	Debian + Node feature	Node.js (latest), npm/yarn, zsh, Docker, Git, SSH passthrough, ESLint extension
Bun	Debian + Bun feature	Bun runtime, zsh, Docker, Git, SSH passthrough, Bun VS Code extension
Python	Debian + Python feature	Python (latest), pip, venv, zsh, Docker, Git, SSH passthrough, Python extension
Go	Debian + Go feature	Go (latest), Go tools, zsh, Docker, Git, SSH passthrough, Go extension
Generic	Debian	zsh, Docker, Git, SSH passthrough

You can also use a custom template by providing a git URL. In the template selector, choose "Enter git URL" under the "Other" section:

? Select a template:
── Built-in ──
  Node.js — Node (latest) with npm/yarn + Common Utils + Docker
  Bun — Bun (latest) + Common Utils + Docker
  Python — Python (latest) with pip/venv + Common Utils + Docker
  Go — Go (latest) + Common Utils + Docker
  Generic — Debian with Common Utils + Docker
── Other ──
  Enter git URL
── Your Templates ──
  Create new template

When selecting "Enter git URL", provide a git repository URL:

? Git repository URL: https://github.com/my-org/custom-devcontainer.git

All built-in templates include these common features:

common-utils -- zsh (default shell), oh-my-zsh, and essential utilities
docker-outside-of-docker -- access the host Docker daemon from inside the container
git -- pre-installed for version control
SSH passthrough -- your host ~/.ssh directory is bind-mounted read-only, so container Git operations use your existing SSH keys

Step 4: Template Creates Configuration

SkyBox creates .devcontainer/devcontainer.json:

json

{
  "name": "Node.js",
  "image": "mcr.microsoft.com/devcontainers/base:debian",
  "workspaceFolder": "/workspaces/new-app",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {},
    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {},
    "ghcr.io/devcontainers/features/git:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": ["dbaeumer.vscode-eslint"]
    }
  }
}

This configuration is automatically committed to git.

Customizing devcontainer.json

After SkyBox creates the initial configuration, you can customize it:

Add More Extensions

json

{
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "bradlc.vscode-tailwindcss"
      ]
    }
  }
}

Add Environment Variables

json

{
  "containerEnv": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgres://localhost:5432/mydb"
  }
}

Add Services with Docker Compose

For more complex setups (databases, caches), create .devcontainer/docker-compose.yml:

yaml

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ..:/workspaces/my-app:cached

  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: dev

Update devcontainer.json:

json

{
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspaces/my-app"
}

Project Structure After Setup

After creating a project, your file structure looks like:

~/.skybox/
  Projects/
    my-project/           # Local synced copy
      .devcontainer/
        devcontainer.json
      .git/
      src/
      package.json

Remote (your-server:~/code/):
  my-project/             # Remote backup copy
    .devcontainer/
      devcontainer.json
    .git/
    src/
    package.json

Verifying Setup

Check your project status:

bash

skybox status my-project

Output shows:

Project: my-project
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Container
  Status:     running
  Image:      mcr.microsoft.com/devcontainers/base:debian
  Uptime:     2 hours
  CPU:        0.5%
  Memory:     256M / 4G

Sync
  Status:     syncing
  Session:    skybox-my-project
  Pending:    0 files
  Last sync:  -

Git
  Branch:     main
  Status:     clean
  Ahead:      0 commits
  Behind:     0 commits

Session
  Status:     active here
  Machine:    my-laptop
  User:       me
  Started:    2 hours ago
  PID:        12345

Disk Usage
  Local:      45M
  Remote:     44M

Command	Usage in this workflow
`skybox push`	Push a local project to remote
`skybox clone`	Clone a remote project locally
`skybox new`	Create a new project from scratch
`skybox browse`	List available remote projects
`skybox up`	Start the dev container
`skybox status`	Verify project setup
`skybox init`	Initial SkyBox setup

Next Steps

Daily Development - Learn the day-to-day workflow
Multi-Machine Workflow - Working across multiple computers

Creating a New Project ​

Prerequisites ​

Option 1: Push an Existing Project ​

Step 1: Push Your Project ​

Step 2: What Happens ​

Step 3: Start Development ​

Option 2: Clone from Remote ​

Step 1: Browse Available Projects ​

Step 2: Clone the Project ​

Step 3: What Happens ​

Option 3: Create a New Project with skybox new ​

Option 4: Start from a Template (Existing Directory) ​

Step 1: Create Project Directory ​

Step 2: Push to SkyBox ​

Step 3: Start and Select Template ​

Available Templates ​

Step 4: Template Creates Configuration ​

Customizing devcontainer.json ​

Add More Extensions ​

Add Environment Variables ​

Add Services with Docker Compose ​

Project Structure After Setup ​

Verifying Setup ​

Related Commands ​

Next Steps ​

Creating a New Project

Prerequisites

Option 1: Push an Existing Project

Step 1: Push Your Project

Step 2: What Happens

Step 3: Start Development

Option 2: Clone from Remote

Step 1: Browse Available Projects

Step 2: Clone the Project

Step 3: What Happens

Option 3: Create a New Project with `skybox new`

Option 4: Start from a Template (Existing Directory)

Step 1: Create Project Directory

Step 2: Push to SkyBox

Step 3: Start and Select Template

Available Templates

Step 4: Template Creates Configuration

Customizing devcontainer.json

Add More Extensions

Add Environment Variables

Add Services with Docker Compose

Project Structure After Setup

Verifying Setup

Related Commands

Next Steps