Skip to content

Spin Framework

Spin is a WebAssembly framework for building serverless applications. DeepFabric uses Spin to run tool execution in isolated sandboxes.

Getting Started

There are two ways to run the Spin service:

Method Best For
Docker Using the service as-is, quick setup, production
Local Install Developing components, customizing tools, contributing

The fastest way to get started. No installation required:

docker run -d -p 3000:3000 ghcr.io/always-further/deepfabric/tools-sdk:latest

With a custom port:

docker run -d -p 8080:3000 ghcr.io/always-further/deepfabric/tools-sdk:latest

Verify it's running:

curl http://localhost:3000/vfs/health
# {"status":"healthy","components":["vfs"]}

Install Spin if you plan to develop or customize components:

macOS: 

brew install fermyon/tap/spin

Linux: 

curl -fsSL https://developer.fermyon.com/downloads/install.sh | bash
sudo mv spin /usr/local/bin/

Verify installation: 

spin --version

Build and run: 

cd tools-sdk
spin build
spin up

With a custom port: 

spin up --listen 0.0.0.0:8080

Background mode: 

spin up --background

The service starts at http://localhost:3000.

Building Components

Only needed for local development

Skip this section if you're using Docker.

Navigate to the tools-sdk directory and build:

cd tools-sdk
spin build

This compiles all Rust components to WebAssembly. Build output:

  • components/vfs/target/wasm32-wasip1/release/vfs.wasm
  • components/mock/target/wasm32-wasip1/release/mock.wasm

Endpoints

Endpoint Method Description
/vfs/execute POST Execute VFS tool
/vfs/health GET Health check
/vfs/components GET List VFS tools
/vfs/session/{id} DELETE Clean up session
/mock/load-schema POST Load tool definitions
/mock/execute POST Execute mock tool
/mock/list-tools GET List loaded tools

Testing

Verify the service is running:

Health check
curl http://localhost:3000/vfs/health
# {"status":"healthy","components":["vfs"]}

Execute a tool:

Write a file
curl -X POST http://localhost:3000/vfs/execute \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "test-123",
    "tool": "write_file",
    "args": {"file_path": "hello.txt", "content": "Hello, World!"}
  }'
# {"success":true,"result":"Successfully wrote 13 bytes to hello.txt"}

Configuration

The spin.toml file defines components and routes:

spin.toml
spin_manifest_version = 2

[application]
name = "deepfabric-tools"
version = "0.1.0"

[[trigger.http]]
route = "/vfs/..."
component = "vfs"

[component.vfs]
source = "components/vfs/target/wasm32-wasip1/release/vfs.wasm"
key_value_stores = ["default"]