apps/docs/src/content/docs/en/go-sdk/options.mdx
import "github.com/daytonaio/daytona/libs/sdk-go/pkg/options"
Package options provides functional option types for configuring SDK operations.
This package uses the functional options pattern to provide a clean, extensible API for configuring optional parameters. Each option function returns a closure that modifies the corresponding options struct.
Options are passed as variadic arguments to SDK methods:
err := sandbox.Git.Clone(ctx, url, path,
options.WithBranch("develop"),
options.WithUsername("user"),
options.WithPassword("token"),
)
The Apply function creates a new options struct and applies all provided option functions to it:
opts := options.Apply(
options.WithBranch("main"),
options.WithUsername("user"),
)
// opts.Branch == "main", opts.Username == "user"
<a name="Apply"></a>
func Apply[T any](opts ...func(*T)) *T
Apply creates a new instance of type T and applies all provided option functions.
This generic function enables a consistent pattern for applying functional options across different option types. It allocates a zero-value instance of T, then applies each option function in order.
Example:
opts := options.Apply(
options.WithBranch("main"),
options.WithUsername("user"),
)
<a name="WithAllowEmpty"></a>
func WithAllowEmpty(allowEmpty bool) func(*GitCommit)
WithAllowEmpty allows creating a commit even when there are no staged changes.
This is useful for triggering CI/CD pipelines or marking points in history without actual code changes.
Example:
resp, err := sandbox.Git.Commit(ctx, path, "Trigger rebuild", author, email,
options.WithAllowEmpty(true),
)
<a name="WithBranch"></a>
func WithBranch(branch string) func(*GitClone)
WithBranch sets the branch to clone instead of the repository's default branch.
Example:
err := sandbox.Git.Clone(ctx, url, path, options.WithBranch("develop"))
<a name="WithCodeRunLanguage"></a>
func WithCodeRunLanguage(language types.CodeLanguage) func(*CodeRun)
<a name="WithCodeRunParams"></a>
func WithCodeRunParams(params types.CodeRunParams) func(*CodeRun)
WithCodeRunParams sets the code execution parameters.
Example:
result, err := sandbox.Process.CodeRun(ctx, code,
options.WithCodeRunParams(types.CodeRunParams{Language: "python"}),
)
<a name="WithCodeRunTimeout"></a>
func WithCodeRunTimeout(timeout time.Duration) func(*CodeRun)
<a name="WithCommandEnv"></a>
func WithCommandEnv(env map[string]string) func(*ExecuteCommand)
WithCommandEnv sets environment variables for the command.
These variables are added to the command's environment in addition to the sandbox's default environment.
Example:
result, err := sandbox.Process.ExecuteCommand(ctx, "echo $MY_VAR",
options.WithCommandEnv(map[string]string{"MY_VAR": "hello"}),
)
<a name="WithCommitId"></a>
func WithCommitId(commitID string) func(*GitClone)
WithCommitId sets a specific commit SHA to checkout after cloning.
The repository is first cloned, then the specified commit is checked out, resulting in a detached HEAD state.
Example:
err := sandbox.Git.Clone(ctx, url, path, options.WithCommitId("abc123def"))
<a name="WithCreatePtyEnv"></a>
func WithCreatePtyEnv(env map[string]string) func(*CreatePty)
WithCreatePtyEnv sets environment variables for CreatePty.
Example:
handle, err := sandbox.Process.CreatePty(ctx, "my-pty",
options.WithCreatePtyEnv(map[string]string{"TERM": "xterm-256color"}),
)
<a name="WithCreatePtySize"></a>
func WithCreatePtySize(ptySize types.PtySize) func(*CreatePty)
WithCreatePtySize sets the PTY terminal dimensions for CreatePty.
Example:
handle, err := sandbox.Process.CreatePty(ctx, "my-pty",
options.WithCreatePtySize(types.PtySize{Rows: 24, Cols: 80}),
)
<a name="WithCustomContext"></a>
func WithCustomContext(contextID string) func(*RunCode)
WithCustomContext sets the interpreter context ID for code execution.
Using a context allows you to maintain state (variables, imports, etc.) across multiple code executions. Create a context with CreateContext first.
Example:
ctx, _ := sandbox.CodeInterpreter.CreateContext(ctx, nil)
channels, err := sandbox.CodeInterpreter.RunCode(ctx, "x = 42",
options.WithCustomContext(ctx["id"].(string)),
)
<a name="WithCwd"></a>
func WithCwd(cwd string) func(*ExecuteCommand)
WithCwd sets the working directory for command execution.
Example:
result, err := sandbox.Process.ExecuteCommand(ctx, "ls -la",
options.WithCwd("/home/user/project"),
)
<a name="WithEnv"></a>
func WithEnv(env map[string]string) func(*RunCode)
WithEnv sets environment variables for code execution.
These variables are available to the code during execution.
Example:
channels, err := sandbox.CodeInterpreter.RunCode(ctx, "import os; print(os.environ['API_KEY'])",
options.WithEnv(map[string]string{"API_KEY": "secret"}),
)
<a name="WithExecuteTimeout"></a>
func WithExecuteTimeout(timeout time.Duration) func(*ExecuteCommand)
WithExecuteTimeout sets the timeout for command execution.
If the command doesn't complete within the timeout, it will be terminated.
Example:
result, err := sandbox.Process.ExecuteCommand(ctx, "sleep 60",
options.WithExecuteTimeout(5*time.Second),
)
<a name="WithExtraIndexURLs"></a>
func WithExtraIndexURLs(urls ...string) func(*PipInstall)
WithExtraIndexURLs adds extra index URLs for pip install.
Extra indexes are checked in addition to the main index URL. Useful for installing packages from both PyPI and a private index.
Example:
image := daytona.Base("python:3.11").PipInstall(
[]string{"mypackage"},
options.WithExtraIndexURLs("https://private.example.com/simple/"),
)
<a name="WithExtraOptions"></a>
func WithExtraOptions(options string) func(*PipInstall)
WithExtraOptions adds extra command-line options for pip install.
Use this for pip options not covered by other With* functions.
Example:
image := daytona.Base("python:3.11").PipInstall(
[]string{"mypackage"},
options.WithExtraOptions("--no-cache-dir --upgrade"),
)
<a name="WithFindLinks"></a>
func WithFindLinks(links ...string) func(*PipInstall)
WithFindLinks adds find-links URLs for pip install.
Find-links URLs are searched for packages before the package index. Useful for installing packages from local directories or custom URLs.
Example:
image := daytona.Base("python:3.11").PipInstall(
[]string{"mypackage"},
options.WithFindLinks("/path/to/wheels", "https://example.com/wheels/"),
)
<a name="WithForce"></a>
func WithForce(force bool) func(*GitDeleteBranch)
WithForce enables force deletion of a branch even if it's not fully merged.
Use with caution as this can result in lost commits if the branch contains work that hasn't been merged elsewhere.
Example:
err := sandbox.Git.DeleteBranch(ctx, path, "feature/abandoned",
options.WithForce(true),
)
<a name="WithGroup"></a>
func WithGroup(group string) func(*SetFilePermissions)
WithGroup sets the file group.
The group should be a valid group name on the sandbox system.
Example:
err := sandbox.FileSystem.SetFilePermissions(ctx, "/home/user/file.txt",
options.WithGroup("users"),
)
<a name="WithIndexURL"></a>
func WithIndexURL(url string) func(*PipInstall)
WithIndexURL sets the base URL of the Python Package Index.
Replaces the default PyPI (https://pypi.org/simple\) with a custom index.
Example:
image := daytona.Base("python:3.11").PipInstall(
[]string{"mypackage"},
options.WithIndexURL("https://my-pypi.example.com/simple/"),
)
<a name="WithInterpreterTimeout"></a>
func WithInterpreterTimeout(timeout time.Duration) func(*RunCode)
WithInterpreterTimeout sets the execution timeout for code.
If the code doesn't complete within the timeout, execution is terminated.
Example:
channels, err := sandbox.CodeInterpreter.RunCode(ctx, "import time; time.sleep(60)",
options.WithInterpreterTimeout(5*time.Second),
)
<a name="WithLogChannel"></a>
func WithLogChannel(logChannel chan string) func(*CreateSandbox)
WithLogChannel provides a channel for receiving build logs during sandbox creation.
When creating a sandbox from a custom image that requires building, build logs are streamed to the provided channel. The channel is closed when streaming completes. If no build is required, no logs are sent and the channel remains unused.
Example:
logChan := make(chan string)
go func() {
for log := range logChan {
fmt.Println(log)
}
}()
sandbox, err := client.Create(ctx, params,
options.WithLogChannel(logChan),
)
<a name="WithMode"></a>
func WithMode(mode string) func(*CreateFolder)
WithMode sets the Unix file permissions for the created folder.
The mode should be specified as an octal string (e.g., "0755", "0700"). If not specified, defaults to "0755".
Example:
err := sandbox.FileSystem.CreateFolder(ctx, "/home/user/mydir",
options.WithMode("0700"),
)
<a name="WithOwner"></a>
func WithOwner(owner string) func(*SetFilePermissions)
WithOwner sets the file owner.
The owner should be a valid username on the sandbox system.
Example:
err := sandbox.FileSystem.SetFilePermissions(ctx, "/home/user/file.txt",
options.WithOwner("root"),
)
<a name="WithPassword"></a>
func WithPassword(password string) func(*GitClone)
WithPassword sets the password or access token for HTTPS authentication when cloning.
For GitHub, use a Personal Access Token (PAT). For GitLab, use a Project Access Token or Personal Access Token. For Bitbucket, use an App Password.
Example:
err := sandbox.Git.Clone(ctx, url, path,
options.WithUsername("username"),
options.WithPassword("ghp_xxxxxxxxxxxx"),
)
<a name="WithPermissionMode"></a>
func WithPermissionMode(mode string) func(*SetFilePermissions)
WithPermissionMode sets the Unix file permissions.
The mode should be specified as an octal string (e.g., "0644", "0755").
Example:
err := sandbox.FileSystem.SetFilePermissions(ctx, "/home/user/file.txt",
options.WithPermissionMode("0644"),
)
<a name="WithPre"></a>
func WithPre() func(*PipInstall)
WithPre enables installation of pre-release and development versions.
Example:
image := daytona.Base("python:3.11").PipInstall(
[]string{"mypackage"},
options.WithPre(),
)
<a name="WithPtyEnv"></a>
func WithPtyEnv(env map[string]string) func(*PtySession)
WithPtyEnv sets environment variables for the PTY session.
Example:
session, err := sandbox.Process.CreatePtySession(ctx, "my-session",
options.WithPtyEnv(map[string]string{"TERM": "xterm-256color"}),
)
<a name="WithPtySize"></a>
func WithPtySize(size types.PtySize) func(*PtySession)
WithPtySize sets the PTY terminal dimensions.
Example:
session, err := sandbox.Process.CreatePtySession(ctx, "my-session",
options.WithPtySize(types.PtySize{Rows: 24, Cols: 80}),
)
<a name="WithPullPassword"></a>
func WithPullPassword(password string) func(*GitPull)
WithPullPassword sets the password or access token for HTTPS authentication when pulling.
Example:
err := sandbox.Git.Pull(ctx, path,
options.WithPullUsername("username"),
options.WithPullPassword("ghp_xxxxxxxxxxxx"),
)
<a name="WithPullUsername"></a>
func WithPullUsername(username string) func(*GitPull)
WithPullUsername sets the username for HTTPS authentication when pulling.
Example:
err := sandbox.Git.Pull(ctx, path,
options.WithPullUsername("username"),
options.WithPullPassword("github_token"),
)
<a name="WithPushPassword"></a>
func WithPushPassword(password string) func(*GitPush)
WithPushPassword sets the password or access token for HTTPS authentication when pushing.
Example:
err := sandbox.Git.Push(ctx, path,
options.WithPushUsername("username"),
options.WithPushPassword("ghp_xxxxxxxxxxxx"),
)
<a name="WithPushUsername"></a>
func WithPushUsername(username string) func(*GitPush)
WithPushUsername sets the username for HTTPS authentication when pushing.
Example:
err := sandbox.Git.Push(ctx, path,
options.WithPushUsername("username"),
options.WithPushPassword("github_token"),
)
<a name="WithTimeout"></a>
func WithTimeout(timeout time.Duration) func(*CreateSandbox)
WithTimeout sets the maximum duration to wait for sandbox creation to complete.
If the timeout is exceeded before the sandbox is ready, Create returns an error. The default timeout is 60 seconds.
Example:
sandbox, err := client.Create(ctx, params,
options.WithTimeout(5*time.Minute),
)
<a name="WithUsername"></a>
func WithUsername(username string) func(*GitClone)
WithUsername sets the username for HTTPS authentication when cloning.
For GitHub, GitLab, and similar services, the username is typically your account username or a placeholder like "git" when using tokens.
Example:
err := sandbox.Git.Clone(ctx, url, path,
options.WithUsername("username"),
options.WithPassword("github_token"),
)
<a name="WithWaitForStart"></a>
func WithWaitForStart(waitForStart bool) func(*CreateSandbox)
WithWaitForStart controls whether [daytona.Client.Create] waits for the sandbox to reach the started state before returning.
When true (the default), Create blocks until the sandbox is fully started and ready for use. When false, Create returns immediately after the sandbox is created, which may be in a pending or building state.
Example:
// Return immediately without waiting for the sandbox to start
sandbox, err := client.Create(ctx, params,
options.WithWaitForStart(false),
)
<a name="CodeRun"></a>
CodeRun holds optional parameters for [daytona.ProcessService.CodeRun].
type CodeRun struct {
Params *types.CodeRunParams // Code execution parameters
Timeout *time.Duration // Execution timeout
Language types.CodeLanguage // Override the default language
}
<a name="CreateFolder"></a>
CreateFolder holds optional parameters for [daytona.FileSystemService.CreateFolder].
type CreateFolder struct {
Mode *string // Unix file permissions (e.g., "0755")
}
<a name="CreatePty"></a>
CreatePty holds optional parameters for [daytona.ProcessService.CreatePty].
type CreatePty struct {
PtySize *types.PtySize // Terminal dimensions (rows and columns)
Env map[string]string // Environment variables for the PTY session
}
<a name="CreateSandbox"></a>
CreateSandbox holds optional parameters for [daytona.Client.Create].
type CreateSandbox struct {
Timeout *time.Duration // Maximum time to wait for sandbox creation
WaitForStart bool // Whether to wait for the sandbox to reach started state
LogChannel chan string // Channel for receiving build logs during image builds
}
<a name="ExecuteCommand"></a>
ExecuteCommand holds optional parameters for [daytona.ProcessService.ExecuteCommand].
type ExecuteCommand struct {
Cwd *string // Working directory for command execution
Env map[string]string // Environment variables
Timeout *time.Duration // Command execution timeout
}
<a name="GitClone"></a>
GitClone holds optional parameters for [daytona.GitService.Clone].
Fields are pointers to distinguish between unset values and zero values. Use the corresponding With* functions to set these options.
type GitClone struct {
Branch *string // Branch to clone (defaults to repository's default branch)
CommitId *string // Specific commit SHA to checkout after cloning
Username *string // Username for HTTPS authentication
Password *string // Password or token for HTTPS authentication
}
<a name="GitCommit"></a>
GitCommit holds optional parameters for [daytona.GitService.Commit].
type GitCommit struct {
AllowEmpty *bool // Allow creating commits with no staged changes
}
<a name="GitDeleteBranch"></a>
GitDeleteBranch holds optional parameters for [daytona.GitService.DeleteBranch].
type GitDeleteBranch struct {
Force *bool // Force delete even if branch is not fully merged
}
<a name="GitPull"></a>
GitPull holds optional parameters for [daytona.GitService.Pull].
type GitPull struct {
Username *string // Username for HTTPS authentication
Password *string // Password or token for HTTPS authentication
}
<a name="GitPush"></a>
GitPush holds optional parameters for [daytona.GitService.Push].
type GitPush struct {
Username *string // Username for HTTPS authentication
Password *string // Password or token for HTTPS authentication
}
<a name="PipInstall"></a>
PipInstall holds optional parameters for [daytona.Image.PipInstall].
type PipInstall struct {
FindLinks []string // URLs to search for packages
IndexURL string // Base URL of the Python Package Index
ExtraIndexURLs []string // Extra index URLs for package lookup
Pre bool // Allow pre-release and development versions
ExtraOptions string // Additional pip command-line options
}
<a name="PtySession"></a>
PtySession holds optional parameters for [daytona.ProcessService.CreatePtySession].
type PtySession struct {
PtySize *types.PtySize // Terminal dimensions (rows and columns)
Env map[string]string // Environment variables for the PTY session
}
<a name="RunCode"></a>
RunCode holds optional parameters for [daytona.CodeInterpreterService.RunCode].
type RunCode struct {
ContextID string // Interpreter context ID for persistent state
Env map[string]string // Environment variables for code execution
Timeout *time.Duration // Execution timeout
}
<a name="SetFilePermissions"></a>
SetFilePermissions holds optional parameters for [daytona.FileSystemService.SetFilePermissions].
type SetFilePermissions struct {
Mode *string // Unix file permissions (e.g., "0644")
Owner *string // File owner username
Group *string // File group name
}