Runtime Environments

// The NodeRuntime interface abstracts execution environment
type NodeRuntime interface {
    Start(ctx context.Context) error
    InitiateStop(ctx context.Context) error
    WaitForStopped(ctx context.Context) error
    Restart(ctx context.Context) error
    IsHealthy(ctx context.Context) (bool, error)
    // ...
}

~/.tmpnet/networks/[timestamp]/
├── config.json           # Network configuration
├── genesis.json          # Genesis file
├── network.env           # Shell environment
├── metrics.txt           # Grafana dashboard link
├── NodeID-7Xhw2.../
│   ├── config.json       # Node runtime config
│   ├── flags.json        # Node flags
│   ├── process.json      # PID, URI, staking address
│   ├── db/               # Node database
│   ├── logs/main.log     # Node logs
│   └── plugins/          # VM plugins

~/.tmpnet/networks/latest -> [timestamp]/  # Symlink created only by tmpnetctl start-network

type ProcessRuntimeConfig struct {
    // Path to avalanchego binary (required)
    AvalancheGoPath string

    // Directory containing VM plugin binaries
    PluginDir string

    // Reuse the same API port when restarting nodes
    ReuseDynamicPorts bool
}

# Clone and build AvalancheGo
git clone https://github.com/ava-labs/avalanchego.git
cd avalanchego
./scripts/build.sh

# The binary is now at ./build/avalanchego

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/ava-labs/avalanchego/tests/fixture/tmpnet"
)

func main() {
    ctx := context.Background()

    // Create network with local process runtime
    network := &tmpnet.Network{
        DefaultRuntimeConfig: tmpnet.NodeRuntimeConfig{
            Process: &tmpnet.ProcessRuntimeConfig{
                // Use absolute path to your avalanchego binary
                AvalancheGoPath:   os.Getenv("HOME") + "/avalanchego/build/avalanchego",
                PluginDir:         os.Getenv("HOME") + "/.avalanchego/plugins",
                ReuseDynamicPorts: true,
            },
        },
        Nodes: tmpnet.NewNodesOrPanic(5),
    }

    // Bootstrap the network
    if err := tmpnet.BootstrapNewNetwork(
        ctx,
        logging.NoLog{}, // any logging.Logger (github.com/ava-labs/avalanchego/utils/logging)
        network,
        "", // Use the default root network directory (~/.tmpnet/networks)
    ); err != nil {
        log.Fatal(err)
    }
    defer network.Stop(ctx)

    // Get node URIs for interaction
    for _, node := range network.Nodes {
        fmt.Printf("Node %s: %s\n", node.NodeID, node.URI)
    }
}

# Verify kubectl is configured
kubectl cluster-info
kubectl auth can-i create pods --namespace=default

type KubeRuntimeConfig struct {
    ConfigPath             string  // kubeconfig path (default: ~/.kube/config)
    ConfigContext          string  // kubeconfig context to use
    Namespace              string  // target namespace
    Image                  string  // avalanchego container image
    VolumeSizeGB           uint    // PVC size in GB (minimum 2)
    UseExclusiveScheduling bool    // one pod per k8s node
    SchedulingLabelKey     string  // anti-affinity label key
    SchedulingLabelValue   string  // anti-affinity label value
    IngressHost            string  // e.g., "localhost:30791"
    IngressSecret          string  // TLS secret for HTTPS
}

# Use the provided script
./scripts/start_kind_cluster.sh

# Creates:
# - KIND cluster named "kind" (kubeconfig context "kind-kind")
# - Namespace "tmpnet" and context "kind-kind-tmpnet" for the tmpnet service account
# - Traefik ingress controller on NodePort 30791
# - Port mapping to localhost:30791

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/ava-labs/avalanchego/tests/fixture/tmpnet"
)

func main() {
    ctx := context.Background()

    // Configure Kubernetes runtime
    network := &tmpnet.Network{
        DefaultRuntimeConfig: tmpnet.NodeRuntimeConfig{
            Kube: &tmpnet.KubeRuntimeConfig{
                ConfigContext: "kind-kind",
                Namespace:     "tmpnet-demo",
                Image:         "avaplatform/avalanchego:latest",
                VolumeSizeGB:  5,
                IngressHost:   "localhost:30791",
            },
        },
        Nodes: tmpnet.NewNodesOrPanic(5),
    }

    if err := tmpnet.BootstrapNewNetwork(ctx, logging.NoLog{}, network, ""); err != nil {
        log.Fatal(err)
    }
    defer network.Stop(ctx)

    fmt.Println("Network created successfully!")
}

# Check pods
kubectl get pods -n tmpnet-demo

# Access node API
curl http://localhost:30791/networks/<network-uuid>/<node-id>/ext/health

timeout := time.Duration(nodeCount) * time.Minute
if config.UseExclusiveScheduling {
    timeout *= 2  // Double for anti-affinity scheduling
}

import (
    "github.com/ava-labs/avalanchego/tests/fixture/e2e"
)

var _ = ginkgo.Describe("[Cross-Runtime Tests]", func() {
    ginkgo.It("should work on any runtime", func() {
        // Get the test environment (local or Kubernetes)
        env := e2e.GetEnv(tc)

        // Get network - abstracted across runtimes
        network := env.GetNetwork()

        // Get node URIs - automatically handles port-forward vs direct
        nodeURI := env.GetRandomNodeURI()

        // All operations work identically regardless of runtime
        _, err := health.NewClient(nodeURI.URI).Health(context.Background(), nil) // github.com/ava-labs/avalanchego/api/health
        Expect(err).NotTo(HaveOccurred())
    })
})

StatefulSet: bootstrap-monitor
├── Init Container: bootstrap-monitor init
│   └── Prepares configuration and data directory
├── Containers:
│   ├── avalanchego (primary)
│   │   └── Runs node with sync monitoring
│   └── bootstrap-monitor wait-for-completion (sidecar)
│       └── Polls health and emits completion status
└── PersistentVolumeClaim: data
    └── Persistent storage for node database

~/.tmpnet/prometheus/file_sd_configs/
└── [network-uuid]-[node-id].json

# Prometheus
export PROMETHEUS_URL="https://prometheus.example.com"
export PROMETHEUS_PUSH_URL="https://prometheus.example.com/api/v1/push"
export PROMETHEUS_USERNAME="user"
export PROMETHEUS_PASSWORD="pass"

# Loki (logs)
export LOKI_URL="https://loki.example.com"
export LOKI_PUSH_URL="https://loki.example.com/loki/api/v1/push"
export LOKI_USERNAME="user"
export LOKI_PASSWORD="pass"

# Grafana
export GRAFANA_URI="https://grafana.example.com/d/tmpnet"

tmpnetctl start-network
# Output includes:
# The log output includes:
# metrics and logs available via grafana (collectors must be running) {"url": "https://grafana.example.com/d/tmpnet?&var-filter=network_uuid%7C%3D%7Cabc-123&..."}

pkill -f avalanchego
lsof -i :9650-9660

kubectl describe pod <pod-name> -n tmpnet
kubectl get events -n tmpnet --sort-by='.lastTimestamp'

# Check if node is still bootstrapping (requires jq: brew install jq)
# tmpnet nodes use dynamic ports. Read the node URI from node.URI or [node dir]/process.json.
# For the kube runtime, use http://localhost:30791/networks/<network-uuid>/<node-id>.
curl -s -X POST -H 'content-type:application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"info.isBootstrapped","params":{"chain":"P"}}' \
  <node-uri>/ext/info | jq '.result.isBootstrapped'

# Alternative without jq:
curl -s <node-uri>/ext/health