Client Configuration

Reference for ~/.podspawn/config.yaml, covering local defaults and server routing with .pod hostnames.

The client configuration file lives at ~/.podspawn/config.yaml. In local mode, it stores container defaults. In client mode, it tells the podspawn CLI how to resolve .pod hostnames to real server addresses.

config.yaml

podfile.yaml

Local mode

The setup wizard (run by curl -sSfL https://podspawn.dev/up | bash) generates a local section with your container defaults. You can also create or edit this file by hand.

Full example

local:
  image: ubuntu:24.04
  shell: /bin/bash
  cpus: 2
  memory: 2g
  max_lifetime: 24h
  mode: grace-period

Fields

Field	Type	Default	Description
`image`	`string`	`ubuntu:24.04`	Default base image for containers created with `podspawn create`.
`shell`	`string`	`/bin/bash`	Shell launched by `podspawn shell`.
`cpus`	`int`	`2`	CPU cores allocated to each container.
`memory`	`string`	`2g`	Memory limit. Accepts `g`/`m` suffixes.
`max_lifetime`	`string`	`24h`	Maximum container lifetime before auto-cleanup.
`mode`	`string`	`grace-period`	Lifecycle mode (`grace-period` or `destroy-on-disconnect`).

You can edit these files anytime. See the Podfile reference for all options.

Default Podfile

The wizard also generates ~/.podspawn/podfile.yaml with packages and services based on your choices. This acts as a fallback Podfile when a project directory doesn't have its own. See Podfile Overview for the full field reference.

Example generated by choosing "web dev" + PostgreSQL + Redis:

base: ubuntu:24.04
shell: /bin/bash
packages:
  - nodejs
  - python3
  - git
  - curl
  - ripgrep
services:
  - name: postgres
    image: postgres:16
    env:
      POSTGRES_PASSWORD: devpass
  - name: redis
    image: redis:7

Client mode (server routing)

In client mode, the same file stores server routing for .pod hostnames. A missing servers section is an error in client mode since there are no useful defaults.

Full example

servers:
  default: dev.example.org:22
  mappings:
    work.pod: work-server.internal:2222
    personal.pod: 192.168.1.50:22
    staging.pod: staging.example.org:22

servers

Field	Type	Default	Description
`default`	`string`	(none, required)	Fallback server address for any `.pod` hostname that does not have a specific mapping.
`mappings`	`map[string]string`	`{}`	Explicit hostname-to-server mappings. Keys are `.pod` hostnames, values are `host:port` addresses.

How resolution works

When you run podspawn connect myproject.pod, the client resolves the hostname in this order:

If the hostname does not end in .pod, it passes through unchanged (treated as a direct address).

If servers.mappings contains an exact match for the hostname, that server address is used.

Otherwise, servers.default is used as the fallback.

If neither a mapping nor a default exists, the connection fails with an error.

The .pod suffix is what triggers routing. Plain hostnames like 192.168.1.50 or my-server.example.org bypass the resolution logic entirely.

Minimal config

If you only have one podspawn server, you just need default:

servers:
  default: my-server.example.org:22

Every .pod hostname will route to that server.

Client Configuration

On this page