schepper
Declarative manager for Docker Sandboxes (sbx).
Each project gets a schepper.yaml. Run schepper up to create or reconcile the sandbox to match.
Notice that Docker itself is working on a similar feature.
Install
uv tool install schepper
Workflow
cd ~/Projects/myproject
schepper init # creates schepper.yaml with defaults
# edit schepper.yaml
schepper up # creates sandbox, confirms, then prints the attach command
schepper run # attach interactively
Commands
| Command | Description |
|---|---|
schepper init |
Scaffold schepper.yaml in current project dir |
schepper up |
Align sandbox with config and start it; confirms all changes, warns before recreation |
schepper run |
Attach to the sandbox interactively (must already exist) |
schepper down |
Stop sandbox |
schepper rm |
Remove sandbox (with confirmation) |
schepper status |
Show status, kit, memory, ports for the current sandbox |
schepper inspect [name] |
Print a live sandbox's config as schepper.yaml (copy-pasteable) |
schepper ls |
List all sandboxes (sbx ls) |
schepper ssh |
Run sbx setup ssh globally (once) |
schepper.yaml
name: myproject
kit: claude
memory: 8g
cpus: 0
storage: 10g
ports:
- 3000
- 8000-8010
ssh: false
| Field | Default | Description |
|---|---|---|
name |
current directory name | Sandbox name passed to sbx |
kit |
claude |
Agent kit: claude, codex, shell, etc. |
memory |
8g |
Memory limit in binary units, e.g. 512m, 4g, 8g |
cpus |
0 |
CPU count; 0 = auto (all host CPUs) |
storage |
10g |
VM root disk size. Cannot be changed on an existing sandbox — requires schepper rm && schepper up. |
ports |
[] |
Ports to publish. Ranges like 8000-8010 are expanded. |
ssh |
false |
When true, runs sbx setup ssh on every schepper up |
Ports are always mapped symmetrically (3000:3000), so localhost:3000 works identically inside and outside the sandbox — Claude can suggest a preview URL and it just works.
Notes
- Changing
memoryorkiton an existing sandbox requires recreation.schepper upwill detect the diff, warn, and ask to confirm before removing and recreating. Changingstoragealso requires recreation, butschepper upcannot detect it automatically — runschepper rm && schepper upmanually. - SSH:
schepper ssh(orssh: truein config) runssbx setup ssh, which writes an~/.ssh/configentry sossh <name>.sbxconnects without further setup.
Development
git clone https://github.com/Ecno92/schepper
cd schepper
uv sync --extra dev
uv run pytest tests/ -v
To publish a new release:
uv build
uv publish
1 maintainer
Metadata
1 maintainer
Release files for schepper 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| schepper-0.1.0.tar.gz | 34.5 kB | Without provenance | Details for schepper-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| schepper-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for schepper-0.1.0-py3-none-any.whl |
Total release size: 46.3 kB
Release files / schepper-0.1.0.tar.gz
| Download URL | schepper-0.1.0.tar.gz |
|---|---|
| Size | 34.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3f28e4b2ceda29974ffb049be08a13b9b5eb141893df68a5a5c71d2274e36718
|
|
BLAKE2b-256 checksum How to use checksums |
49eb6beb240669741d00d6bb484b3f55624a8eefc39286b540b0ea442c6b17ee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / schepper-0.1.0-py3-none-any.whl
| Download URL | schepper-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fd242be7245737d2e034973f37a81bb0389b656b103af6c3f7d6a09204723752
|
|
BLAKE2b-256 checksum How to use checksums |
d458cd495ddf29b66bbf8df54fb3e0d97b049a0e789a0de38c40627e06a128f7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for schepper 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
