Go API reference

Import github.com/hyperterse/sandboxer/sdks/go. The implementation lives in sdks/go/core/. Add a blank import of github.com/hyperterse/sandboxer/sdks/go/providers so each backend registers when the process starts.

You pick a provider (for example local Docker or a hosted sandbox API). The client talks to that host directly. There is no separate Sandboxer server in the request path.

import (
    "github.com/hyperterse/sandboxer/sdks/go"
    _ "github.com/hyperterse/sandboxer/sdks/go/providers"
)

The sections below mirror the library: provider → sandbox (lifecycle, commands, files, PTY) → package-level helpers. Each API below includes a short summary, parameters, an example, and source links.

Provider — ListSandboxes · CreateSandbox · AttachSandbox · KillSandbox · Close

Sandbox — lifecycle — ID · Info · IsRunning · Pause · Resume · Kill · PortURL

Sandbox — commands — RunCommand · StartCommand · WaitForHandle · KillProcess · ListProcesses

Sandbox — filesystem — ReadFile · WriteFile · ListDirectory · MakeDir · Remove · Exists

Sandbox — PTY — CreatePTY · ResizePTY · KillPTY · ListPTY

Package helpers — ConnectSandbox · RunCommand · ReadFile · WriteFile · CreatePTY

More — Configuration · Providers · Errors

Provider

Types: Provider, CreateSandboxRequest, ListSandboxesFilter.

`ListSandboxes`

Description. Returns sandbox metadata visible to this provider / credential.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`filter`	`ListSandboxesFilter`	yes	`Provider`, `MetadataFilter`, `Limit` (use zero values when unused).

Example.

list, err := p.ListSandboxes(ctx, sandboxer.ListSandboxesFilter{Limit: 50})

References

Reference
`core/provider.go`
`core/catalog.go` (filter struct)

`CreateSandbox`

Description. Provisions and starts a sandbox; returns a live Sandbox handle plus SandboxInfo.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`req`	`CreateSandboxRequest`	yes	`Provider` (required), optional `Template`, `TimeoutSeconds`, `Metadata`, `Envs`, `CPUs`, `MemoryMb`, `AutoDestroy`.

Example.

sb, info, err := p.CreateSandbox(ctx, sandboxer.CreateSandboxRequest{
    Provider: sandboxer.ProviderLocal,
    TimeoutSeconds: sandboxer.Ptr(600),
})
defer sb.Kill(ctx)

References

Reference
`core/provider.go`
`core/sandbox.go`

`AttachSandbox`

Description. Reconnects to an existing sandbox by provider id.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`sandboxID`	`string`	yes	Id from the provider or prior `SandboxInfo`.

Example.

sb, err := p.AttachSandbox(ctx, info.ID)

References

Reference
`core/provider.go`

`KillSandbox`

Description. Destroys a sandbox by id without holding a Sandbox handle.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`sandboxID`	`string`	yes	Target sandbox id.

Example.

if err := p.KillSandbox(ctx, sid); err != nil { ... }

References

Reference
`core/provider.go`

`Close`

Description. Releases provider-held HTTP clients, watchers, or other resources.

Parameter	Type	Required	Description
(none)

Example.

defer p.Close()

References

Reference
`core/provider.go`

Sandbox

See Sandbox. Request types: RunCommandRequest, StartCommandRequest, CreatePTYRequest.

`ID`

Description. Stable identifier for this sandbox session.

Parameter	Type	Required	Description
(none)

Example.

id := sb.ID()

References

Reference
`core/sandbox.go`

`Info`

Description. Fetches current metadata and status from the provider.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.

Example.

info, err := sb.Info(ctx)

References

Reference
`core/sandbox.go`

`IsRunning`

Description. Whether the sandbox is in a running state.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.

Example.

ok, err := sb.IsRunning(ctx)

References

Reference
`core/sandbox.go`

`Pause`

Description. Pauses execution when the backend supports it (ErrNotSupported otherwise).

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.

Example.

err := sb.Pause(ctx)

References

Reference
`core/sandbox.go`

`Resume`

Description. Resumes a paused sandbox when supported.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.

Example.

err := sb.Resume(ctx)

References

Reference
`core/sandbox.go`

`Kill`

Description. Terminates this sandbox from the handle you hold.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.

Example.

defer sb.Kill(ctx)

References

Reference
`core/sandbox.go`

`PortURL`

Description. Returns a URL that reaches port inside the sandbox when tunneling / preview URLs exist.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`port`	`int`	yes	Exposed port number.

