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.

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.