For Developers

Build on spore.host

The truffle and spawn packages are clean, importable Go libraries. Use them in your own tools, scripts, or services — no CLI subprocess calls required. The MCP server ships as a ready-to-use integration for AI assistants. Python SDK and REST API are on the roadmap.

Available now

Go library

Import truffle and spawn directly into your Go project. No subprocesses, no shell wrappers — just Go packages with clean APIs.

truffle — capacity search

Search instance types, fetch Spot prices, check service quotas.

import (
    truffleaws "github.com/spore-host/spore-host/truffle/pkg/aws"
    "github.com/spore-host/spore-host/truffle/pkg/find"
    "github.com/spore-host/spore-host/truffle/pkg/quotas"
)

// Natural language search
pq, _ := find.ParseQuery("nvidia h100 8gpu")
criteria, _ := pq.BuildCriteria()

client, _ := truffleaws.NewClient(ctx)
results, _ := client.SearchInstanceTypes(ctx,
    []string{"us-east-1"},
    criteria.InstanceTypePattern,
    criteria.FilterOptions,
)

// Spot prices
prices, _ := client.GetSpotPricing(ctx, results,
    truffleaws.SpotOptions{ShowSavings: true},
)

// Quota check
qc, _ := quotas.NewClient(ctx)
info, _ := qc.GetQuotas(ctx, "us-east-1")
ok, msg := qc.CanLaunch("p4d.24xlarge", 96, info, false)

spawn — instance management

List, launch, stop, terminate, and update instances programmatically.

import spawnclient "github.com/spore-host/spore-host/spawn/pkg/aws"

client, _ := spawnclient.NewClient(ctx)

// List running instances (all regions)
instances, _ := client.ListInstances(ctx, "", "running")

// Launch
result, _ := client.Launch(ctx, spawnclient.LaunchConfig{
    Name:         "ml-job",
    InstanceType: "p4d.24xlarge",
    Region:       "us-east-1",
    TTL:          "12h",
    OnComplete:   "terminate",
})

// Stop / terminate
client.StopInstance(ctx, result.Region, result.InstanceID, false)
client.Terminate(ctx, result.Region, result.InstanceID)

// Extend TTL
client.UpdateInstanceTags(ctx, result.Region, result.InstanceID,
    map[string]string{"spawn:ttl": "24h"},
)
truffle on pkg.go.dev → spawn on pkg.go.dev →

Available now

MCP server

spore-host-mcp exposes truffle and spawn as MCP tools for Claude Desktop, Cursor, and any MCP-compatible AI assistant. It uses the same Go packages above — no API keys, no extra auth, just your existing AWS credentials.

Install

brew install scttfrdmn/tap/spore-host-mcp

Configure (Claude Desktop)

// ~/.claude/claude_desktop_config.json
{
  "mcpServers": {
    "spore-host": {
      "command": "/usr/local/bin/spore-host-mcp"
    }
  }
}

Available tools

  • truffle_find — natural language instance search
  • truffle_spot_prices — current Spot prices by AZ
  • truffle_quota_check — can you launch this type?
  • spawn_list — list running instances
  • spawn_status — detailed status by name or ID
  • spawn_stop — stop or hibernate
  • spawn_terminate — terminate permanently
  • spawn_extend — extend TTL
MCP server source →

Real-world example

prism uses spore.host as a library

prism is a research workspace platform that imports spawn and truffle directly to manage RStudio and Jupyter environments on behalf of university researchers. It uses the same cross-account IAM pattern and lifecycle infrastructure as spore.host — without maintaining its own EC2 tooling.

View prism on GitHub →

Available now

Python SDK

Use spore.host from Jupyter notebooks, marimo, training scripts, and data pipelines. Find instances, launch compute, and manage the full lifecycle in Python.

Install

pip install spore-host
# with notebook extras
pip install "spore-host[jupyter]"

Launch and manage

import spore

# Launch an instance
inst = spore.spawn.launch(
    "c8a.2xlarge",
    name="my-analysis",
    ttl="12h",
    idle_timeout="30m",
)
inst.wait_running()

# Find instances
results = spore.truffle.find("amd epyc genoa", region="us-east-1")
for r in results:
    print(r.instance_type, f"${r.on_demand_price:.4f}/hr")

# Manage running instances
instances = spore.spawn.list()
inst = spore.spawn.status("sim-run-42")
inst.extend("2h")
inst.wait("terminated", on_status=lambda i: print(i.state))

REST API

A language-agnostic HTTP API over truffle and spawn — the foundation for the Python SDK and future R/Julia bindings.

GET  /v1/instances              # list
POST /v1/instances              # launch
GET  /v1/instances/{id}         # status
POST /v1/instances/{id}/stop
POST /v1/instances/{id}/start
POST /v1/instances/{id}/extend
POST /v1/instances/{id}/terminate
GET  /v1/search?q=nvidia+h100
GET  /v1/spot?type=p4d.24xlarge
GET  /v1/quota?type=p4d.24xlarge®ion=us-east-1

Auth: X-API-Key header. Keys via spawn api-key create.