Example.

u, err := sb.PortURL(ctx, 8080)

References

Reference
`core/sandbox.go`

`RunCommand`

Description. Runs a shell command synchronously; blocks until exit.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`req`	`RunCommandRequest`	yes	`Cmd` required; optional `Cwd`, `Env`, `TimeoutSeconds`, `User`.

Example.

res, err := sb.RunCommand(ctx, sandboxer.RunCommandRequest{
    Cmd: "npm test",
    TimeoutSeconds: sandboxer.Ptr(120),
})
fmt.Println(res.ExitCode, res.Stdout)

References

Reference
`core/sandbox.go`
`core/command.go`

`StartCommand`

Description. Starts a command asynchronously; returns OS pid and provider handle id for WaitForHandle.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`req`	`StartCommandRequest`	yes	`Cmd` required; optional `Cwd`, `Env`, `User`.

Example.

pid, handle, err := sb.StartCommand(ctx, sandboxer.StartCommandRequest{Cmd: "sleep 30"})
res, err := sb.WaitForHandle(ctx, handle)

References

Reference
`core/sandbox.go`

`WaitForHandle`

Description. Blocks until an async command identified by handleID completes.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`handleID`	`string`	yes	Handle from `StartCommand`.

Example.

res, err := sb.WaitForHandle(ctx, handle)

References

Reference
`core/sandbox.go`

`KillProcess`

Description. Sends SIGKILL (or equivalent) to a process inside the sandbox.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`pid`	`int`	yes	Process id in the guest.

Example.

err := sb.KillProcess(ctx, pid)

References

Reference
`core/sandbox.go`

`ListProcesses`

Description. Lists processes the provider exposes for this sandbox.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.

Example.

procs, err := sb.ListProcesses(ctx)

References

Reference
`core/sandbox.go`

`ReadFile`

Description. Reads a file as raw bytes (no base64 layer unlike HTTP SDKs).

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`path`	`string`	yes	Absolute guest path.

Example.

b, err := sb.ReadFile(ctx, "/etc/hostname")

References

Reference
`core/sandbox.go`

`WriteFile`

Description. Writes bytes to a path, optionally with unix mode and user.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`path`	`string`	yes	Destination path.
`content`	`[]byte`	yes	File bytes.
`mode`	`*int`	no	Unix mode bits when supported.
`user`	`*string`	no	File owner hint when supported.

Example.

err := sb.WriteFile(ctx, "note.txt", []byte("hello"), nil, nil)

References

Reference
`core/sandbox.go`

`ListDirectory`

Description. Lists directory entries with metadata.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`path`	`string`	yes	Directory path.

Example.

entries, err := sb.ListDirectory(ctx, "/app")

References

Reference
`core/sandbox.go`

`MakeDir`

Description. Creates a directory (and parents if the provider allows).

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`path`	`string`	yes	Directory path.

Example.

err := sb.MakeDir(ctx, "/tmp/work")

References

Reference
`core/sandbox.go`

`Remove`

Description. Deletes a file or empty/non-empty tree per provider rules.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`path`	`string`	yes	Path to remove.

Example.

err := sb.Remove(ctx, "/tmp/old")

References

Reference
`core/sandbox.go`

`Exists`

Description. Returns whether the path exists in the guest filesystem.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`path`	`string`	yes	Path to test.

Example.

ok, err := sb.Exists(ctx, "/app/package.json")

References

Reference
`core/sandbox.go`

`CreatePTY`

Description. Allocates an interactive PTY session; optional initial Command and geometry.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`req`	`CreatePTYRequest`	yes	Optional `Rows`, `Cols`, `Cwd`, `Env`, `User`, `Command`.

Example.

pty, err := sb.CreatePTY(ctx, sandboxer.CreatePTYRequest{
    Rows: sandboxer.Ptr(24), Cols: sandboxer.Ptr(80),
})

References

Reference
`core/sandbox.go`
`core/pty.go`

`ResizePTY`

Description. Updates terminal rows/columns for an existing PTY.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`pid`	`int`	yes	PTY pid from `CreatePTY` / `ListPTY`.
`rows`, `cols`	`int`	yes	New geometry.

Example.

err := sb.ResizePTY(ctx, pty.Pid, 30, 100)

References

Reference
`core/sandbox.go`

`KillPTY`

Description. Closes the PTY session identified by pid.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`pid`	`int`	yes	PTY process id.

Example.

err := sb.KillPTY(ctx, pty.Pid)

References

Reference
`core/sandbox.go`

