Skip to main content
Change of provenance

The repository or configuration that created this release differ from a previous release. View details.

Bosn

Bosn is a Rust daemon for safely managing Docker development applications. It keeps ownership, generation, volume, lease, execution-session, and event state in a durable SQLite registry. The daemon is the only component that mutates Docker or that writes that registry.

The distribution includes three intentionally thin front ends:

  • bosn, a bundled native CLI;
  • import bosn, a PyO3 client binding; and
  • bosn mcp, a stdio MCP server for Hermes and other MCP clients.

The former Python daemon, Docker front doors, manifest parser, and SQLite registry are deliberately not packaged. Python callers use bosn.Client; they cannot import or invoke a second lifecycle implementation.

Install

pip install bosn
bosn --version

Platform wheels contain the native bosn CLI and the bosn._native Python extension. Installing the wheel puts the bosn binary itself into the environment's scripts directory, so the bosn on PATH is the native CLI, with no Python wrapper in between. The extension uses PyO3's abi3-py310 ABI, so Bosn supports CPython 3.10 and newer with one platform wheel rather than publishing cp311-only artifacts.

One-file setup

Bosn accepts a local file or HTTPS URL for a versioned setup document. The document declares a digest-pinned image or inline Dockerfile, optional inline files, environment, bind mounts, named volumes, tmpfs mounts, and named tasks. Planning is inert; ensure and task submission are daemon-owned jobs.

version = 1

[app]
image = "registry.example/team/app@sha256:REPLACE_WITH_64_LOWERCASE_HEX_DIGEST"
command = "exec sleep 120"

[task.check]
command = "cargo check"
bosn setup plan --state-dir "$HOME/.local/state/bosn" \
  --workspace "$PWD" --config https://example.invalid/bosn-setup.toml \
  --refresh
bosn setup ensure --state-dir "$HOME/.local/state/bosn" \
  --workspace "$PWD" --config https://example.invalid/bosn-setup.toml \
  --refresh --deadline-ms 300000 --output-limit 8388608

online_refresh is explicit; offline_cache_only uses only a previously validated local cache record. URLs with credentials, unsupported schemes, path traversal, unpinned images, and oversized documents are refused.

Python

from pathlib import Path
import bosn

client = bosn.Client(Path.home() / ".local/state/bosn")
plan = client.plan_setup(
    Path.cwd(), "https://example.invalid/bosn-setup.toml", policy="online_refresh"
)
job_id = client.submit_setup_ensure(
    Path.cwd(),
    "https://example.invalid/bosn-setup.toml",
    policy="online_refresh",
    deadline_ms=300_000,
    output_limit=8 * 1024 * 1024,
)

The binding exposes typed request and observation operations only. It does not accept Docker command arguments, container identifiers, mounts, or arbitrary commands from callers.

Concurrent runs

The daemon runs task jobs (bosn run --task ...) from different checkouts in parallel, max(1, ncpu * 2) runner slots by default, each limited to 4 CPUs. Stack ensures run in their own lane, so they never wait behind long tasks. bosn jobs (or the bosn_jobs MCP tool) shows what is running, in which slot, with which containers and caches. A task that goes silent is torn down, and a daemon restart reaps what its predecessor left running. For stacks that drive the host Docker engine (act), a per-job proxy labels, limits, isolates and removes the job's containers, and maps cache volumes into act's job containers. See docs/runners.md.

The daemon starts on demand and exits after 10 idle minutes (BOSN_DAEMON_IDLE_EXIT_SECS, 0 to keep it), so the next command always runs the current release; containers and the registry survive the exit. Any command that reaches a daemon of another release warns bosn daemon/client mismatch on stderr.

bosn jobs                                  # what is running now
bosn daemon serve --state-dir "$HOME/.local/state/bosn" --runner-slots 8 --runner-cpus 4

MCP / Hermes

Run bosn mcp over stdio. A typical Hermes registration is:

mcp_servers:
  bosn:
    command: bosn
    args: [mcp]

Set BOSN_STATE_DIR if the default state directory is not appropriate. MCP tools use the same typed daemon operations as the CLI and Python client; long operations return durable job IDs.

Development

./install
./lint
./test

./install prepares Soldr and the Rust toolchain pinned by rust-toolchain.toml before installing the native package. Source builds use Soldr for both the CLI and Maturin's compiler calls. The declared Docker test and lint tasks build a wheel against a read-only checkout, with writable target, toolchain and environment volumes.

