Core Concepts

Understanding the key primitives that make up Devboxes: base images 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.

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

Sessions → Learn about persistent terminal sessions that survive disconnections and devbox restarts.

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