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.

The proxy API lets your local process communicate directly with services running inside a sprite over encrypted WebSocket tunnels. You can forward a single port, batch-forward multiple ports at once, or open a raw net.Conn for custom protocols. ProxyManager simplifies lifecycle management when you need to track and tear down several sessions together.

​
Client methods

​
ProxyPort

func (c *Client) ProxyPort(ctx context.Context, spriteName string, localPort, remotePort int) (*ProxySession, error)
Creates a TCP proxy session that listens on localPort locally and forwards connections to remotePort on the named sprite. Returns the active session or an error if the listener cannot be created.
​
ctx
context.Context
required
Context for the lifetime of the proxy session. Cancelling the context closes the session.
​
spriteName
string
required
Name of the sprite to proxy to.
​
localPort
int
required
Local TCP port to listen on (1–65535).
​
remotePort
int
required
Remote TCP port on the sprite to forward to.
​
*ProxySession
*ProxySession
Active proxy session. Call Close() when done.
​
error
error
Non-nil if the local listener could not be bound or the proxy could not be established.
session, err := client.ProxyPort(ctx, "my-sprite", 8080, 8080)
if err != nil {
    log.Fatal(err)
}
defer session.Close()
// Local :8080 now forwards to sprite port 8080
session.Wait()

​
ProxyPorts

func (c *Client) ProxyPorts(ctx context.Context, spriteName string, mappings []PortMapping) ([]*ProxySession, error)
Creates proxy sessions for multiple port mappings in a single call. If any mapping fails, all previously created sessions are closed before the error is returned.
​
ctx
context.Context
required
Context controlling all sessions created by this call.
​
spriteName
string
required
Name of the sprite to proxy to.
​
mappings
[]PortMapping
required
Slice of PortMapping structs defining each local-to-remote port pair.
​
[]*ProxySession
[]*ProxySession
One active session per mapping, in the same order as the input slice.
​
error
error
Non-nil if any session could not be established (all sessions are cleaned up on failure).
sessions, err := client.ProxyPorts(ctx, "my-sprite", []sprites.PortMapping{
    {LocalPort: 5432, RemotePort: 5432},
    {LocalPort: 6379, RemotePort: 6379},
})
if err != nil {
    log.Fatal(err)
}
defer func() {
    for _, s := range sessions {
        s.Close()
    }
}()

​
ProxySocket

func (c *Client) ProxySocket(ctx context.Context, network, spriteName, addr string) (net.Conn, error)
Opens a raw proxied net.Conn to an address inside the sprite. The only supported network value is "tcp". The returned connection behaves like any standard net.Conn.
​
ctx
context.Context
required
Context for the connection handshake.
​
network
string
required
Network type. Only "tcp" is supported.
​
spriteName
string
required
Name of the sprite to connect to.
​
addr
string
required
Host and port in the form "host:port", e.g., "localhost:5432".
​
net.Conn
net.Conn
Full-duplex connection to the remote address inside the sprite.
​
error
error
Non-nil if the network is unsupported or the WebSocket handshake fails.
conn, err := client.ProxySocket(ctx, "tcp", "my-sprite", "localhost:5432")
if err != nil {
    log.Fatal(err)
}
defer conn.Close()
// Use conn as any net.Conn

​
Sprite methods

The Sprite type exposes the same proxy methods without requiring the sprite name:

​
ProxyPort

func (s *Sprite) ProxyPort(ctx context.Context, localPort, remotePort int) (*ProxySession, error)
Equivalent to client.ProxyPort(ctx, sprite.Name(), localPort, remotePort).

​
ProxyPorts

func (s *Sprite) ProxyPorts(ctx context.Context, mappings []PortMapping) ([]*ProxySession, error)
Equivalent to client.ProxyPorts(ctx, sprite.Name(), mappings).

​
ProxySocket

func (s *Sprite) ProxySocket(ctx context.Context, network, addr string) (net.Conn, error)
Equivalent to client.ProxySocket(ctx, network, sprite.Name(), addr).

​
ProxySession

ProxySession represents an active port-forwarding listener. It is returned by ProxyPort and ProxyPorts. 
type ProxySession struct {
    LocalPort  int
    RemotePort int
    RemoteHost string
    // unexported fields
}
​
LocalPort
int
Local TCP port the session is listening on.
​
RemotePort
int
Remote TCP port on the sprite that connections are forwarded to.
​
RemoteHost
string
Specific remote host to connect to inside the sprite (e.g., "10.0.0.1"). Defaults to "localhost" when empty.

​
Close

func (ps *ProxySession) Close() error
Stops the session: cancels the session context, closes the local TCP listener, and signals the accept loop to exit. Idempotent — safe to call multiple times.

​
Wait

func (ps *ProxySession) Wait()
Blocks until the session is closed. Useful for keeping a process alive while the proxy is active.

​
LocalAddr

func (ps *ProxySession) LocalAddr() net.Addr
Returns the net.Addr of the local listener, or nil if the session has no listener. 
session, _ := sprite.ProxyPort(ctx, 0, 8080) // port 0 = OS-assigned
fmt.Println("listening on", session.LocalAddr())

​
PortMapping

PortMapping describes a single local-to-remote port forwarding rule used with ProxyPorts. 
type PortMapping struct {
    LocalPort  int
    RemotePort int
    RemoteHost string
}
​
LocalPort
int
Local TCP port to listen on.
​
RemotePort
int
Remote TCP port on the sprite to forward to.
​
RemoteHost
string
Optional. Specific host inside the sprite to connect to (e.g., "10.0.0.1", "fdf::1"). Defaults to "localhost" when empty.

​
ProxyManager

ProxyManager tracks a collection of ProxySession values and provides bulk lifecycle operations. 
type ProxyManager struct {
    // unexported fields
}

​
NewProxyManager

func NewProxyManager() *ProxyManager
Creates and returns a new, empty ProxyManager.

​
AddSession

func (pm *ProxyManager) AddSession(session *ProxySession)
Registers a session with the manager. Thread-safe.
​
session
*ProxySession
required
The proxy session to track.

​
CloseAll

func (pm *ProxyManager) CloseAll()
Closes all registered sessions and removes them from the manager. Thread-safe.

​
WaitAll

func (pm *ProxyManager) WaitAll()
Blocks until all registered sessions have closed. Thread-safe. 
pm := sprites.NewProxyManager()

sessions, err := client.ProxyPorts(ctx, "my-sprite", []sprites.PortMapping{
    {LocalPort: 5432, RemotePort: 5432},
    {LocalPort: 6379, RemotePort: 6379},
})
if err != nil {
    log.Fatal(err)
}
for _, s := range sessions {
    pm.AddSession(s)
}

// Shut everything down cleanly on exit
defer pm.CloseAll()
pm.WaitAll()

Build docs developers (and LLMs) love

Get started for freeTalk to us