slicer

package module
v0.0.20 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 26, 2026 License: MIT Imports: 18 Imported by: 1

README

Golang SDK for Slicer

SDK for SlicerVM.com

Installation

go get github.com/slicervm/sdk@latest

Features

  • VM Management: Create, list, and delete VMs.
  • Execute Commands in VMs: Run commands in VMs and stream command output (stdout/stderr).
  • File Management: Upload and download files to/from VMs with CpToVM and CpFromVM.
  • Secret Management: Securely manage secrets like API keys or other sensitive information for VMs.

Documentation

Quick start

Create a new slicer config:

slicer new api \
    --count=0 \
    --graceful-shutdown=false \
    --ram 4 \
    --cpu 2 > api.yaml

Create a VM (node) in a host group with the default RAM/CPU settings as defined in the host group.

package main

import (
    "fmt"
    "os"
    "context"
    
    sdk "github.com/slicervm/sdk"
)

func main() {
    // Typically you'd load these from environment variables
    baseURL := os.Getenv("SLICER_URL")      // API base URL
    token := os.Getenv("SLICER_TOKEN")      // Your API token
    userAgent := "my-microvm-client/1.0"
    hostGroup := "api"                       // Existing host group name

    client := sdk.NewSlicerClient(baseURL, token, userAgent, nil /* or &http.Client{} */)

    createReq := sdk.SlicerCreateNodeRequest{
        RamBytes:      4 * 1024 * 1024 * 1024, // 4GB RAM 
        CPUs:       2,
        Userdata: `#!/bin/bash
echo 'Bootstrapping...'
ping -c3 google.com

sudo reboot
`,
        SSHKeys: []string{"ssh-rsa AAAA..."}, // Optional: inject public SSH keys
        ImportUser: "alexellis", // Optional: Import GitHub keys for a specific user
    }

    ctx := context.Background()
    node, err := client.CreateNode(ctx, hostGroup, createReq)
    if err != nil {
        panic(fmt.Errorf("failed to create node: %w", err))
    }

    fmt.Printf("Created VM: hostname=%s ip=%s created_at=%s\n", node.Hostname, node.IP, .CreatedAt)
    fmt.Printf("Parsed IP only: %s\n", node.IPAddress())
}

Start Slicer:

sudo -E slicer up ./api.yaml

Run the program i.e. after running go build -o client main.go:

SLICER_URL=http://127.0.0.1:8080 SLICER_TOKEN="$(sudo cat /var/lib/slicer/auth/token)" ./client

You'll find the logs for the microVM at /var/log/slicer/HOSTNAME.txt, showing the userdata executing.

Notes:

  • The argument order for NewSlicerClient is (baseURL, token, userAgent, httpClient).
  • If RamBytes or CPUs are not the values configured on the host group are used; Userdata, SSHKeys and ImportUser are optional.
  • Userdata runs on first boot; keep it idempotent.
  • Use a persistent http.Client (e.g. with timeout) in production instead of nil.

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrSecretExists is an error returned when a secret with given name already exists.
	ErrSecretExists = errors.New("secret already exists")
)

Functions

func ExtractTarStream added in v0.0.10

func ExtractTarStream(ctx context.Context, r io.Reader, extractDir string, uid, gid uint32) error

ExtractTarStream extracts a tar stream from r into extractDir. Only handles regular files and directories. Preserves mtime and executable bit. Normalizes permissions (strips setuid/setgid/sticky bits). Skips all other entry types. If uid or gid are non-zero, files will be chowned to that uid/gid after creation. Note: Permissions are set when opening files (efficient), chown is only applied if uid/gid are non-zero.

func ExtractTarToPath added in v0.0.10

func ExtractTarToPath(ctx context.Context, r io.Reader, dest string, uid, gid uint32) error

ExtractTarToPath extracts a tar stream to a local path with cp-like renaming. If dest exists and is a directory, extracts into it. Otherwise extracts and renames. No temporary directories are used - extraction happens directly. If uid or gid are non-zero, files will be chowned to that uid/gid after creation.

