The Core Idea: Execution Environments That Branch

Containers are great for packaging, but they do not branch state. ConTree is built around a different mental model: treat every execution as a checkpoint, then branch from any checkpoint like Git. This matters for agents and tooling that need to explore many options, compare results, and keep working states intact.

ConTree gives you:

  • VM-level isolation for untrusted code execution.
  • Git-like branching of execution state.
  • Instant rollback to any checkpoint.
  • Parallel path exploration.
  • Built-in execution history.
  • OCI image support.

That combination enables workflows like speculative execution (run two approaches from the same checkpoint) and tree-search style agents (expand, evaluate, backtrack, and continue).

Safety Is a First-Class Feature

ConTree uses microVMs with separate kernels per execution, which provides hardware-level isolation. This is a stronger boundary than container namespace isolation, and it is designed for running untrusted code. Executions are batch-style, with no inbound network access; outbound access may depend on deployment configuration.

A Few Concepts to Keep Handy

ConTree’s API maps cleanly to a small set of concepts:

  • Image: An immutable filesystem snapshot. Base images come from OCI registries, and each execution can produce a new image.
  • Instance: A single command execution request. It runs in a microVM and returns stdout/stderr plus an optional new image.
  • Operation: An async task (instance execution or image import). It has states like pending, running, done, failed, and cancelled.
  • Disposable: A mode where execution does not create a new image. Use it when you only need output.
  • Tag: A human-readable alias for an image UUID, similar to a Git tag.
  • Inspect: Browse an image’s filesystem via API without executing anything.
  • Branch: Start a new execution from any existing image to create a new state.
  • Rollback: Jump back to any prior image by UUID or tag.

API Surface: Small, Composable, Explicit

ConTree’s API is intentionally compact. You can build most workflows with a handful of endpoints:

  • POST /v1/images/import to import base images from OCI registries.
  • GET /v1/images to list images.
  • POST /v1/images/{image}/tag to tag images for easy reuse.
  • POST /v1/instances to execute commands in a microVM.
  • GET /v1/operations and GET /v1/operations/{operation} to track async work.
  • GET /v1/inspect/{uuid}/list and GET /v1/inspect/{uuid}/download to browse and fetch files without execution.
  • POST /v1/files to upload local files into the execution context.

That minimal surface is deliberate: when every execution yields a new image, you can compose safe, branchable workflows without special-case APIs.

Why This Matters for Agents

Agents need to try multiple paths, compare results, and recover quickly. ConTree’s branching model makes those workflows natural and fast:

  • Fork a checkpoint for each hypothesis.
  • Run branches in parallel.
  • Inspect artifacts via the API.
  • Keep the best branch, discard the rest.

That is the difference between sequential trial-and-error and true parallel exploration.

What’s Next

If you want the fastest mental model: treat ConTree as Git for execution environments. Start from a base image, run commands, branch when you need to explore, and roll back when you need to recover. The API is built to make this simple and explicit.