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 ¶
- type APIError
- type Client
- func (c *Client) DownloadFiles(ctx context.Context, result *RunResult, destDir string) error
- func (c *Client) GetExecution(ctx context.Context, id string) (*RunResult, error)
- func (c *Client) GetExecutionLogs(ctx context.Context, id string) (string, error)
- func (c *Client) GetSkill(ctx context.Context, name, version string) (*SkillDetail, error)
- func (c *Client) Health(ctx context.Context) error
- func (c *Client) ListSkills(ctx context.Context) ([]Skill, error)
- func (c *Client) RegisterSkill(ctx context.Context, zipPath string) error
- func (c *Client) Run(ctx context.Context, req RunRequest) (*RunResult, error)
- type Option
- type RunRequest
- type RunResult
- type Skill
- type SkillDetail
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.
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 ¶
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) DownloadFiles ¶
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 ¶
GetExecution retrieves the current state of a previously started execution.
func (*Client) GetExecutionLogs ¶
GetExecutionLogs returns the combined stdout/stderr logs for an execution.
func (*Client) GetSkill ¶
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 ¶
Health checks whether the Skillbox server is reachable. It returns nil on success or an error describing the failure.
func (*Client) ListSkills ¶
ListSkills returns all skills registered on the server. The response includes descriptions so callers can decide which skill to use.
func (*Client) RegisterSkill ¶
RegisterSkill uploads a skill zip archive to the Skillbox server. zipPath must point to a readable .zip file on disk.
func (*Client) Run ¶
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.
type Option ¶
type Option func(*Client)
Option configures a Client. Pass options to New.
func WithHTTPClient ¶
WithHTTPClient replaces the default HTTP client. Use this to configure custom timeouts, transport settings, or instrumentation.
func WithTenant ¶
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.
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