> ## Documentation Index
> Fetch the complete documentation index at: https://docs.declaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Go SDK

> Install the Declaw Go SDK and connect to the API using Config, functional options, and environment variables.

The Declaw Go SDK is available as a Go module and supports Go 1.22+.

## Installation

```bash theme={null}
go get github.com/declaw-ai/declaw-go
```

## Environment variables

The SDK reads connection settings from environment variables by default.

```bash theme={null}
export DECLAW_API_KEY="your-api-key"
export DECLAW_DOMAIN="api.declaw.ai"      # or your enterprise on-prem domain
export DECLAW_API_URL="https://api.declaw.ai"  # optional full URL override
```

## Config

`Config` holds the credentials and endpoint used by every API call. The SDK builds it automatically from environment variables — you rarely need to construct one directly. Use `NewConfig()` with functional options when you need explicit control.

```go theme={null}
import "github.com/declaw-ai/declaw-go"

cfg := declaw.NewConfig(
    declaw.WithAPIKey("your-api-key"),
    declaw.WithDomain("api.declaw.ai"),
)
```

<ParamField body="APIKey" type="string" default="$DECLAW_API_KEY">
  API key sent as the `Authorization: Bearer` header on every request. Defaults
  to the `DECLAW_API_KEY` environment variable.
</ParamField>

<ParamField body="Domain" type="string" default="$DECLAW_DOMAIN or api.declaw.ai">
  Hostname of the Declaw API server. Defaults to the `DECLAW_DOMAIN`
  environment variable, falling back to `api.declaw.ai`.
</ParamField>

<ParamField body="Port" type="int" default="443">
  API server port. HTTPS for 443, HTTP for 80.
</ParamField>

<ParamField body="APIURL" type="string" default="$DECLAW_API_URL">
  Full URL override (e.g. `http://localhost:8080`). When set, `Domain` and
  `Port` are not used to construct the URL.
</ParamField>

<ParamField body="RequestTimeout" type="time.Duration" default="0 (no timeout)">
  Default per-request timeout applied to all HTTP calls made with this config.
</ParamField>

### ConfigOption functions

| Function                | Description                     |
| ----------------------- | ------------------------------- |
| `WithAPIKey(key)`       | Set the API key                 |
| `WithDomain(domain)`    | Set the API domain              |
| `WithAPIURL(url)`       | Set a full URL override         |
| `WithRequestTimeout(d)` | Set the default request timeout |

## Quick example

```go theme={null}
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/declaw-ai/declaw-go"
)

func main() {
    ctx := context.Background()

    // Create a sandbox (picks up DECLAW_API_KEY and DECLAW_API_URL from env)
    sbx, err := declaw.Create(ctx,
        declaw.WithTemplate("python"),
        declaw.WithTimeout(300),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer sbx.Kill(ctx)

    // Run a command
    result, err := sbx.Commands.Run(ctx, "echo 'Hello from Declaw!'")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Stdout)   // Hello from Declaw!
    fmt.Println(result.ExitCode) // 0
}
```

## What's exported

The top-level `declaw` package exports all public types and functions:

```go theme={null}
import "github.com/declaw-ai/declaw-go"

// Sandbox lifecycle
declaw.Create()
declaw.Connect()
declaw.ListSandboxes()
declaw.KillSandbox()
declaw.KillManySandboxes()
declaw.Restore()

// Templates
declaw.BuildTemplate()
declaw.BuildTemplateBackground()
declaw.GetBuildStatus()
declaw.ListTemplates()
declaw.GetTemplate()
declaw.DeleteTemplate()

// Volumes
declaw.CreateVolume()
declaw.ListVolumes()
declaw.GetVolume()
declaw.DownloadVolume()
declaw.DeleteVolume()

// Account management
declaw.NewAccountClient()

// Sub-objects on Sandbox
sbx.Commands   // *Commands
sbx.Files      // *Filesystem
sbx.PTY        // *PTY

// Security policy types
declaw.SecurityPolicy{}
declaw.PIIConfig{}
declaw.InjectionDefenseConfig{}
declaw.NetworkPolicy{}
declaw.TransformationRule{}
declaw.AuditConfig{}
declaw.EnvSecurityConfig{}
declaw.ToxicityConfig{}
declaw.CodeSecurityConfig{}
declaw.InvisibleTextConfig{}

// Models
declaw.SandboxInfo{}
declaw.SandboxMetrics{}
declaw.CommandResult{}
declaw.ProcessInfo{}
declaw.EntryInfo{}
declaw.WriteInfo{}
declaw.WriteEntry{}
declaw.PtySize{}
declaw.SnapshotInfo{}
declaw.SandboxPage{}
declaw.KillResult{}
declaw.VolumeInfo{}
declaw.VolumeAttachment{}
declaw.TemplateSpec{}
declaw.TemplateInfo{}
declaw.BuildInfo{}
declaw.CopyItem{}
declaw.SandboxLifecycle{}

// Network
declaw.SandboxNetworkOpts{}
declaw.AllTraffic          // "*"
declaw.DomainMatches()

// Constants
declaw.StateLive / StatePaused / StateKilled
declaw.FileTypeFile / FileTypeDirectory / FileTypeSymlink / FileTypeOther

// Error types
declaw.SandboxError{}
declaw.TimeoutError{}
declaw.NotFoundError{}
declaw.AuthenticationError{}
declaw.InvalidArgumentError{}
declaw.NotEnoughSpaceError{}
declaw.InsufficientBalanceError{}
declaw.RateLimitError{}
declaw.CommandExitError{}
declaw.TemplateError{}
declaw.BuildError{}
declaw.FileUploadError{}
declaw.GitAuthError{}
declaw.GitUpstreamError{}
```