vaultrun

package
v0.4.2 Latest Latest
Warning

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

Go to latest
Published: Oct 15, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package vaultrun provides a Go SDK for the VaultRun API.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIKey

type APIKey struct {
	ID         string     `json:"id"`
	Name       string     `json:"name"`
	Prefix     string     `json:"prefix"`
	Active     bool       `json:"active"`
	CreatedAt  time.Time  `json:"created_at"`
	LastUsedAt *time.Time `json:"last_used_at,omitempty"`
}

APIKey represents a VaultRun API key (plaintext is never returned after creation).

type AsyncRunOptions

type AsyncRunOptions struct {
	RunOptions
	// CallbackURL receives an HTTP POST with the completed Run when the job finishes.
	CallbackURL string
}

AsyncRunOptions extends RunOptions with an optional webhook callback URL.

type AsyncRunResult

type AsyncRunResult struct {
	RunID   string `json:"run_id"`
	Status  string `json:"status"`
	Message string `json:"message"`
}

AsyncRunResult is returned by RunAsync — contains the pending run's ID.

type AuditLog

type AuditLog struct {
	ID        string    `json:"id"`
	Actor     string    `json:"actor"`
	SessionID *string   `json:"session_id,omitempty"`
	RunID     *string   `json:"run_id,omitempty"`
	Action    string    `json:"action"`
	Metadata  any       `json:"metadata,omitempty"`
	Timestamp time.Time `json:"timestamp"`
}

AuditLog is a single entry in the audit trail.

type Client

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

Client is the VaultRun API client.

func New

func New(baseURL, apiKey string) *Client

New creates a new VaultRun client.

func (*Client) AddOrgMember

func (c *Client) AddOrgMember(ctx context.Context, orgID, principal, role string) (*OrgMember, error)

AddOrgMember adds (or updates) a member in an org. Role must be one of "viewer", "executor", or "admin". Requires master key or org admin.

func (*Client) CreateKey

func (c *Client) CreateKey(ctx context.Context, opts CreateKeyOptions) (*CreatedKey, error)

CreateKey creates a new API key. The plaintext key is returned in CreatedKey.Key and will never be retrievable again.

func (*Client) CreateOrg

func (c *Client) CreateOrg(ctx context.Context, name, slug string) (*Organization, error)

CreateOrg creates a new organization. Slug is auto-generated from name if omitted. Requires master key.

func (*Client) CreateSession

func (c *Client) CreateSession(ctx context.Context, opts CreateSessionOptions) (*Session, error)

CreateSession creates a new sandbox session.

func (*Client) CreateSnapshot

func (c *Client) CreateSnapshot(ctx context.Context, sessionID, name string) (*Snapshot, error)

CreateSnapshot creates a snapshot archive of a session's workspace.

func (*Client) DeleteArtifact

func (c *Client) DeleteArtifact(ctx context.Context, artifactID string) error

DeleteArtifact deletes a shared artifact.

func (*Client) DeleteFile

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

DeleteFile removes a file from a session workspace.

func (*Client) DeleteOrg

func (c *Client) DeleteOrg(ctx context.Context, orgID string) error

DeleteOrg deletes an org and all its members. Requires master key.

func (*Client) DeleteSession

func (c *Client) DeleteSession(ctx context.Context, sessionID string) error

DeleteSession stops and removes a session.

func (*Client) DeleteSnapshot

func (c *Client) DeleteSnapshot(ctx context.Context, snapshotID string) error

DeleteSnapshot deletes a snapshot.

func (*Client) DownloadArtifact

func (c *Client) DownloadArtifact(ctx context.Context, artifactID string) ([]byte, error)

DownloadArtifact streams an artifact file and returns the raw bytes.

func (*Client) DownloadFile

func (c *Client) DownloadFile(ctx context.Context, sessionID, remotePath string) (io.ReadCloser, error)

DownloadFile downloads a single file from a session workspace.

func (*Client) DownloadSnapshot

func (c *Client) DownloadSnapshot(ctx context.Context, snapshotID string) ([]byte, error)

DownloadSnapshot streams a snapshot archive and returns the raw bytes.

func (*Client) DownloadWorkspace

func (c *Client) DownloadWorkspace(ctx context.Context, sessionID string) (io.ReadCloser, error)

DownloadWorkspace downloads the entire workspace as a ZIP archive. The caller is responsible for closing the returned ReadCloser.

func (*Client) GetOrg

func (c *Client) GetOrg(ctx context.Context, orgID string) (*Organization, error)

GetOrg fetches a single org by ID. Accessible to org members.

func (*Client) GetRun

func (c *Client) GetRun(ctx context.Context, runID string) (*Run, error)

GetRun retrieves a run by ID.

func (*Client) GetSession

func (c *Client) GetSession(ctx context.Context, sessionID string) (*Session, error)

GetSession retrieves a session by ID.

func (*Client) GetSessionLogs

func (c *Client) GetSessionLogs(ctx context.Context, sessionID string, tail int) (string, error)

GetSessionLogs returns the last n lines of container logs for the session. Pass 0 to use the server default.

func (*Client) GetSessionStats

