# wrr/drop architecture

> Architecture diagram of the GitHub repository wrr/drop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wrr/drop
- Repository: https://github.com/wrr/drop

## Overview

Drop is a Linux sandbox manager for local command-line work. Its main workflow is to initialize an environment and config, then resolve that config and launch a command in isolated namespaces, with a filesystem assembled for the sandbox and optional gVisor execution. The run path also configures pasta networking and coordinates parent and child processes over IPC, with PTY forwarding for interactive sessions. The README documents additional environment management and config editing commands. Some subsystem links are grounded in README capability descriptions because their implementations were not excerpted.

Main entry points: [`internal/command/run.go`](https://github.com/wrr/drop/blob/main/internal/command/run.go) (Run coordinator), [`cmd/drop/main.go`](https://github.com/wrr/drop/blob/main/cmd/drop/main.go) (Drop entry), [`internal/command/init.go`](https://github.com/wrr/drop/blob/main/internal/command/init.go) (Environment init), [`internal/cli/cli.go`](https://github.com/wrr/drop/blob/main/internal/cli/cli.go) (Command router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["CLI and environments"]
  node_entry["Drop entry<br/>[main.go]"]
  node_cli["Command router<br/>[cli.go]"]
  node_init["Environment init<br/>[init.go]"]
  node_edit["Config editor<br/>[edit.go]"]
  node_envstore[("Environment store<br/>[paths.go]")]
  node_config["Config loading<br/>[config.go]"]
  node_defaults["Default config<br/>[default.go]"]
end

subgraph group_sandbox["Sandbox runtime"]
  node_run["Run coordinator<br/>[run.go]"]
  node_envvars["Environment vars<br/>[env.go]"]
  node_filesystem["Root filesystem<br/>[mount.go]"]
  node_paths["Sandbox paths<br/>[paths.go]"]
  node_etcfiles["Sandbox /etc<br/>[etc.go]"]
  node_cwd["Working directory<br/>[cwd.go]"]
end

subgraph group_isolation["Isolation services"]
  node_namespace["Linux namespaces<br/>[run.go]"]
  node_network["Pasta networking<br/>[netns.go]"]
  node_gvisor["gVisor runtime<br/>[gvisor.go]"]
end

subgraph group_support["Runtime support"]
  node_ipc["Parent-child IPC<br/>[ipc.go]"]
  node_pty["PTY handling<br/>[pty.go]"]
  node_ptyipc["PTY socket<br/>[ptysocket.go]"]
  node_updater["Update check<br/>[updater.go]"]
end

node_user(("User"))
node_pasta["pasta service"]
node_runsc["runsc"]
node_hostcommand(("Host command"))
node_update_service["Release service"]

node_user -->|"runs"| node_entry
node_entry -->|"routes"| node_cli
node_entry -->|"dispatches init"| node_init
node_entry -->|"dispatches run"| node_run
node_cli -->|"dispatches init"| node_init
node_cli -->|"dispatches run"| node_run
node_entry -->|"dispatches edit"| node_edit
node_entry -->|"lists or removes"| node_envstore
node_init -->|"creates environment"| node_envstore
node_init -->|"writes defaults"| node_defaults
node_init -->|"writes base config"| node_config
node_run -->|"loads config"| node_config
node_run -.->|"creates paths"| node_paths
node_run -->|"sets up"| node_namespace
node_run -->|"assembles root"| node_filesystem
node_run -->|"writes files"| node_etcfiles
node_run -->|"starts networking"| node_network
node_network -->|"starts"| node_pasta
node_run -->|"sends child args"| node_ipc
node_run -->|"forwards terminal"| node_pty
node_run -.->|"passes PTY"| node_ptyipc
node_run -.->|"prepares variables"| node_envvars
node_run -->|"executes optionally"| node_gvisor
node_gvisor -->|"execs"| node_runsc
node_run -.->|"executes natively"| node_hostcommand
node_entry -->|"checks version"| node_updater
node_updater -.->|"checks releases"| node_update_service
node_edit -.->|"edits config"| node_config
node_filesystem -.->|"uses locations"| node_paths
node_run -.->|"sets sandbox cwd"| node_cwd

click node_entry "https://github.com/wrr/drop/blob/main/cmd/drop/main.go"
click node_cli "https://github.com/wrr/drop/blob/main/internal/cli/cli.go"
click node_init "https://github.com/wrr/drop/blob/main/internal/command/init.go"
click node_edit "https://github.com/wrr/drop/blob/main/internal/command/edit.go"
click node_envstore "https://github.com/wrr/drop/blob/main/internal/jailfs/paths.go"
click node_config "https://github.com/wrr/drop/blob/main/internal/config/config.go"
click node_defaults "https://github.com/wrr/drop/blob/main/internal/config/default.go"
click node_run "https://github.com/wrr/drop/blob/main/internal/command/run.go"
click node_envvars "https://github.com/wrr/drop/blob/main/internal/env/env.go"
click node_filesystem "https://github.com/wrr/drop/blob/main/internal/jailfs/mount.go"
click node_paths "https://github.com/wrr/drop/blob/main/internal/jailfs/paths.go"
click node_etcfiles "https://github.com/wrr/drop/blob/main/internal/jailfs/etc.go"
click node_cwd "https://github.com/wrr/drop/blob/main/internal/jailfs/cwd.go"
click node_namespace "https://github.com/wrr/drop/blob/main/internal/command/run.go"
click node_network "https://github.com/wrr/drop/blob/main/internal/netns/netns.go"
click node_gvisor "https://github.com/wrr/drop/blob/main/internal/gvisor/gvisor.go"
click node_ipc "https://github.com/wrr/drop/blob/main/internal/ipc/ipc.go"
click node_pty "https://github.com/wrr/drop/blob/main/internal/pty/pty.go"
click node_ptyipc "https://github.com/wrr/drop/blob/main/internal/ipc/ptysocket.go"
click node_updater "https://github.com/wrr/drop/blob/main/internal/updater/updater.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_cli,node_init,node_edit,node_envstore,node_config,node_defaults,node_user toneBlue
class node_run,node_envvars,node_filesystem,node_paths,node_etcfiles,node_cwd toneAmber
class node_namespace,node_network,node_gvisor toneMint
class node_ipc,node_pty,node_ptyipc,node_updater toneRose
class node_pasta,node_runsc,node_hostcommand,node_update_service toneIndigo
```

## Components

### CLI and environments

- [Drop entry](https://github.com/wrr/drop/blob/main/cmd/drop/main.go): `cmd/drop/main.go`
- [Command router](https://github.com/wrr/drop/blob/main/internal/cli/cli.go): `internal/cli/cli.go`
- [Environment init](https://github.com/wrr/drop/blob/main/internal/command/init.go): `internal/command/init.go`
- [Config editor](https://github.com/wrr/drop/blob/main/internal/command/edit.go): `internal/command/edit.go`
- [Environment store](https://github.com/wrr/drop/blob/main/internal/jailfs/paths.go): `internal/jailfs/paths.go`
- [Config loading](https://github.com/wrr/drop/blob/main/internal/config/config.go): `internal/config/config.go`
- [Default config](https://github.com/wrr/drop/blob/main/internal/config/default.go): `internal/config/default.go`

### Sandbox runtime

- [Run coordinator](https://github.com/wrr/drop/blob/main/internal/command/run.go): `internal/command/run.go`
- [Environment vars](https://github.com/wrr/drop/blob/main/internal/env/env.go): `internal/env/env.go`
- [Root filesystem](https://github.com/wrr/drop/blob/main/internal/jailfs/mount.go): `internal/jailfs/mount.go`
- [Sandbox paths](https://github.com/wrr/drop/blob/main/internal/jailfs/paths.go): `internal/jailfs/paths.go`
- [Sandbox /etc](https://github.com/wrr/drop/blob/main/internal/jailfs/etc.go): `internal/jailfs/etc.go`
- [Working directory](https://github.com/wrr/drop/blob/main/internal/jailfs/cwd.go): `internal/jailfs/cwd.go`

### Isolation services

- [Linux namespaces](https://github.com/wrr/drop/blob/main/internal/command/run.go): `internal/command/run.go`
- [Pasta networking](https://github.com/wrr/drop/blob/main/internal/netns/netns.go): `internal/netns/netns.go`
- [gVisor runtime](https://github.com/wrr/drop/blob/main/internal/gvisor/gvisor.go): `internal/gvisor/gvisor.go`

### Runtime support

- [Parent-child IPC](https://github.com/wrr/drop/blob/main/internal/ipc/ipc.go): `internal/ipc/ipc.go`
- [PTY handling](https://github.com/wrr/drop/blob/main/internal/pty/pty.go): `internal/pty/pty.go`
- [PTY socket](https://github.com/wrr/drop/blob/main/internal/ipc/ptysocket.go): `internal/ipc/ptysocket.go`
- [Update check](https://github.com/wrr/drop/blob/main/internal/updater/updater.go): `internal/updater/updater.go`

### Other components

- **User**
- **pasta service**
- **runsc**
- **Host command**
- **Release service**

## Connections

- User → Drop entry: runs (evidence: `README.md`)
- Drop entry → Command router: routes (evidence: `cmd/drop/main.go`)
- Drop entry → Environment init: dispatches init (evidence: `cmd/drop/main.go`)
- Drop entry → Run coordinator: dispatches run (evidence: `cmd/drop/main.go`)
- Command router → Environment init: dispatches init (evidence: `internal/cli/cli.go`)
- Command router → Run coordinator: dispatches run (evidence: `internal/cli/cli.go`)
- Drop entry → Config editor: dispatches edit (evidence: `cmd/drop/main.go`)
- Drop entry → Environment store: lists or removes (evidence: `cmd/drop/main.go`)
- Environment init → Environment store: creates environment (evidence: `internal/command/init.go`)
- Environment init → Default config: writes defaults (evidence: `internal/command/init.go`)
- Environment init → Config loading: writes base config (evidence: `internal/command/init.go`)
- Run coordinator → Config loading: loads config (evidence: `internal/command/run.go`)
- Run coordinator → Sandbox paths: creates paths
- Run coordinator → Linux namespaces: sets up (evidence: `README.md`)
- Run coordinator → Root filesystem: assembles root (evidence: `internal/command/run.go`)
- Run coordinator → Sandbox /etc: writes files (evidence: `internal/command/run.go`)
- Run coordinator → Pasta networking: starts networking (evidence: `internal/command/run.go`)
- Pasta networking → pasta service: starts (evidence: `internal/netns/netns.go`)
- Run coordinator → Parent-child IPC: sends child args (evidence: `internal/command/run.go`)
- Run coordinator → PTY handling: forwards terminal (evidence: `internal/command/run.go`)
- Run coordinator → PTY socket: passes PTY
- Run coordinator → Environment vars: prepares variables
- Run coordinator → gVisor runtime: executes optionally (evidence: `internal/command/run.go`)
- gVisor runtime → runsc: execs (evidence: `internal/gvisor/gvisor.go`)
- Run coordinator → Host command: executes natively
- Drop entry → Update check: checks version (evidence: `cmd/drop/main.go`)
- Update check → Release service: checks releases
- Config editor → Config loading: edits config
- Root filesystem → Sandbox paths: uses locations
- Run coordinator → Working directory: sets sandbox cwd