func GiB added in v0.0.17

func GiB(gb int64) int64

GB converts gigabytes to bytes

func MiB added in v0.0.17

func MiB(mb int64) int64

MB converts megabytes to bytes

func StreamTarArchive added in v0.0.10

func StreamTarArchive(ctx context.Context, w io.Writer, parentDir, baseName string) error

StreamTarArchive streams a tar archive of regular files and directories to w. Only handles regular files and directories. Preserves mtime and executable bit. Skips symlinks, devices, and other special files.

func ValidRelPath added in v0.0.10

func ValidRelPath(p string) bool

ValidRelPath validates that a path is a valid relative path and doesn't contain directory traversal attempts. Note: Backslashes are allowed in filenames (e.g., systemd unit files with escaped characters). Since tar paths use forward slashes as separators (via filepath.ToSlash()), any backslashes in the path are part of the filename, not path separators.

Types

type CreateSecretRequest added in v0.0.6

type CreateSecretRequest struct {
	// Name is the unique name of the secret
	Name string `json:"name"`
	// Data is the secret content
	Data string `json:"data"`
	// Permissions specifies the file permissions (defaults to system default)
	Permissions string `json:"permissions,omitempty"`

	// GID is the user ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	UID uint32 `json:"uid,omitempty"`

	// GID is the group ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	GID uint32 `json:"gid,omitempty"`
}

CreateSecretRequest is the payload for creating a new secret via the REST API.

type Secret added in v0.0.6

type Secret struct {
	// Name is the unique name of the secret
	Name string `json:"name"`
	// Size is the size of the secret data in bytes
	Size int64 `json:"size"`
	// Permissions specifies the file permissions for the secret (e.g., "0600")
	Permissions string `json:"permissions"`

	// GID is the user ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	UID uint32 `json:"uid,omitempty"`

	// GID is the group ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	GID uint32 `json:"gid,omitempty"`

	// ModifiedAt is the time the secret was last modified
	ModifiedAt *time.Time `json:"modified_at,omitempty"`
}

Secret represents a secret stored in the slicer system. Secrets can be used to store sensitive configuration data, keys, or other private information that can be mounted into nodes or used by services.

type SlicerAgentHealthResponse added in v0.0.13

type SlicerAgentHealthResponse struct {
	// Hostname is the hostname of the agent
	Hostname string `json:"hostname,omitempty"`

	// Uptime is the uptime of the agent
	AgentUptime time.Duration `json:"agent_uptime,omitempty"`

	// AgentVersion is the version of the agent
	AgentVersion string `json:"agent_version,omitempty"`

	// SystemUptime is the uptime of the system
	SystemUptime time.Duration `json:"system_uptime,omitempty"`

	// UserdataRan indicates whether the user data script has completed executing
	UserdataRan bool `json:"userdata_ran,omitempty"`
}

type SlicerClient

type SlicerClient struct {
	// contains filtered or unexported fields
}

SlicerClient handles all HTTP communication with the Slicer API

func NewSlicerClient

func NewSlicerClient(baseURL, token string, userAgent string, httpClient *http.Client) *SlicerClient

NewSlicerClient creates a new Slicer API client

func (*SlicerClient) CpFromVM added in v0.0.10

func (c *SlicerClient) CpFromVM(ctx context.Context, vmName, vmPath, localPath string, permissions, mode string) error

CpFromVM copies files from a VM path to a local path. The tar stream is received from the VM and extracted to localPath with proper renaming logic (supports renaming files/directories). If uid or gid are 0, the current user's UID/GID will be used. On Windows, chown operations are skipped (uid/gid are ignored).

func (*SlicerClient) CpToVM added in v0.0.10

func (c *SlicerClient) CpToVM(ctx context.Context, vmName, localPath, vmPath string, uid, gid uint32, permissions, mode string) error

CpToVM copies files from a local path to a VM path. The localPath can be a file or directory. The tar stream is created internally and sent to the VM. uid and gid specify the ownership for extracted files (0 means use default).

