Built-in Provider examples

The runnable examples/environment-provider project uses a13n-harness directly, without an Agent or model credentials. See Cloud Providers for the cloud backends.

InstallCopy Anchor Link

cd examples/environment-provider
uv sync --locked

External applications can install the released a13n-harness distribution.

Direct LocalCopy Anchor Link

uv run environment-provider-example direct_local --workspace /absolute/path/to/workspace

The Host creates the directory, constructs a connector, opens an execution, writes and reads /provider-example.txt, then closes the execution. The directory remains. Direct Local shares the Host account and does not provide operating-system isolation.

Local EnvdCopy Anchor Link

uv run environment-provider-example local_envd --executable /absolute/path/to/a13n-envd

Without --executable, resolution checks A13N_ENVD_EXECUTABLE and then PATH. The Host owns a LocalEnvdProviderRuntime. Each connector opening creates an independent fixed-cwd Session; execution close releases only that Session. The example closes the Host runtime afterward and preserves the workspace. See Operate a13n-envd.

DockerCopy Anchor Link

# Repository root
make image-sandbox
cd examples/environment-provider
uv run environment-provider-example docker

The default image is a13n-sandbox:local; use --image IMAGE to select another compatible image. The Host explicitly creates a container through a management provider and keeps the returned state. A connector built from that state opens two independent executions: one writes a file, the other reads it. Closing either execution preserves the container. The Host finally calls provider destroy() explicitly.

A production Host publishes management state before opening execution. If a management operation fails or is cancelled after allocation, use observed_environment_state(error, fallback) to recover and publish the observed reference. Execution has no management-state writeback. A stopped or missing target fails opening without resume or replacement.

Use with HarnessCopy Anchor Link

Supply the connector through a Host source:

Use the Host-owned PreparedSource implementation from the Harness environment guide. It returns the prepared connector on first use.

result = await executable.run("Inspect the workspace", environment=PreparedSource(connector))

Harness opens and closes a fresh execution for each used mount. Add DynamicEnvironmentCapability when the model should receive Environment tools. For a complete offline application, see the Agent application example.

HTTP and WebSocket EnvdCopy Anchor Link

The Remote Envd guide covers existing daemons and a Host WebSocket handler. The demo explicitly starts and cleans up its own daemon:

uv run environment-provider-example remote_envd_demo \
  --transport http --executable ../../target/debug/a13n-envd
uv run environment-provider-example remote_envd_demo \
  --transport websocket --executable ../../target/debug/a13n-envd

Both open separate Sessions through the same connector. Execution close preserves the daemon; only the demo's operator code stops it.

ValidateCopy Anchor Link

From the repository root, make examples-check-all lints, type-checks, tests, and builds the independent projects. The offline smoke path uses Direct Local; Envd and Docker require their respective runtimes.