Skip to content
ContractSpec
Start here

Package manual · integrations

·Agents, execution and context

integration.agent-sandbox

Deny-by-default Docker and development sandbox adapters for @lssm-tech/lib.ai-agent

integrationsintegrationv2.0.5experimentalservernode
@lssm-tech/integration.agent-sandbox
bun add @lssm-tech/integration.agent-sandbox
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Production Docker and development-fixture implementations of @lssm-tech/lib.ai-agent sandbox ports.

Scope

  • DockerAgentSandbox creates one OS-contained container per workspace with a read-only root, private tmpfs workspace, dropped capabilities, no-new-privileges, non-root execution, and explicit memory/PID/output/time limits.
  • Docker networking is deny-all by default. Each allowlisted TCP target is DNS-pinned before attachment and exposed through a dedicated restricted sidecar on an internal-only network, preventing direct DNS/IP bypass.
  • Commands, read/write roots, network targets, and secrets are deny-by-default. Secrets are resolved by reference for one command, redacted from output, and rejected from reads or artifact extraction if a command persisted them.
  • Extracts immutable artifacts through @lssm-tech/lib.files.
  • LocalDevelopmentSandbox remains an honest policy/redaction fixture and rejects isolation, egress, and quota claims it cannot prove.

Containment conformance

bun test src/docker-agent-sandbox.test.ts runs the adapter in an external fixture against a live Docker daemon. It covers command denial, traversal and symlink attacks, DNS/IP egress bypass, positive network allowlisting, child-process fanout, memory/CPU/output limits, cancellation, teardown, secret scrubbing, and artifact integrity.

UDP allowlisting is rejected rather than silently weakened.

Docker teardown now verifies container and network absence through inventory. A failed removal acknowledgement is recoverable only when absence is confirmed. Unconfirmed teardown throws and retains the workspace handle for retry. This is removal verification, not durable restart discovery or executor fencing.

Docker CLI operations default to a five-minute deadline. Sandbox commands use the policy timeout plus 30 seconds for transport. Deadline and input failures kill the CLI client and report an unknown external outcome; they neither retry the command nor prove the daemon-side process stopped. Reconcile the workspace before resuming effects.

Network and proxy names are tracked before allocation so lost creation acknowledgements retain cleanup targets. Container creation failures also enter cleanup. This process-local tracking does not yet provide restart discovery. Containment conformance fails on teardown errors instead of suppressing them.

Relationships

THIS PACKAGEintegration.agent-sandbox18 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

2 declarations

Declared capabilities

Integration Agent Sandbox

Deny-by-default Docker and development sandbox adapters for @lssm-tech/lib.ai-agent

Scripts

  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • publish:pkg:canarybun publish:pkg --tag canary
  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lintbun lint:fix
  • lint:fixnode ../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .
  • lint:checknode ../../../scripts/biome.cjs check .
  • testbun test
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit