README
¶
toolexec
Execution layer providing tool running, code orchestration, and runtime isolation for the ApertureStack tool framework.
Installation
go get github.com/jonwraymond/toolexec@latest
Packages
| Package | Description |
|---|---|
exec |
Unified facade combining discovery + execution |
run |
Core execution pipeline with validation and chaining |
code |
Code-based orchestration with tool access |
runtime |
Sandbox runtimes and security profiles |
backend |
Backend registry and resolution |
Quick Start
import (
"github.com/jonwraymond/toolexec/exec"
"github.com/jonwraymond/tooldiscovery/index"
"github.com/jonwraymond/tooldiscovery/tooldoc"
)
idx := index.NewInMemoryIndex()
docs := tooldoc.NewInMemoryStore(tooldoc.StoreOptions{Index: idx})
executor, err := exec.New(exec.Options{
Index: idx,
Docs: docs,
LocalHandlers: map[string]exec.Handler{
"math-add": func(ctx context.Context, args map[string]any) (any, error) {
a, b := args["a"].(float64), args["b"].(float64)
return a + b, nil
},
},
})
result, err := executor.RunTool(ctx, "math:add", map[string]any{"a": 5, "b": 3})
fmt.Println(result.Value) // 8
Features
- Unified Facade: Single API for discovery, execution, and documentation
- Schema Validation: Input/output validated against tool schemas
- Backend Abstraction: Local, provider, or MCP server execution
- Tool Chaining: Sequential chains with explicit data passing
- Runtime Isolation: Docker, gVisor, and WASM runtimes
Documentation
- MkDocs site: https://jonwraymond.github.io/toolexec/
- Schemas and contracts
- Architecture
- Design notes
- User journey
- Examples
- Contributing
Examples
go run ./examples/basic
go run ./examples/chain
go run ./examples/discovery
go run ./examples/streaming
go run ./examples/runtime
go run ./examples/full
License
MIT License - see LICENSE
Directories
¶
| Path | Synopsis |
|---|---|
|
Package backend provides tool execution backend abstractions and registry.
|
Package backend provides tool execution backend abstractions and registry. |
|
Package toolcode provides the code-mode orchestration layer for executing constrained code snippets with access to metatool helper functions.
|
Package toolcode provides the code-mode orchestration layer for executing constrained code snippets with access to metatool helper functions. |
|
examples
|
|
|
basic
command
Package main demonstrates basic tool execution with the exec facade.
|
Package main demonstrates basic tool execution with the exec facade. |
|
chain
command
Package main demonstrates sequential tool chaining with the exec facade.
|
Package main demonstrates sequential tool chaining with the exec facade. |
|
discovery
command
Package main demonstrates the search → execute workflow.
|
Package main demonstrates the search → execute workflow. |
|
full
command
Package main demonstrates complete integration across all toolexec layers.
|
Package main demonstrates complete integration across all toolexec layers. |
|
runtime
command
Package main demonstrates custom runtime configuration.
|
Package main demonstrates custom runtime configuration. |
|
streaming
command
Package main demonstrates streaming tool execution.
|
Package main demonstrates streaming tool execution. |
|
Package exec provides a unified facade for tool execution in the toolexec ecosystem.
|
Package exec provides a unified facade for tool execution in the toolexec ecosystem. |
|
Package run is the execution layer for MCP-style tools defined in the model package and resolved via toolindex.
|
Package run is the execution layer for MCP-style tools defined in the model package and resolved via toolindex. |
|
Package runtime provides execution runtime and isolation boundaries for code-oriented orchestration.
|
Package runtime provides execution runtime and isolation boundaries for code-oriented orchestration. |
|
backend/containerd
Package containerd provides a backend that executes code via containerd.
|
Package containerd provides a backend that executes code via containerd. |
|
backend/docker
Package docker provides a backend that executes code in Docker containers with configurable security profiles and resource limits.
|
Package docker provides a backend that executes code in Docker containers with configurable security profiles and resource limits. |
|
backend/firecracker
Package firecracker provides a backend that executes code in Firecracker microVMs.
|
Package firecracker provides a backend that executes code in Firecracker microVMs. |
|
backend/gvisor
Package gvisor provides a backend that executes code with gVisor (runsc).
|
Package gvisor provides a backend that executes code with gVisor (runsc). |
|
backend/kata
Package kata provides a backend that executes code in Kata Containers.
|
Package kata provides a backend that executes code in Kata Containers. |
|
backend/kubernetes
Package kubernetes provides a backend that executes code in Kubernetes pods/jobs.
|
Package kubernetes provides a backend that executes code in Kubernetes pods/jobs. |
|
backend/remote
Package remote provides a backend that executes code on a remote runtime service.
|
Package remote provides a backend that executes code on a remote runtime service. |
|
backend/temporal
Package temporal provides a backend that treats snippet execution as a Temporal workflow/activity.
|
Package temporal provides a backend that treats snippet execution as a Temporal workflow/activity. |
|
backend/unsafe
Package unsafe provides a backend that executes code directly on the host.
|
Package unsafe provides a backend that executes code directly on the host. |
|
backend/wasm
Package wasm provides a backend that executes code compiled to WebAssembly.
|
Package wasm provides a backend that executes code compiled to WebAssembly. |
|
gateway/direct
Package direct provides a gateway that implements ToolGateway by directly delegating to toolindex, tooldocs, and toolrun components.
|
Package direct provides a gateway that implements ToolGateway by directly delegating to toolindex, tooldocs, and toolrun components. |
|
gateway/proxy
Package proxy provides a gateway that implements ToolGateway by serializing requests over a connection (for cross-process/container communication).
|
Package proxy provides a gateway that implements ToolGateway by serializing requests over a connection (for cross-process/container communication). |
|
toolcodeengine
Package toolcodeengine provides an adapter that implements code.Engine using runtime.Runtime for execution.
|
Package toolcodeengine provides an adapter that implements code.Engine using runtime.Runtime for execution. |
Click to show internal directories.
Click to hide internal directories.