sboxd 0.1.7

Policy-driven command runner for sandboxed dependency installation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

# Transparent Interception with Shims

Shims let you use sbox without changing your existing workflow. Once installed, running `npm install` in a project with `sbox.yaml` automatically delegates to `sbox run -- npm install`. In a project without `sbox.yaml`, the real npm runs unchanged.

## Installing shims

```bash
sbox shim                        # install to ~/.local/bin (default)
sbox shim --dir ~/bin            # custom directory
sbox shim --force                # overwrite existing shims
sbox shim --dry-run              # preview what would be created
```

After installing, add the shim directory before the real binaries in your PATH:

```bash
# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"
```

Verify the shim is active:

```bash
which npm          # should show ~/.local/bin/npm
npm --version      # calls the shim, which passes through to real npm (no sbox.yaml here)
```

## Supported package managers

| Shim | Intercepts |
|------|-----------|
| `npm` | All npm commands |
| `npx` | npx invocations |
| `pnpm` | All pnpm commands |
| `yarn` | All yarn commands |
| `bun` | All bun commands |
| `uv` | All uv commands |
| `pip` | All pip commands |
| `pip3` | All pip3 commands |
| `poetry` | All poetry commands |
| `cargo` | All cargo commands |
| `composer` | All composer commands |

## How shims work

Each shim is a small shell script:

```bash
#!/bin/sh
# sbox shim: npm
# Generated by `sbox shim`. Re-run `sbox shim --dir DIR` to regenerate.
_sbox_d="$PWD"
while true; do
  if [ -f "$_sbox_d/sbox.yaml" ]; then
    exec sbox run -- npm "$@"
  fi
  [ "$_sbox_d" = "/" ] && break
  _sbox_d="${_sbox_d%/*}"
  [ -z "$_sbox_d" ] && _sbox_d="/"
done
exec /usr/bin/npm "$@"
```

The shim walks up the directory tree from `$PWD`, checking each level for `sbox.yaml`. If found at any level, it delegates to sbox. If the root is reached without finding a config, the real binary is called with all original arguments.

The path to the real binary is hardcoded at shim-generation time (by `sbox shim`) to avoid PATH lookup loops. If the real binary moves, re-run `sbox shim` to regenerate.

Exit codes, stdin, stdout, and stderr are passed through unchanged. The shim is transparent to the calling process.

## Dispatch rules with shims

When a shim delegates to sbox, sbox applies the normal dispatch rules. For example, with:

```yaml
dispatch:
  npm-install:
    match:
      - "npm install*"
    profile: install
  npm-run:
    match:
      - "npm run*"
    profile: default
```

Running `npm install` uses the `install` profile (network on, registry allowlist, lockfile check).
Running `npm run build` uses the `default` profile (network off).

## Removing shims

```bash
rm ~/.local/bin/npm ~/.local/bin/npx  # remove individual shims
# or remove all at once:
sbox shim --dry-run                   # list shim paths
```

## Team setup

For a team where everyone should have sbox active:

```bash
# System-wide (requires sudo)
sudo sbox shim --dir /usr/local/bin

# Or document in the project README:
echo "Run: sbox shim && export PATH=\"\$HOME/.local/bin:\$PATH\""
```

Projects without `sbox.yaml` are unaffected.