skillbox

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Mar 3, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package skillbox provides a Go client for the Skillbox API — an open-source secure skill execution runtime for AI agents.

The client wraps the Skillbox REST API with zero dependencies beyond the Go standard library.

Quick start 

client := skillbox.New("http://localhost:8080", "sk-your-api-key")
result, err := client.Run(ctx, skillbox.RunRequest{
    Skill: "data-analysis",
    Input: json.RawMessage(`{"data": [1, 2, 3]}`),
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Status, string(result.Output))

Authentication

Pass the API key directly to New, or leave it empty to read from the SKILLBOX_API_KEY environment variable automatically.

Multi-tenancy

Use WithTenant to scope all requests to a specific tenant: 

client := skillbox.New(baseURL, apiKey, skillbox.WithTenant("tenant-42"))

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	// StatusCode is the HTTP status code of the response.
	StatusCode int `json:"-"`

	// ErrorCode is a machine-readable error identifier (e.g. "invalid_request").
	ErrorCode string `json:"error"`

	// Message is a human-readable description of what went wrong.
	Message string `json:"message"`
}

APIError is returned when the Skillbox API responds with a non-2xx status code and a structured error body.

func (*APIError) Error 

func (e *APIError) Error() string

Error implements the error interface.

type Client 

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

Client communicates with the Skillbox API. Create one with New and reuse it for the lifetime of your application — it is safe for concurrent use.

func New 

func New(baseURL, apiKey string, opts ...Option) *Client

New creates a new Skillbox Client.

If apiKey is empty, New falls back to the SKILLBOX_API_KEY environment variable. When neither is set, requests are sent without authentication (useful for local development without auth enabled).

The returned client uses http.DefaultClient unless overridden with WithHTTPClient.

func (*Client) DeleteFile added in v0.2.0 

func (c *Client) DeleteFile(ctx context.Context, id string) error

DeleteFile removes a file by its ID. The server responds with 204 No Content on success.

func (*Client) DownloadFile added in v0.2.0 

func (c *Client) DownloadFile(ctx context.Context, id, destPath string) error

DownloadFile fetches the raw content of a file and writes it to destPath on disk. The destination path is validated to prevent path-traversal attacks — it must resolve to an absolute path that does not contain "..".

func (*Client) DownloadFiles 

func (c *Client) DownloadFiles(ctx context.Context, result *RunResult, destDir string) error

DownloadFiles fetches the output file archive from a completed execution, decompresses the gzip layer, and extracts the tar entries into destDir.

If the execution produced no files (RunResult.HasFiles returns false), DownloadFiles is a no-op and returns nil.

All tar entry paths are validated to prevent path-traversal attacks — entries that would escape destDir cause an immediate error.

func (*Client) GetExecution 

func (c *Client) GetExecution(ctx context.Context, id string) (*RunResult, error)

GetExecution retrieves the current state of a previously started execution.

func (*Client) GetExecutionLogs 

func (c *Client) GetExecutionLogs(ctx context.Context, id string) (string, error)

GetExecutionLogs returns the combined stdout/stderr logs for an execution.

func (*Client) GetFile added in v0.2.0 

func (c *Client) GetFile(ctx context.Context, id string) (*FileInfo, error)

GetFile retrieves the metadata for a single file by its ID.

func (*Client) GetSkill 

func (c *Client) GetSkill(ctx context.Context, name, version string) (*SkillDetail, error)

GetSkill retrieves the full metadata for a specific skill version, including the SKILL.md instructions body. Use this to understand what a skill does, what input it expects, and how it behaves before calling Run.

func (*Client) Health 

func (c *Client) Health(ctx context.Context) error

Health checks whether the Skillbox server is reachable. It returns nil on success or an error describing the failure.

func (*Client) ListFileVersions added in v0.2.0 

func (c *Client) ListFileVersions(ctx context.Context, id string) ([]FileInfo, error)

ListFileVersions returns all versions of a file, ordered by version number. Each entry is a full FileInfo record.

func (*Client) ListFiles added in v0.2.0 

func (c *Client) ListFiles(ctx context.Context, filter FileFilter) ([]FileInfo, error)

ListFiles returns files matching the given filter criteria. Use FileFilter to scope results by session, execution, or page through results with limit/offset.

func (*Client) ListSkills 

func (c *Client) ListSkills(ctx context.Context) ([]Skill, error)

ListSkills returns all skills registered on the server. The response includes descriptions so callers can decide which skill to use.

func (*Client) RegisterSkill 

