podspawnpodspawn shell
Attach to a local machine with an interactive shell, or restart a stopped project-backed machine
Attaches to a running podspawn machine with an interactive shell. This is the primary way to connect to local machines.
Usage
podspawn shell <name>
podspawn shell <user@name>Arguments
| Argument | Required | Description |
|---|---|---|
name | Yes | Machine name to attach to |
user | No | Username prefix, same user@host format as other commands |
Examples
# Attach to a machine
$ podspawn shell dev# Attach as a specific user
$ podspawn shell alice@backendHow it works
podspawn shell uses Docker exec to open a shell inside the container as your non-root user. No SSH is involved, so there is nothing to configure and no port conflicts to worry about. The shell prompt shows username@machinename (e.g., karthik@dev:~$).
This is the primary way to use podspawn locally. SSH is a separate feature for remote access, team servers, and IDE integration.
For project-backed machines created with podspawn create --project ..., shell also acts as the restart entrypoint. If the container was stopped with podspawn stop, podspawn recreates it from the saved workspace under ~/.podspawn/workspaces/<name>/, reruns on_start, and skips on_create once the machine's persisted initialization flag is set. If a previous on_create failed before initialization completed, shell retries it.
When you need SSH instead
podspawn shell covers the interactive terminal use case. For these features, you need a server-mode SSH setup:
| Feature | shell | SSH |
|---|---|---|
| Interactive terminal | Yes | Yes |
| SFTP / file transfer | No (docker cp works) | Yes |
Port forwarding (-L, -R) | No | Yes |
| VS Code Remote SSH | No | Yes |
| Cursor Remote | No | Yes |
| JetBrains Gateway | No | Yes |
| SSH agent forwarding | No | Yes |
See the server commands docs for setting up SSH access.
How is this guide?