DriftGard Agent Runtime

DriftGard Agent Runtime is an optional execution environment for agents, with OpenShell containment and explicit DriftGard tool, model and final-response gates. The current source includes local operation and customer-owned AWS, GCP and Azure deployment recipes. Existing DG API, SDK, connector and observer integrations remain available.

This checkout is a private development candidate, not an approved production release. The Drop 12 register tracks current security, compatibility and release work. The soak is deferred at the owner's request. Historical Drop 1 signatures and cloud development tests do not qualify changed source automatically.

Start with Understanding DG Runtime for a plain-language explanation of the components, execution flow and current limits. Then see the current capability and support matrix and guided setup. The local demo below is a synthetic containment check. Connected MCP/model/delivery commands and cloud recipes are separate workflows; arbitrary local functions are not intercepted automatically.

Install the CLI for guided setup

The CLI is distributed as an explicitly labelled npm development preview. With Node.js 22 or newer, install the pinned preview in your user directory from any terminal folder:

npm install --ignore-scripts --omit=dev --prefix "$HOME/.local/share/driftgard-cli" @driftgard/[email protected]
"$HOME/.local/share/driftgard-cli/node_modules/.bin/dg-runtime" --version
"$HOME/.local/share/driftgard-cli/node_modules/.bin/dg-runtime" --help

This installs the CLI in your user directory, without administrator access or a source checkout. It does not start an agent, install the OpenShell binaries or deploy resources. Follow the project wizard to import enrollment, review tools and verify your connection. Use its project-specific private directory.

The npm package includes the launcher and its supporting files only, excluding local build artifacts, credentials and runtime state. It does not turn the development manifest into a signed production release. The npm release uses the preview channel, not latest. It does not certify sandbox artifacts or cloud deployments as production ready; the existing release qualification controls remain separate.

Try it locally from source

Prerequisites: Node.js 22+, Docker running Linux containers, internet access for release/image downloads. Current host targets: macOS Apple Silicon and native Linux x86-64/ARM64 (glibc 2.28+). See validation status before treating a target as tested. Remote Docker engines and Windows are unsupported.

From this repository:

node --version
node bin/dg-runtime.cjs init
node bin/dg-runtime.cjs install
node bin/dg-runtime.cjs doctor
node bin/dg-runtime.cjs start
node bin/dg-runtime.cjs demo
node bin/dg-runtime.cjs stop

Each command outputs JSON. start additionally reports phase changes to stderr. demo must prove an allowed synthetic request, middleware modification and a denied path without that path reaching the mock service. A timeout or connection failure is a failed test, not evidence that policy denied a request.

One active runtime is supported per state directory. The example has one serial worker; concurrent demo requests are rejected. start is idempotent when ready. Use status before retrying a slow start. Use stop after a startup error. After a killed launcher, start performs scoped recovery; recover is also available explicitly.

The default state directory is ~/.local/share/driftgard-runtime (0700). Set DG_RUNTIME_HOME to a dedicated directory to isolate another installation. runtime.json configures local ports; use different ports for multiple runtimes. Do not put keys in it: cloud credentials and unknown configuration fields are rejected. uninstall removes this installation's state and example image tag after stop; it retains the repository and shared Docker image cache.

node bin/dg-runtime.cjs status
# If the launcher crashed: node bin/dg-runtime.cjs recover
node bin/dg-runtime.cjs uninstall

What is actually enforced

The OpenShell supervisor is trusted infrastructure outside the workload. It mediates permitted network traffic. The workload gets an exact host, port, HTTP method, path and executable allowlist. No automatic provider discovery, host workspace upload, Docker socket or model credentials are given to it. Gateway access uses mutual TLS. The launcher uses its own OpenShell configuration and disables upstream telemetry; it does not install a global service.

The fixed openshell/regex middleware is used only to prove the middleware path with a synthetic marker. It is not DriftGard, comprehensive DLP, or a production security rule. The mock service never transfers money. This workload is a script, not an autonomous model-driven agent.

The local administrator and Docker daemon are trusted. This is not protection against an administrator with host or Docker access. The init/start/demo path remains a synthetic foundation demo. Connected MCP, model and final-delivery gates are separate opt-in commands documented below. A dg_connected: false foundation status is intentional; it cannot silently fall back from cloud mode. Production deployment qualification remains separate.

Development and release gates

Local tests require Node 22+ and Python 3.9+; sandbox acceptance also needs Docker.

npm test
npm run check
npm run test:integration
# With verified Syft 1.54.0 and Grype 0.119.0 installed:
npm run security:scan

For an exact cloud API or workload image, use the separate cloud image scan procedure. It retains unsuppressed evidence and does not qualify the worker OS or approve a release.

Integration tests download pinned artifacts, create local Docker resources, run synthetic requests and clean up their own runtime. They do not use paid APIs. Failure retains diagnostics and reports their path. No npm dependencies are required. Tests include port conflicts, rejected unauthenticated gateway access, concurrent requests, launcher/gateway SIGKILL and preservation of unrelated containers and volumes. The package is private to prevent accidental publication.

• Offline policy analysis — evaluate a saved CP locally; no live execution permission.
• Architecture and adapter contracts
• Drop 2 registration and connection check
• Drop 2 generic MCP execution gate and limits
• Drop 3 action cancellation and receipt recovery
• Supported scope and validation
• Recovery
• Security boundaries
• Dependency and license inventory
• Pinned release manifest
• Security scan and release blockers
• Security rebuilds and local review bundles
• Latest candidate validation evidence
• Final Linux ARM64 tests and deferred 24-hour soaks
• Historical candidate validation
• Production acceptance and signed release procedure
• Portable release review packet
• Distribution, signing and approved response targets

This repository is prepared for an open-source release but has not been published, security-certified or approved for production use.

Explicit host-reported business outcomes: Drop 6 contract.

Final application JSON delivery: Drop 6 contract.

Coding and business-agent recipes, custom API import, and capture ownership: Drop 7 guide.

Customer-hosted asynchronous AWS jobs, guided deployment and recovery: Drop 8 AWS guide and qualification status.

Credential rotation, durable receipt recovery, retention and enterprise pilot operations: Drop 9 operations and acceptance evidence.

Customer-hosted GCP deployment (qualified development preview): Drop 10 GCP guide, acceptance evidence and API image security assessment.

Customer-hosted Azure deployment (qualified development preview): Drop 11 Azure guide, acceptance evidence and API image security assessment. The Azure profile remains a development candidate pending the separate production release gates, including the deferred soak tests.

Drop 12 release preparation: the readiness audit consolidates remaining work across all drops. The owner selected a 30-minute soak for step 4, followed by the step 5 release review. Historical long-soak requirements and the current checker are not silently rewritten; the explicit acceptance-profile update is tracked in the audit before testing. No production release is approved.