`ListPTY`

Description. Enumerates active PTY sessions for this sandbox.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.

Example.

list, err := sb.ListPTY(ctx)

References

Reference
`core/sandbox.go`

Package-level helpers

sandboxer.go — thin wrappers over a Sandbox.

`ConnectSandbox`

Description. Attaches to an existing sandbox by id; same as Provider.AttachSandbox, exposed as a package-level helper for shorter call sites.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`p`	`Provider`	yes	Backend instance.
`sandboxID`	`string`	yes	Existing sandbox id.

Example.

sb, err := sandboxer.ConnectSandbox(ctx, p, id)

References

Reference
`sandboxer.go`
`core/sandbox.go`

`RunCommand` (package)

Description. Delegates to s.RunCommand(ctx, req).

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`s`	`Sandbox`	yes	Target sandbox.
`req`	`RunCommandRequest`	yes	Command spec.

Example.

res, err := sandboxer.RunCommand(ctx, sb, sandboxer.RunCommandRequest{Cmd: "whoami"})

References

Reference
`sandboxer.go`
`core/command.go`

`ReadFile` (package)

Description. Delegates to s.ReadFile(ctx, path).

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`s`	`Sandbox`	yes	Target sandbox.
`path`	`string`	yes	Guest path.

Example.

b, err := sandboxer.ReadFile(ctx, sb, "/tmp/log.txt")

References

Reference
`sandboxer.go`

`WriteFile` (package)

Description. Delegates to s.WriteFile.

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`s`	`Sandbox`	yes	Target sandbox.
`path`	`string`	yes	Guest path.
`content`	`[]byte`	yes	Bytes to write.
`mode`	`*int`	no	Unix mode.
`user`	`*string`	no	Owner hint.

Example.

err := sandboxer.WriteFile(ctx, sb, "f.txt", []byte("x"), nil, nil)

References

Reference
`sandboxer.go`

`CreatePTY` (package)

Description. Delegates to s.CreatePTY(ctx, req).

Parameter	Type	Required	Description
`ctx`	`context.Context`	yes	Cancel and timeout handling.
`s`	`Sandbox`	yes	Target sandbox.
`req`	`CreatePTYRequest`	yes	PTY options.

Example.

info, err := sandboxer.CreatePTY(ctx, sb, sandboxer.CreatePTYRequest{})

References

Reference
`sandboxer.go`
`core/pty.go`

Configuration

sandboxer.Config and environment variables such as SANDBOXER_PROVIDER, SANDBOXER_API_KEY, SANDBOXER_BASE_URL, SANDBOXER_DEFAULT_TIMEOUT, plus optional TLS and OAuth settings. These apply to this Go module only. Your application’s README or deployment guide should document the values you set in production.

Providers

Built-in names include ProviderLocal, ProviderE2B, ProviderDaytona, ProviderRunloop, ProviderFlyMachines, ProviderBlaxel. Map strings with ParseProviderName. Local expects docker on your PATH.

Errors

Sentinel errors in core/errors.go, including ErrNotFound, ErrUnauthorized, ErrNotSupported, and related values—use errors.Is / errors.As as usual.

FilesExpand file tree

reference-go.md

Latest commit

History

reference-go.md

File metadata and controls

Go API reference

Provider

ListSandboxes

CreateSandbox

AttachSandbox

KillSandbox

Close

Sandbox

ID

Info

IsRunning

Pause

Resume

Kill

PortURL

RunCommand

StartCommand

WaitForHandle

KillProcess

ListProcesses

ReadFile

WriteFile

ListDirectory

MakeDir

Remove

Exists

CreatePTY

ResizePTY

KillPTY

ListPTY

Package-level helpers

ConnectSandbox

RunCommand (package)

ReadFile (package)

WriteFile (package)

CreatePTY (package)

Configuration

Providers

Errors

`ListSandboxes`

`CreateSandbox`

`AttachSandbox`

`KillSandbox`

`Close`

`ID`

`Info`

`IsRunning`

`Pause`

`Resume`

`Kill`

`PortURL`

`RunCommand`

`StartCommand`

`WaitForHandle`

`KillProcess`

`ListProcesses`

`ReadFile`

`WriteFile`

`ListDirectory`

`MakeDir`

`Remove`

`Exists`

`CreatePTY`

`ResizePTY`

`KillPTY`

`ListPTY`

`ConnectSandbox`

`RunCommand` (package)

`ReadFile` (package)

`WriteFile` (package)

`CreatePTY` (package)