func (*SlicerClient) CreateNode

func (c *SlicerClient) CreateNode(ctx context.Context, groupName string, request SlicerCreateNodeRequest) (*SlicerCreateNodeResponse, error)

CreateNode creates a new node in the specified host group

func (*SlicerClient) CreateSecret added in v0.0.6

func (c *SlicerClient) CreateSecret(ctx context.Context, request CreateSecretRequest) error

CreateSecret creates a new secret. Returns ErrSecretExists if a secret with the same name already exists. An error is returned if creation fails.

func (*SlicerClient) CreateVM added in v0.0.10

func (c *SlicerClient) CreateVM(ctx context.Context, groupName string, request SlicerCreateNodeRequest) (*SlicerCreateNodeResponse, error)

CreateVM creates a new VM in a host group

func (*SlicerClient) DeleteNode

func (c *SlicerClient) DeleteNode(groupName, nodeName string) error

DeleteNode deletes a node from the specified host group

func (*SlicerClient) DeleteSecret added in v0.0.6

func (c *SlicerClient) DeleteSecret(ctx context.Context, secretName string) error

DeleteSecret removes a secret. Returns an error if the secret doesn't exist or if the deletion fails.

func (*SlicerClient) DeleteVM added in v0.0.10

func (c *SlicerClient) DeleteVM(ctx context.Context, groupName, hostname string) (*SlicerDeleteResponse, error)

DeleteVM deletes a VM from a host group

func (*SlicerClient) Exec added in v0.0.9

func (c *SlicerClient) Exec(ctx context.Context, nodeName string, execReq SlicerExecRequest) (chan SlicerExecWriteResult, error)

Exec executes a command on the specified node and streams the output. The channel is unbuffered so the caller should read from it promptly to avoid blocking.

func (*SlicerClient) GetAgentHealth added in v0.0.13

func (c *SlicerClient) GetAgentHealth(ctx context.Context, hostname string, includeStats bool) (*SlicerAgentHealthResponse, error)

GetAgentHealth fetches the health of the agent If includeStats is true, the response will include statistics about the system and agent.

func (*SlicerClient) GetHostGroupNodes

func (c *SlicerClient) GetHostGroupNodes(ctx context.Context, groupName string) ([]SlicerNode, error)

GetHostGroupNodes fetches nodes for a specific host group

func (*SlicerClient) GetHostGroups

func (c *SlicerClient) GetHostGroups(ctx context.Context) ([]SlicerHostGroup, error)

GetHostGroups fetches all host groups from the API

func (*SlicerClient) GetVMLogs added in v0.0.10

func (c *SlicerClient) GetVMLogs(ctx context.Context, hostname string, lines int) (*SlicerLogsResponse, error)

GetVMLogs fetches logs for a specific VM

func (*SlicerClient) GetVMStats added in v0.0.10

func (c *SlicerClient) GetVMStats(ctx context.Context, hostname string) ([]SlicerNodeStat, error)

GetVMStats fetches stats for all VMs or a specific VM if hostname is provided. If hostname is empty, returns stats for all VMs.

func (*SlicerClient) ListSecrets added in v0.0.6

func (c *SlicerClient) ListSecrets(ctx context.Context) ([]Secret, error)

ListSecrets retrieves all secrets. Note: The actual secret data is not returned for security reasons.

func (*SlicerClient) ListVMs added in v0.0.10

func (c *SlicerClient) ListVMs(ctx context.Context) ([]SlicerNode, error)

ListVMs fetches all VMs (nodes)

func (*SlicerClient) PatchSecret added in v0.0.6

func (c *SlicerClient) PatchSecret(ctx context.Context, secretName string, request UpdateSecretRequest) error

PatchSecret updates an existing secret with new data and/or metadata. Only the fields provided in the UpdateSecretRequest will be modified. Returns an error if the secret doesn't exist or if the update fails.

func (*SlicerClient) PauseVM added in v0.0.20

