Core Concepts

Understanding the key primitives that make up Devboxes: base images, blueprints, and lifecycle management.

Base Images

Base images define the software environment for your devbox using standard Dockerfiles. This includes development tools, language runtimes, packages, and any other software needed for your workflow.

FROM node:20-bookworm

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    build-essential \
    ca-certificates

# Install Node.js development tools globally
RUN npm install -g \
    typescript \
    ts-node \
    eslint \
    prettier \
    @types/node \
    turbo \
    pnpm

# Configure npm
RUN npm config set update-notifier false

Base images are built and cached by Namespace, enabling fast devbox provisioning.

Why Dockerfiles?

Using Dockerfiles for base images provides:

  • Familiarity: Use the same syntax you already know
  • Version control: Check your environment definition into git alongside your code
  • Flexibility: Install any software, configure any tools, customize any settings
  • Portability: Share consistent environments across your entire team

Advanced Base Images

Base images support the full Dockerfile specification, enabling complex environment setups:

FROM golang:1.21

# Install development tools
RUN apt-get update && apt-get install -y \
    git make vim postgresql-client

# Install Go tools
RUN go install golang.org/x/tools/gopls@latest
RUN go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Configure environment
ENV GO111MODULE=on
ENV GOPATH=/go

Namespace builds and caches base images, so subsequent devbox instances using the same Dockerfile start immediately without rebuild time.

Blueprints

Blueprints combine multiple components to create reusable devbox templates:

  • Base image: The Dockerfile defining installed software
  • Git repository: Source code automatically cloned on initialization
  • Default resources: CPU and memory configuration for devboxes
  • Port forwards: Network ports exposed for services
  • Environment variables: Configuration values and credentials
  • Initialization hooks: Commands or scripts that run when the devbox starts
  • Docker support: Optional Docker-in-Docker for container workflows
  • Privileged mode: Optional elevated permissions for system-level operations

Once you create a blueprint, you or your team can create new devboxes from it in just a few seconds.

Blueprint configuration interface

Creating Blueprints

You can create blueprints via the Dashboard or using the CLI:

$devbox blueprint create \
--name=main \
--machine_type=32x64 \
--dockerfile=Dockerfile \
--repository=github.com/namespacelabs/foundation

Blueprint Components in Detail

Git Repository:

  • Automatically cloned into the devbox on initialization
  • Built-in git access for commits, branches, and pull requests
  • Supports private repositories via GitHub integration

Port Forwards:

  • Expose services running in your devbox
  • Access via secure HTTPS endpoints
  • Supports multiple ports for complex applications

Environment Variables:

  • Configure application settings
  • Store credentials securely
  • Support for secret references from Namespace Vault

Initialization Hooks:

  • Run commands when the devbox starts
  • Execute scripts for setup tasks
  • Install additional dependencies dynamically

Lifecycle Management

Namespace manages your devbox lifecycle automatically:

  • Start on-demand: Devboxes start when you connect or trigger them
  • Pause when idle: After a period of inactivity, devboxes automatically pause to save costs
  • Persistence: Your code, files, and configuration remain intact across pause/resume cycles
  • Fast resume: Paused devboxes resume in seconds when needed

This intelligent lifecycle management ensures you only pay for active development time while maintaining instant access to your environments.

Lifecycle States

Running:

  • Devbox is active and consuming resources
  • Accessible via SSH, VSCode, Cursor, or web terminal
  • Billed based on resource usage

Paused:

  • Devbox is stopped and not consuming compute resources
  • File system and state are preserved
  • No compute charges, only storage costs

Starting:

  • Transitioning from paused to running state
  • Takes only seconds to resume
  • Initialization hooks run if configured

Resource Optimization

Lifecycle management helps optimize costs:

  • Automatically pause devboxes after periods of inactivity
  • Resume instantly when needed
  • Pay only for active development time
  • Persistent storage maintains your work across sessions

Next Steps

Introduction → Get started with creating your first devbox and connecting your development tools.

SSH & Remote Access → Learn how to connect to your devbox via SSH, web terminals, and IDE integrations.

Machine Shapes → Explore available CPU and memory configurations to find the optimal shape for your workload.

Last updated