Example Projects Using OpenWork: A Complete Guide to the Rust Microsandbox

OpenWork ships with a production-ready Rust microsandbox example in the examples/ directory that demonstrates bootstrapping workspaces, authenticated API calls, and the full platform architecture.

The different-ai/openwork repository includes a comprehensive example project designed to teach developers how the platform’s components interact in real-world scenarios. Located at examples/microsandbox-openwork-rust/, this ready-to-run Rust application serves as the canonical reference for integrating OpenWork’s microsandbox capabilities, token-based authentication, and MCP (Model Context Protocol) endpoints into your own tooling.

What Is the OpenWork Microsandbox Example?

The primary example project is a Rust microsandbox that provides an end-to-end demonstration of OpenWork’s core functionality. Rather than isolated code snippets, this is a fully executable application that spins up the OpenWork server inside a lightweight Docker container and exercises the complete workspace lifecycle.

The example performs three critical operations:

1. Bootstraps the microsandbox using the OpenWork SDK to initialize the server environment
2. Manages workspace lifecycles by creating workspaces, checking health endpoints, and making authenticated calls to /workspaces and /opencode/session
3. Handles persistence and security by mounting /workspace and /data directories from the host and managing OPENWORK_TOKEN and OPENWORK_HOST_TOKEN authentication

Architecture Demonstrated in the Example

Running the example project reveals how OpenWork’s five-layer architecture functions in practice:

MCP Server Layer

The example runs the MCP server endpoint at /w/:workspaceId/opencode/session, demonstrating how agents invoke remote procedures through OpenWork Desktop. In src/main.rs, the code initiates OpenCode sessions using the same REST contracts that production skills utilize.

Control Plane (Den) Integration

While the microsandbox example focuses on local execution, its API calls mirror the REST contracts exposed by the OpenWork Den—the central governance layer for teams and model providers. The authentication patterns and endpoint structures you implement here transfer directly to cloud deployments.

Plugin and Skill System

The example creates an OpenCode session using the same invocation patterns that OpenWork plugins employ. This demonstrates how the opencode.json configuration (documented in packages/openwork-bootstrap/README.md) enables AI agents to extend functionality through callable skills.

Micro-Sandbox Environment

The entire example centers on the Docker-based microsandbox image, providing an isolated, reproducible environment for OpenWork services. The code handles container lifecycle commands including startup, health monitoring, and graceful shutdown.

Authentication and Token Management

Environment variables OPENWORK_TOKEN (client shared secret) and OPENWORK_HOST_TOKEN (host-admin secret) secure access to endpoints. The example tests both authenticated and unauthenticated scenarios, showing how to protect sensitive operations while allowing public health checks.

Running the OpenWork Example Project

Clone the repository and execute the microsandbox example using Cargo:

# Clone the repository

git clone https://github.com/different-ai/openwork.git
cd openwork
git checkout dev

# Build and run the Rust microsandbox example

cargo run --manifest-path examples/microsandbox-openwork-rust/Cargo.toml

Configuring Environment Overrides

For custom Docker images or persistent workspace directories, export these variables before running:

OPENWORK_MICROSANDBOX_IMAGE=ghcr.io/example/openwork-microsandbox:dev \
OPENWORK_MICROSANDBOX_WORKSPACE_DIR="$PWD/examples/microsandbox-openwork-rust/.state/demo/workspace" \
OPENWORK_MICROSANDBOX_DATA_DIR="$PWD/examples/microsandbox-openwork-rust/.state/demo/data" \
OPENWORK_TOKEN=my-shared-secret \
OPENWORK_HOST_TOKEN=my-owner-secret \
cargo run --manifest-path examples/microsandbox-openwork-rust/Cargo.toml

Running Integration Tests

Execute the end-to-end smoke test (ignored by default in the test suite) to verify the complete workflow:

OPENWORK_MICROSANDBOX_IMAGE=ttl.sh/openwork-microsandbox-11559:1d \
cargo test --manifest-path examples/microsandbox-openwork-rust/Cargo.toml -- --ignored --nocapture

Key Source Files and Implementation Details

Understanding these specific files accelerates your development:

• examples/microsandbox-openwork-rust/src/main.rs – Contains the primary implementation that launches the microsandbox container, performs health checks at the /health endpoint, and executes authenticated API calls to create workspaces and OpenCode sessions.

• examples/microsandbox-openwork-rust/src/bin/debug_env.rs – A utility binary that prints resolved environment variables, essential for debugging token configurations and directory mount points before running the main application.

• examples/microsandbox-openwork-rust/README.md – Documents all supported environment variables, Docker image requirements, and step-by-step execution instructions.

• packages/openwork-bootstrap/README.md – Shows how to configure opencode.json to add OpenWork capabilities to any AI agent, using the same initialization principles demonstrated in the microsandbox example.

Summary

The OpenWork repository provides a complete reference implementation for developers building AI-powered tooling:

• The Rust microsandbox at examples/microsandbox-openwork-rust/ demonstrates the full OpenWork architecture from container startup to authenticated API usage
• Key source files including src/main.rs and src/bin/debug_env.rs provide copy-pasteable patterns for workspace lifecycle management
• Environment variable configuration supports custom Docker images, persistent storage paths, and dual-token authentication schemes
• Integration tests validate the end-to-end workflow using cargo test with ignored flags

Frequently Asked Questions

Where are the example projects located in the OpenWork repository?

All example projects reside in the examples/ directory at the repository root. The primary reference implementation is examples/microsandbox-openwork-rust/, which contains a complete Cargo project with its own Cargo.toml, source code in src/, and comprehensive documentation.

Do I need OpenWork Desktop to run the example projects?

No. The microsandbox example runs independently using Docker and simulates the OpenWork server environment. While the example mirrors the MCP endpoints that OpenWork Desktop provides, it creates a self-contained testing environment that does not require the desktop application installed.

How do the authentication tokens work in the example?

The example uses two token types: OPENWORK_TOKEN for client-side shared secrets that grant API access, and OPENWORK_HOST_TOKEN for administrative operations. These map to the authentication system implemented in the OpenWork Den (control plane), allowing you to test protected endpoints versus public health checks within the same codebase.

Can I extend the microsandbox example for my own OpenWork integration?

Yes. The src/main.rs file provides patterns for workspace creation, session management, and Docker lifecycle control that translate directly to TypeScript, Python, or other language implementations. The packages/openwork-bootstrap/README.md demonstrates how these same principles apply when adding OpenWork capabilities to existing AI agents through configuration files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}