func (c *Client) GetSessionStats(ctx context.Context, sessionID string) (*SessionStats, error)

GetSessionStats returns live CPU/memory usage for the given session.

func (*Client) ListArtifacts

func (c *Client) ListArtifacts(ctx context.Context) ([]*SharedArtifact, error)

ListArtifacts returns shared artifacts visible to the caller.

func (*Client) ListAuditLogs

func (c *Client) ListAuditLogs(ctx context.Context, opts ...ListAuditLogsOptions) ([]*AuditLog, error)

ListAuditLogs returns audit log entries for the current actor. Master key holders receive all actors' entries; regular keys receive only their own. Use opts.SessionID to narrow results to a specific session.

func (*Client) ListFiles

func (c *Client) ListFiles(ctx context.Context, sessionID string) ([]*File, error)

ListFiles returns all files in a session workspace.

func (*Client) ListImages

func (c *Client) ListImages(ctx context.Context) ([]*Image, error)

ListImages returns Docker images available on the host.

func (*Client) ListKeys

func (c *Client) ListKeys(ctx context.Context) ([]*APIKey, error)

ListKeys returns all API keys.

func (*Client) ListOrgMembers

func (c *Client) ListOrgMembers(ctx context.Context, orgID string) ([]*OrgMember, error)

ListOrgMembers lists all members of an org. Accessible to org members.

func (*Client) ListOrgSessions

func (c *Client) ListOrgSessions(ctx context.Context, orgID string) ([]*Session, error)

ListOrgSessions returns active sessions belonging to the org. The caller must be an org member; results are filtered by the server.

func (*Client) ListOrgs

func (c *Client) ListOrgs(ctx context.Context) ([]*Organization, error)

ListOrgs returns all organizations. Requires master key.

func (*Client) ListRuns

func (c *Client) ListRuns(ctx context.Context, sessionID string) ([]*Run, error)

ListRuns returns all runs for a session.

func (*Client) ListSessions

func (c *Client) ListSessions(ctx context.Context, opts ...ListSessionsOptions) ([]*Session, error)

ListSessions returns active sessions visible to the authenticated caller.

func (*Client) ListSnapshots

func (c *Client) ListSnapshots(ctx context.Context, sessionID string) ([]*Snapshot, error)

ListSnapshots lists all snapshots for a session.

func (*Client) PromoteArtifact

func (c *Client) PromoteArtifact(ctx context.Context, sessionID, path string, name ...string) (*SharedArtifact, error)

PromoteArtifact promotes a session file to the shared artifact registry. path is the file path inside the session workspace.

func (*Client) PullImage

func (c *Client) PullImage(ctx context.Context, image string) (*PullStatus, error)

PullImage requests the host to pull the named Docker image.

func (*Client) RemoveOrgMember

func (c *Client) RemoveOrgMember(ctx context.Context, orgID, principal string) error

RemoveOrgMember removes a principal from an org. Requires master key or org admin.

func (*Client) RevokeKey

func (c *Client) RevokeKey(ctx context.Context, keyID string) error

RevokeKey deactivates an API key by ID.

func (*Client) Run

func (c *Client) Run(ctx context.Context, sessionID string, opts RunOptions) (*Run, error)

Run executes a command inside a session and waits for the result.

func (*Client) RunAsync

func (c *Client) RunAsync(ctx context.Context, sessionID string, opts AsyncRunOptions) (*AsyncRunResult, error)

RunAsync submits a command for non-blocking execution. It returns immediately with the pending run's ID. Poll GetRun to check for completion, or supply a CallbackURL to receive a webhook when done.

func (*Client) Stream

func (c *Client) Stream(ctx context.Context, sessionID string, opts RunOptions, stdout, stderr io.Writer) (*StreamEvent, error)

Stream executes a command via SSE, writing stdout/stderr chunks to the provided writers as they arrive. Returns the final StreamEvent (type="done"). Pass nil for stdout or stderr to discard that stream.

func (*Client) UpdateSessionLabels

func (c *Client) UpdateSessionLabels(ctx context.Context, sessionID string, labels map[string]string) error

UpdateSessionLabels replaces the label set on a session. Pass an empty map to clear all labels.

func (*Client) UploadFile

func (c *Client) UploadFile(ctx context.Context, sessionID, remotePath string, content io.Reader) (*File, error)

UploadFile uploads a file to a session workspace.

type CreateKeyOptions

type CreateKeyOptions struct {
	Name      string
	ExpiresAt *time.Time // nil means no expiry
}

CreateKeyOptions configures a new API key.

type CreateSessionOptions

type CreateSessionOptions struct {
	Name           string
	Image          string
	NetworkEnabled bool
	CPULimit       float64
	MemoryLimitMB  int
	TimeoutSeconds int
	Labels         map[string]string
}

CreateSessionOptions configures a new session.

type CreatedKey

type CreatedKey struct {
	APIKey
	Key string `json:"key"`
}

CreatedKey is returned once on key creation — it includes the plaintext key.

type File

type File struct {
	ID          string    `json:"id"`
	SessionID   string    `json:"session_id"`
	Path        string    `json:"path"`
	SizeBytes   int64     `json:"size_bytes"`
	ContentType string    `json:"content_type"`
	CreatedAt   time.Time `json:"created_at"`
}

File represents a file in a session workspace.

type Image

type Image struct {
	ID        string   `json:"id"`
	Tags      []string `json:"tags"`
	SizeBytes int64    `json:"size_bytes"`
	CreatedAt string   `json:"created_at"`
}

Image represents a Docker image available on the host.

type ListAuditLogsOptions

type ListAuditLogsOptions struct {
	// SessionID restricts entries to a single session.
	// Non-master callers may only query sessions they own.
	SessionID string
	Limit     int // 0 uses the server default (50)
	Offset    int
}

ListAuditLogsOptions filters the audit log query.

type ListSessionsOptions

type ListSessionsOptions struct {
	// LabelKey and LabelValue filter by a specific label (both must be set).
	LabelKey   string
	LabelValue string
}

ListSessionsOptions filters the session list.

type OrgMember

type OrgMember struct {
	OrgID     string    `json:"org_id"`
	Principal string    `json:"principal"`
	Role      string    `json:"role"` // "viewer" | "executor" | "admin"
	CreatedAt time.Time `json:"created_at"`
}

OrgMember represents a principal's membership in an org.

type Organization

type Organization struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"`
	Slug      string    `json:"slug"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

Organization represents a VaultRun team/org.

type PullStatus

type PullStatus struct {
	Image   string `json:"image"`
	Status  string `json:"status"`
	Message string `json:"message"`
}

PullStatus is returned after requesting an image pull.

type Run

type Run struct {
	ID              string     `json:"id"`
	SessionID       string     `json:"session_id"`
	Command         string     `json:"command"`
	Args            []string   `json:"args"`
	Status          string     `json:"status"`
	ExitCode        *int       `json:"exit_code,omitempty"`
	Stdout          *string    `json:"stdout,omitempty"`
	Stderr          *string    `json:"stderr,omitempty"`
	DurationMS      *int64     `json:"duration_ms,omitempty"`
	TimeoutSeconds  int        `json:"timeout_seconds"`
	OutputTruncated bool       `json:"output_truncated,omitempty"`
	CreatedAt       time.Time  `json:"created_at"`
	StartedAt       *time.Time `json:"started_at,omitempty"`
	FinishedAt      *time.Time `json:"finished_at,omitempty"`
}

Run represents a command execution result.

type RunOptions

type RunOptions struct {
	Command        string
	Args           []string
	Env            map[string]string
	WorkingDir     string
	TimeoutSeconds int
}

RunOptions configures a command execution.

type Session

type Session struct {
	ID             string            `json:"id"`
	Name           *string           `json:"name,omitempty"`
	Image          string            `json:"image"`
	Status         string            `json:"status"`
	ContainerID    *string           `json:"container_id,omitempty"`
	NetworkEnabled bool              `json:"network_enabled"`
	CPULimit       float64           `json:"cpu_limit"`
	MemoryLimitMB  int               `json:"memory_limit_mb"`
	TimeoutSeconds int               `json:"timeout_seconds"`
	Labels         map[string]string `json:"labels,omitempty"`
	CreatedAt      time.Time         `json:"created_at"`
	StoppedAt      *time.Time        `json:"stopped_at,omitempty"`
}

Session represents a VaultRun sandbox session.

type SessionStats

type SessionStats struct {
	SessionID     string  `json:"session_id"`
	CPUPercent    float64 `json:"cpu_percent"`
	MemoryUsageMB float64 `json:"memory_usage_mb"`
	MemoryLimitMB int     `json:"memory_limit_mb"`
	PIDs          int     `json:"pids"`
}

SessionStats holds live resource usage for a running session.

type SharedArtifact

type SharedArtifact struct {
	ID          string    `json:"id"`
	Name        string    `json:"name"`
	SizeBytes   int64     `json:"size_bytes"`
	ContentType string    `json:"content_type"`
	CreatedBy   string    `json:"created_by"`
	SessionID   *string   `json:"session_id,omitempty"`
	CreatedAt   time.Time `json:"created_at"`
}

SharedArtifact represents a file promoted to the shared artifact registry.

type Snapshot

type Snapshot struct {
	ID        string    `json:"id"`
	SessionID string    `json:"session_id"`
	Name      string    `json:"name"`
	CreatedBy string    `json:"created_by"`
	SizeBytes int64     `json:"size_bytes"`
	CreatedAt time.Time `json:"created_at"`
}

Snapshot represents a compressed workspace archive.

type StreamEvent

type StreamEvent struct {
	Type       string `json:"type"`        // "stdout", "stderr", or "done"
	Data       string `json:"data"`        // populated for stdout/stderr
	RunID      string `json:"run_id"`      // populated in done
	Status     string `json:"status"`      // populated in done
	ExitCode   *int   `json:"exit_code"`   // populated in done
	DurationMS *int64 `json:"duration_ms"` // populated in done
	Error      string `json:"error"`       // populated on error
}

StreamEvent is a single SSE event from the run/stream endpoint.

Jump to

Keyboard shortcuts

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