func (c *Client) RegisterSkill(ctx context.Context, zipPath string) error

RegisterSkill uploads a skill zip archive to the Skillbox server. zipPath must point to a readable .zip file on disk.

func (*Client) Run 

func (c *Client) Run(ctx context.Context, req RunRequest) (*RunResult, error)

Run executes a skill and blocks until the execution completes. It returns the full RunResult including output, logs, and file metadata.

The provided context controls the HTTP request lifetime. Use context.WithTimeout to enforce an upper bound on how long the caller is willing to wait.

func (*Client) UpdateFile added in v0.2.0 

func (c *Client) UpdateFile(ctx context.Context, id, filePath string) (*FileInfo, error)

UpdateFile uploads a new version of an existing file. The file at filePath is sent as a multipart form with field name "file". The server responds with the updated FileInfo including the new version number.

type FileFilter added in v0.2.0 

type FileFilter struct {
	SessionID   string
	ExecutionID string
	Limit       int
	Offset      int
}

FileFilter specifies query parameters for listing files.

type FileInfo added in v0.2.0 

type FileInfo struct {
	ID          string  `json:"id"`
	TenantID    string  `json:"tenant_id"`
	SessionID   string  `json:"session_id,omitempty"`
	ExecutionID string  `json:"execution_id,omitempty"`
	Name        string  `json:"name"`
	ContentType string  `json:"content_type"`
	SizeBytes   int64   `json:"size_bytes"`
	S3Key       string  `json:"s3_key"`
	Version     int     `json:"version"`
	ParentID    *string `json:"parent_id,omitempty"`
	CreatedAt   string  `json:"created_at"`
	UpdatedAt   string  `json:"updated_at"`
}

FileInfo represents a file record from the Skillbox API.

type Option 

type Option func(*Client)

Option configures a Client. Pass options to New.

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient replaces the default HTTP client. Use this to configure custom timeouts, transport settings, or instrumentation.

func WithTenant 

func WithTenant(tenantID string) Option

WithTenant sets the X-Tenant-ID header on every request, scoping all operations to the given tenant.

type RunRequest 

type RunRequest struct {
	// Skill is the name of the registered skill to execute (e.g. "data-analysis").
	Skill string `json:"skill"`

	// Version pins a specific skill version. When empty the latest version is used.
	Version string `json:"version,omitempty"`

	// Input is the JSON payload forwarded to the skill's entrypoint.
	Input json.RawMessage `json:"input,omitempty"`

	// Env injects additional environment variables into the execution container.
	Env map[string]string `json:"env,omitempty"`
}

RunRequest describes a skill execution. Skill is the only required field.

type RunResult 

type RunResult struct {
	// ExecutionID is the unique identifier for this execution.
	ExecutionID string `json:"execution_id"`

	// Status is the terminal state: "completed", "failed", "timeout", etc.
	Status string `json:"status"`

	// Output is the JSON payload produced by the skill.
	Output json.RawMessage `json:"output"`

	// FilesURL is a pre-signed URL to download a tar.gz archive of output
	// files. Empty when the execution produced no files.
	FilesURL string `json:"files_url"`

	// FilesList enumerates the relative paths inside the archive.
	FilesList []string `json:"files_list"`

	// Logs contains the combined stdout/stderr captured during execution.
	Logs string `json:"logs"`

	// DurationMs is the wall-clock execution time in milliseconds.
	DurationMs int64 `json:"duration_ms"`

	// Error holds a human-readable message when Status indicates failure.
	Error string `json:"error"`
}

RunResult is the response returned after a skill execution completes.

func (*RunResult) HasFiles 

func (r *RunResult) HasFiles() bool

HasFiles reports whether the execution produced downloadable output files.

type Skill 

type Skill struct {
	Name        string `json:"name"`
	Version     string `json:"version"`
	Description string `json:"description"`
	Lang        string `json:"lang,omitempty"`
}

Skill describes a registered skill definition as returned by list endpoints.

type SkillDetail 

type SkillDetail struct {
	Name         string            `json:"name"`
	Version      string            `json:"version"`
	Description  string            `json:"description"`
	Lang         string            `json:"lang"`
	Image        string            `json:"image,omitempty"`
	Instructions string            `json:"instructions,omitempty"`
	Timeout      string            `json:"timeout,omitempty"`
	Resources    map[string]string `json:"resources,omitempty"`
}

SkillDetail is the full skill definition returned by GetSkill, including the SKILL.md instructions body. This is the key data structure for agents that need to understand what a skill does before executing it.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.