func (c *SlicerClient) PauseVM(ctx context.Context, hostname string) error

PauseVM pauses a running VM

func (*SlicerClient) ResumeVM added in v0.0.20

func (c *SlicerClient) ResumeVM(ctx context.Context, hostname string) error

ResumeVM resumes a paused VM

func (*SlicerClient) Shutdown added in v0.0.19

func (c *SlicerClient) Shutdown(ctx context.Context, hostname string, request *SlicerShutdownRequest) error

Shutdown shuts down or reboots a VM. If request is nil, it defaults to shutdown action. The request Action field can be "shutdown" (halt) or "reboot" (restart).

type SlicerCpRequest added in v0.0.10

type SlicerCpRequest struct {
	VM   string // VM name
	Path string // Path on the VM
}

SlicerCpRequest contains parameters for copying files to/from a VM

type SlicerCreateNodeRequest

type SlicerCreateNodeRequest struct {
	RamBytes   int64    `json:"ram_bytes,omitempty"` // RAM size in bytes (must not exceed host group limit)
	CPUs       int      `json:"cpus,omitempty"`      // Number of CPUs (must not exceed host group limit)
	GPUCount   int      `json:"gpu_count,omitempty"`
	Persistent bool     `json:"persistent,omitempty"`
	DiskImage  string   `json:"disk_image,omitempty"`
	ImportUser string   `json:"import_user,omitempty"`
	SSHKeys    []string `json:"ssh_keys,omitempty"`
	Userdata   string   `json:"userdata,omitempty"`
	IP         string   `json:"ip,omitempty"`
	Tags       []string `json:"tags,omitempty"`
	Secrets    []string `json:"secrets,omitempty"`
}

SlicerCreateNodeRequest contains parameters for creating a node

type SlicerCreateNodeResponse

type SlicerCreateNodeResponse struct {
	Hostname  string    `json:"hostname"`
	IP        string    `json:"ip"`
	CreatedAt time.Time `json:"created_at"`
	Arch      string    `json:"arch,omitempty"`
}

SlicerCreateNodeResponse is the response from the REST API when creating a node.

func (*SlicerCreateNodeResponse) IPAddress

func (n *SlicerCreateNodeResponse) IPAddress() net.IP

type SlicerDeleteResponse added in v0.0.10

type SlicerDeleteResponse struct {
	Message     string `json:"message"`
	DiskRemoved string `json:"disk_removed"`
	Error       string `json:"error"`
}

SlicerDeleteResponse represents the response from the delete endpoint

type SlicerExecRequest added in v0.0.9

type SlicerExecRequest struct {
	Command     string   `json:"command,omitempty"`
	Args        []string `json:"args,omitempty"`
	UID         uint32   `json:"uid,omitempty"`
	GID         uint32   `json:"gid,omitempty"`
	Stdin       bool     `json:"stdin,omitempty"`
	Stdout      bool     `json:"stdout,omitempty"`
	Stderr      bool     `json:"stderr,omitempty"`
	Shell       string   `json:"shell,omitempty"`
	Cwd         string   `json:"cwd,omitempty"`
	Permissions string   `json:"permissions,omitempty"`
}

SlicerExecRequest contains parameters for invoking a command within a VM.

type SlicerExecWriteResult added in v0.0.9

type SlicerExecWriteResult struct {
	Timestamp time.Time `json:"timestamp"`
	Stdout    string    `json:"stdout,omitempty"`
	Stderr    string    `json:"stderr,omitempty"`
	ExitCode  int       `json:"exit_code,omitempty"`
	Error     string    `json:"error,omitempty"`
}

ExecWriteResult represents output from commands executing within a microVM.

type SlicerHostGroup

type SlicerHostGroup struct {
	Name     string `json:"name,omitempty"`
	Count    int    `json:"count,omitempty"`
	RamBytes int64  `json:"ram_bytes,omitempty"` // RAM size in bytes
	CPUs     int    `json:"cpus,omitempty"`
	Arch     string `json:"arch,omitempty"`
	GPUCount int    `json:"gpu_count,omitempty"`
}