The Rust migration status, native manifest lifecycle boundary, and registry details are documented in docs/migration-rust.md, docs/rust-manifest-runtime.md, and docs/rust-registry.md. Daemon-owned task secrets (an opt-in GITHUB_TOKEN for act runs) are in docs/task-secrets.md; the read-only GitHub API proxy that keeps the token out of containers is in docs/github-api-proxy.md. Bosn runs its containers at low CPU priority so the desktop stays responsive; see docs/cpu-priority.md. Local CI on an isolated, daemon-owned engine (bosn ci run, with reports and stable exit codes for agents) is in docs/ci.md.

Before pushing this repository, run its gate from a clean, committed checkout:

uvx --from git+https://github.com/zackees/ci.yml@86b63937960d00655f7ef3752ef6f15b6b06f35b ci-lint local-gate run

The heavy lanes require Bosn 0.1.12 or later and replay the Rust checks and Linux test tier through act2 on isolated engines. The gate checks the executed source and required successful steps before stamping the commit. Unchanged lane inputs can reuse a recorded pass; compiler units are cached across runs.

PR verification refuses missing or stale proof. A trusted, attested PR can skip the mapped policy and Rust jobs, with audit sampling retained. Explicit ci-test/ci-full requests keep their Linux test-tier coverage; main pushes and release validation retain their remote checks.

If the gate rejects an old Bosn before submitting a run, check bosn --version and the executable selected by command -v bosn. The gate requires at least 0.1.12. Its uv run --no-project --isolated launchers avoid selecting a virtual environment in an ancestor directory: --no-project alone does not isolate the tooling environment. Make the supported executable available on PATH and rerun the gate; the rejected preflight produces no attestation.

Metadata

Release files for bosn 0.1.27

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Change of provenance

The repository or configuration that created these release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Built distributions (wheels)

Table of built distributions (wheels) for bosn 0.1.27
File Actions
bosn-0.1.27-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for bosn-0.1.27-cp310-abi3-win_amd64.whl
bosn-0.1.27-cp310-abi3-manylinux_2_39_x86_64.whl CPython 3.10 abi3 Linux glibc 2.39+ x86-64 Details for bosn-0.1.27-cp310-abi3-manylinux_2_39_x86_64.whl
bosn-0.1.27-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for bosn-0.1.27-cp310-abi3-macosx_11_0_arm64.whl
bosn-0.1.27-cp310-abi3-macosx_10_12_x86_64.whl CPython 3.10 abi3 macOS 10.12+ x86-64 Details for bosn-0.1.27-cp310-abi3-macosx_10_12_x86_64.whl

Total release size: 59.4 MB

Release files / bosn-0.1.27-cp310-abi3-win_amd64.whl

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL bosn-0.1.27-cp310-abi3-win_amd64.whl
Size 13.6 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
cb2eaea09d88f708a6fa08b919d072acd0b815b43db2e52c5555be8c11a46eb8
BLAKE2b-256 checksum
How to use checksums
720fb0d4a7b50010568464a863e616851e0860aeddd11817d598c4e3d4bed186
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / bosn-0.1.27-cp310-abi3-manylinux_2_39_x86_64.whl

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL bosn-0.1.27-cp310-abi3-manylinux_2_39_x86_64.whl
Size 19.7 MB
Tags CPython 3.10 Linux glibc 2.39+ x86-64 abi3
SHA-256 checksum
How to use checksums
f929ad4b63fc1c7d8eb04307994b3012c24b7b61ae1e9f0473448ed0908e1de4
BLAKE2b-256 checksum
How to use checksums
2b5320090b0604f236f3ec11d3592f26f1553058abe674d716845a14ba93f664
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / bosn-0.1.27-cp310-abi3-macosx_11_0_arm64.whl

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL bosn-0.1.27-cp310-abi3-macosx_11_0_arm64.whl
Size 12.8 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
878698d213316ad8407da1a539e8b7347faf0eea1cbd996686978a591191761d
BLAKE2b-256 checksum
How to use checksums
30e4b3a6b9473d36f21263a8756177d431f6a05d81e911ba5a430e5dbf5808e7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / bosn-0.1.27-cp310-abi3-macosx_10_12_x86_64.whl

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL bosn-0.1.27-cp310-abi3-macosx_10_12_x86_64.whl
Size 13.3 MB
Tags CPython 3.10 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
b3782b5e6ac602b5d9205560e9c4040e6c3f398a213cf499ce2d64b2e5e787e7
BLAKE2b-256 checksum
How to use checksums
d9f20c76ea5c037058bf1a73ed4ad839820f6e4f763e96316dd8697c7c1cf7a0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for bosn 0.1.27

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.

Change of provenance

The repository and configuration that created this release differ from a previous release.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Repository

Select from 4 files

Attestation for bosn-0.1.27-cp310-abi3-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

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.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page