Documentation Introduction

Getting Started

Installation Quick Start Client Setup

Concepts

Architecture Session Lifecycle Authentication Model Networking

Configuration

Server Configuration Client Configuration Security Configuration User Overrides

Podfile

Podfile Overview Packages Services Hooks & Lifecycle devcontainer.json Fallback

Dev Environments

Getting Started with podspawn dev Writing a Podfile for Your Repo Scaffolding with podspawn init Services & Port Forwarding Extending Podfiles Podfile Reference (Complete)Real-World Examples

CLI Reference

podspawn create podspawn run podspawn shell Server Commands Client Commands Admin Commands

Guides

Tutorial Podspawn vs Devcontainers SSH Features Security Hardening AI Agent Environments IDE Integration Operations Troubleshooting

Operations

Running podspawn in production

This guide covers day-to-day operations for podspawn servers: backups, upgrades, monitoring, capacity planning, and log management.

State directory layout

state.db

state.db-wal

state.db-shm

podspawn.log

audit.jsonl

config.yaml

projects.yaml

emergency.keys

Security Hardening

Troubleshooting

Server Config

How is this guide?

IDE Integration

Using VS Code Remote SSH, JetBrains Gateway, and Cursor Remote with podspawn

Troubleshooting

Common issues and how to fix them

On this page

State directory layout SQLite backup Full backup script Restore Upgrade procedure What happens to existing sessions Quick status check Prometheus metrics Cleanup daemon health Audit logging Disk Persistent mode homes Memory Container limits logrotate configuration Verifying rotation