SlicerHostGroup represents a host group from the /hostgroup endpoint.

type SlicerLogsResponse added in v0.0.10

type SlicerLogsResponse struct {
	Hostname string `json:"hostname"`
	Lines    int    `json:"lines"`
	Content  string `json:"content"`
}

SlicerLogsResponse represents the response from the logs endpoint

type SlicerNode

type SlicerNode struct {
	Hostname  string    `json:"hostname"`
	IP        string    `json:"ip"`
	RamBytes  int64     `json:"ram_bytes,omitempty"` // RAM size in bytes
	CPUs      int       `json:"cpus,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	Arch      string    `json:"arch,omitempty"`
	Tags      []string  `json:"tags,omitempty"`
	Status    string    `json:"status,omitempty"` // "Running" or "Paused"
}

SlicerNode represents a node managed by the slicer REST API.

type SlicerNodeStat added in v0.0.10

type SlicerNodeStat struct {
	Hostname  string          `json:"hostname"`
	IP        string          `json:"ip"`
	CreatedAt time.Time       `json:"created_at"`
	Snapshot  *SlicerSnapshot `json:"snapshot"`
	Error     string          `json:"error"`
}

SlicerNodeStat represents stats for a VM node

type SlicerShutdownRequest added in v0.0.19

type SlicerShutdownRequest struct {
	// Action specifies the shutdown action: "shutdown" (halt) or "reboot" (restart).
	// If empty, defaults to "shutdown".
	Action string `json:"action,omitempty"`
}

SlicerShutdownRequest contains parameters for shutting down or rebooting a VM. Action can be "shutdown" (default) to halt the VM or "reboot" to restart it.

type SlicerSnapshot added in v0.0.10

type SlicerSnapshot struct {
	Hostname             string    `json:"hostname"`
	Arch                 string    `json:"arch"`
	Timestamp            time.Time `json:"timestamp"`
	Uptime               string    `json:"uptime"`
	TotalCPUS            int       `json:"totalCpus"`
	TotalMemory          uint64    `json:"totalMemory"`
	MemoryUsed           uint64    `json:"memoryUsed"`
	MemoryAvailable      uint64    `json:"memoryAvailable"`
	MemoryUsedPercent    float64   `json:"memoryUsedPercent"`
	LoadAvg1             float64   `json:"loadAvg1"`
	LoadAvg5             float64   `json:"loadAvg5"`
	LoadAvg15            float64   `json:"loadAvg15"`
	DiskReadTotal        float64   `json:"diskReadTotal"`
	DiskWriteTotal       float64   `json:"diskWriteTotal"`
	NetworkReadTotal     float64   `json:"networkReadTotal"`
	NetworkWriteTotal    float64   `json:"networkWriteTotal"`
	DiskIOInflight       int64     `json:"diskIOInflight"`
	OpenConnections      int64     `json:"openConnections"`
	OpenFiles            int64     `json:"openFiles"`
	Entropy              int64     `json:"entropy"`
	DiskSpaceTotal       uint64    `json:"diskSpaceTotal"`
	DiskSpaceUsed        uint64    `json:"diskSpaceUsed"`
	DiskSpaceFree        uint64    `json:"diskSpaceFree"`
	DiskSpaceUsedPercent float64   `json:"diskSpaceUsedPercent"`
}

SlicerSnapshot represents a snapshot of VM metrics

type UpdateSecretRequest added in v0.0.6

type UpdateSecretRequest struct {
	// Data is the updated secret content
	Data string `json:"data"`
	// Permissions specifies the file permissions
	Permissions string `json:"permissions,omitempty"`

	// GID is the user ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	UID uint32 `json:"uid,omitempty"`

	// GID is the group ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	GID uint32 `json:"gid,omitempty"`
}

UpdateSecretRequest is the payload for updating an existing secret via the REST API. All fields are optional - only provided fields will be updated.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL