Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/superfly/sprites-go/llms.txt

Use this file to discover all available pages before exploring further.

Services are long-running processes managed inside a sprite — databases, web servers, background workers, and similar daemons. The services API lets you define a service with a command, start and stop it on demand, tail its logs in real time via a streaming interface, and send OS signals. Most lifecycle operations return a ServiceStream that delivers log events as the service starts or stops.

​
Client methods

​
ListServices

func (c *Client) ListServices(ctx context.Context, spriteName string) ([]*ServiceWithState, error)
Returns all services defined on the sprite, each with their current runtime state.
​
ctx
context.Context
required
Request context.
​
spriteName
string
required
Name of the sprite to query.
​
[]*ServiceWithState
[]*ServiceWithState
Slice of services with combined definition and state. Empty slice when no services exist.
​
error
error
Non-nil on network or API errors.

​
GetService

func (c *Client) GetService(ctx context.Context, spriteName, serviceName string) (*ServiceWithState, error)
Fetches a single service by name, including its current state.
​
ctx
context.Context
required
Request context.
​
spriteName
string
required
Name of the sprite.
​
serviceName
string
required
Name of the service to fetch.
​
*ServiceWithState
*ServiceWithState
Service definition and runtime state.
​
error
error
Wraps "service not found" when the service does not exist.

​
CreateService

func (c *Client) CreateService(ctx context.Context, spriteName, serviceName string, req *ServiceRequest) (*ServiceStream, error)
Creates or updates a service definition and immediately starts it, returning a log stream. The stream closes when the service has finished starting. Use CreateServiceWithDuration to monitor the service for longer than the default window.
​
ctx
context.Context
required
Request context. Cancelling closes the stream but does not stop the service.
​
spriteName
string
required
Name of the sprite.
​
serviceName
string
required
Name to assign the service.
​
req
*ServiceRequest
required
Service definition. See ServiceRequest.
​
*ServiceStream
*ServiceStream
Stream of ServiceLogEvent values. Call ProcessAll or iterate with Next.
​
error
error
Returns a conflict error if the service name is already in use.
httpPort := 3000
stream, err := client.CreateService(ctx, "my-sprite", "web", &sprites.ServiceRequest{
    Cmd:      "node",
    Args:     []string{"server.js"},
    HTTPPort: &httpPort,
})
if err != nil {
    log.Fatal(err)
}
stream.ProcessAll(func(e *sprites.ServiceLogEvent) error {
    fmt.Printf("[%s] %s\n", e.Type, e.Data)
    return nil
})

​
CreateServiceWithDuration

func (c *Client) CreateServiceWithDuration(ctx context.Context, spriteName, serviceName string, req *ServiceRequest, duration time.Duration) (*ServiceStream, error)
Identical to CreateService but keeps the log stream open for the specified duration after the service starts, allowing you to observe initial output. Pass 0 for the default window.
​
ctx
context.Context
required
Request context.
​
spriteName
string
required
Name of the sprite.
​
serviceName
string
required
Name to assign the service.
​
req
*ServiceRequest
required
Service definition.
​
duration
time.Duration
required
How long to keep the stream open after start. 0 uses the server default.

​
DeleteService

func (c *Client) DeleteService(ctx context.Context, spriteName, serviceName string) error
Deletes the named service. The service must be stopped before deletion.
​
ctx
context.Context
required
Request context.
​
spriteName
string
required
Name of the sprite.
​
serviceName
string
required
Name of the service to delete.
​
error
error
Returns "service not found" or "service conflict" if the service is still running.

​
StartService

func (c *Client) StartService(ctx context.Context, spriteName, serviceName string) (*ServiceStream, error)
Starts a stopped service and returns a log stream. The stream closes once the service is running.
​
ctx
context.Context
required
Request context.
​
spriteName
string
required
Name of the sprite.
​
serviceName
string
required
Name of the service to start.
​
*ServiceStream
*ServiceStream
Stream of startup log events.
​
error
error
Returns "service not found" if the service does not exist.

​
StartServiceWithDuration

func (c *Client) StartServiceWithDuration(ctx context.Context, spriteName, serviceName string, duration time.Duration) (*ServiceStream, error)
Starts a service and keeps the log stream open for duration. Pass 0 for the default monitoring window.
​
ctx
context.Context
required
Request context.
​
spriteName
string
required
Name of the sprite.
​
serviceName
string
required
Name of the service to start.
​
duration
time.Duration
required
Monitoring window after start.

​
StopService

func (c *Client) StopService(ctx context.Context, spriteName, serviceName string) (*ServiceStream, error)
Stops a running service and returns a stream of shutdown events. The stream closes once the service is fully stopped.
​
ctx
context.Context
required
Request context.
​
spriteName
string
required
Name of the sprite.
​
serviceName
string
required
Name of the service to stop.
​
*ServiceStream
*ServiceStream
Stream of shutdown log events.
​
error
error
Returns "service not running" if the service is already stopped.

​
StopServiceWithTimeout

func (c *Client) StopServiceWithTimeout(ctx context.Context, spriteName, serviceName string, timeout time.Duration) (*ServiceStream, error)
Stops a service with a custom shutdown timeout. Pass 0 for the default.
​
ctx
context.Context
required
Request context.
​
spriteName
string
required
Name of the sprite.
​
serviceName
string
required
Name of the service to stop.
​
timeout
time.Duration
required
How long to wait for the service to stop gracefully before force-killing it.

​
SignalService

func (c *Client) SignalService(ctx context.Context, spriteName, serviceName, signal string) error
Sends a POSIX signal to a running service by name (e.g., "SIGHUP", "SIGUSR1").
​
ctx
context.Context
required
Request context.
​
spriteName
string
required
Name of the sprite.
​
serviceName
string
required
Name of the service to signal.
​
signal
string
required
Signal name, e.g., "SIGHUP", "SIGUSR1", "SIGTERM".
​
error
error
Returns "service not found", "service not running", or "invalid signal" on errors.
err := client.SignalService(ctx, "my-sprite", "web", "SIGHUP")

​
ServiceStream

ServiceStream provides a streaming view of log events produced by service lifecycle operations (create, start, stop). 
type ServiceStream struct {
    // unexported fields
}

​
Next

func (ss *ServiceStream) Next() (*ServiceLogEvent, error)
Reads and returns the next log event from the stream. Returns io.EOF when the stream is exhausted. Empty lines are skipped automatically.
​
*ServiceLogEvent
*ServiceLogEvent
Next event from the stream.
​
error
error
io.EOF at end of stream, or a parse/network error.

​
ProcessAll

func (ss *ServiceStream) ProcessAll(handler func(*ServiceLogEvent) error) error
Reads all events from the stream, calling handler for each one. Closes the stream automatically when done. Returns the first non-nil error from handler or from reading the stream.
​
handler
func(*ServiceLogEvent) error
required
Callback invoked for each event. Return a non-nil error to abort processing.

​
Close

func (ss *ServiceStream) Close() error
Closes the underlying HTTP response body. Safe to call multiple times.

​
Types

​
ServiceRequest

Defines the command and configuration for a new service. 
type ServiceRequest struct {
    Cmd      string   `json:"cmd"`
    Args     []string `json:"args,omitempty"`
    Needs    []string `json:"needs,omitempty"`
    HTTPPort *int     `json:"http_port,omitempty"`
}
​
Cmd
string
Executable to run (e.g., "node", "/usr/bin/python3").
​
Args
[]string
Arguments passed to the executable.
​
Needs
[]string
Names of other services that must be running before this service starts.
​
HTTPPort
*int
Optional. Port the service’s HTTP server listens on, used for health checking.

​
ServiceLogEvent

Represents a single event emitted by a ServiceStream. 
type ServiceLogEvent struct {
    Type      string            `json:"type"`
    Data      string            `json:"data,omitempty"`
    ExitCode  *int              `json:"exit_code,omitempty"`
    Timestamp int64             `json:"timestamp"`
    LogFiles  map[string]string `json:"log_files,omitempty"`
}
​
Type
string
Event type. One of "stdout", "stderr", "exit", "error", "complete", "started", "stopping", "stopped".
​
Data
string
Event payload — log line content for stdout/stderr events, or a message for status events.
​
ExitCode
*int
Present on "exit" events. The process exit code.
​
Timestamp
int64
Unix timestamp in milliseconds when the event was emitted.
​
LogFiles
map[string]string
Present on "complete" events. Maps log file names to their paths inside the sprite.

​
ServiceWithState

Combines the service definition with its current runtime state. 
type ServiceWithState struct {
    Service
    State *ServiceState `json:"state,omitempty"`
}
​
Service
Service
Embedded service definition.
​
State
*ServiceState
Runtime state. nil if the service has never been started.

​
ServiceState

Runtime state of a service as returned inside ServiceWithState. 
type ServiceState struct {
    Name          string    `json:"name"`
    Status        string    `json:"status"`
    PID           int       `json:"pid,omitempty"`
    StartedAt     time.Time `json:"started_at,omitempty"`
    Error         string    `json:"error,omitempty"`
    RestartCount  int       `json:"restart_count,omitempty"`
    NextRestartAt time.Time `json:"next_restart_at,omitempty"`
}
​
Status
string
One of "stopped", "starting", "running", "stopping", or "failed".

Build docs developers (and LLMs) love

Get started for freeTalk to us