> ## 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.

# Installation

> Install the Declaw Python, TypeScript, or Go SDK, configure your connection, and verify your setup against a running Declaw instance.

## Requirements

| SDK        | Runtime requirement  |
| ---------- | -------------------- |
| Python     | Python 3.10 or later |
| TypeScript | Node.js 18 or later  |
| Go         | Go 1.22 or later     |

You also need a Declaw API key. Sign up at [declaw.ai](https://declaw.ai) to use Declaw Cloud, or see the [Deployment overview](/deployment/overview) for enterprise on-prem options.

***

## Install

<Tabs>
  <Tab title="Python">
    <Snippet file="snippets/install-python.mdx" />

    This installs both the synchronous (`Sandbox`) and asynchronous (`AsyncSandbox`) clients, along with all security policy types and model classes.

    To install a specific version:

    ```bash theme={null}
    pip install "declaw==0.1.0"
    ```

    To add it to a `pyproject.toml` project:

    ```bash theme={null}
    uv add declaw
    # or
    poetry add declaw
    ```
  </Tab>

  <Tab title="TypeScript">
    <Snippet file="snippets/install-typescript.mdx" />

    The package ships with full TypeScript types.

    With yarn or pnpm:

    ```bash theme={null}
    yarn add @declaw/sdk
    pnpm add @declaw/sdk
    ```

    The SDK is an ES module. Your `tsconfig.json` should include `"moduleResolution": "node16"` or `"bundler"`.
  </Tab>

  <Tab title="Go">
    <Snippet file="snippets/install-go.mdx" />

    Add it to your `go.mod`:

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

    All operations take a `context.Context` for cancellation and timeouts. Configuration is read from environment variables by default.
  </Tab>
</Tabs>

***

## Configuration

The SDK connects to a Declaw API server. You configure the connection either through environment variables (recommended) or programmatically via `ConnectionConfig`.

### Environment variables

<Snippet file="snippets/env-setup.mdx" />

| Variable         | Description                                                                                                                                                                        |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DECLAW_API_KEY` | API key sent as the `X-API-Key` header on every request. Get one from your dashboard at [declaw.ai](https://declaw.ai).                                                            |
| `DECLAW_DOMAIN`  | Hostname of the Declaw API server. Defaults to `api.declaw.ai` for Declaw Cloud. Enterprise on-prem customers will receive their own domain. Do not include the `https://` scheme. |

When these variables are set, you can call `Sandbox.create()` without any arguments:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from declaw import Sandbox

    # Picks up DECLAW_API_KEY and DECLAW_DOMAIN from the environment
    sbx = Sandbox.create(template="python", timeout=300)
    sbx.kill()
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { Sandbox } from "@declaw/sdk";

    // Picks up DECLAW_API_KEY and DECLAW_DOMAIN from the environment
    const sbx = await Sandbox.create({ template: "python", timeout: 300 });
    await sbx.kill();
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    import "github.com/declaw-ai/declaw-go"

    // Picks up DECLAW_API_KEY and DECLAW_DOMAIN from the environment
    sbx, err := declaw.Create(ctx,
        declaw.WithTemplate("python"),
        declaw.WithTimeout(300),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer sbx.Kill(ctx)
    ```
  </Tab>
</Tabs>

### Explicit ConnectionConfig

Pass a `ConnectionConfig` directly when you need multiple connections, non-standard ports, or explicit control over credentials:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from declaw import Sandbox, ConnectionConfig

    config = ConnectionConfig(
        api_key="your-api-key",
        domain="my-vm.example.com:8080",
    )

    sbx = Sandbox.create(template="python", timeout=300, connection_config=config)
    sbx.kill()
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { Sandbox, ConnectionConfig } from "@declaw/sdk";

    const config = new ConnectionConfig({
      apiKey: "your-api-key",
      domain: "my-vm.example.com:8080",
    });

    const sbx = await Sandbox.create({
      template: "python",
      timeout: 300,
      connectionConfig: config,
    });
    await sbx.kill();
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    import "github.com/declaw-ai/declaw-go"

    // Sandbox creation accepts SandboxOption functions directly
    sbx, err := declaw.Create(ctx,
        declaw.WithTemplate("python"),
        declaw.WithTimeout(300),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer sbx.Kill(ctx)

    // Account-level operations use ConfigOption functions
    account := declaw.NewAccountClient(
        declaw.WithAPIKey("your-api-key"),
        declaw.WithAPIURL("http://my-vm.example.com:8080"),
    )
    info, err := account.GetAccount(ctx)
    ```
  </Tab>
</Tabs>

### Timeout

The `timeout` parameter on `Sandbox.create()` sets the maximum lifetime of the sandbox in seconds. If the sandbox is not killed before the timeout, the server destroys it automatically. The default is 300 seconds (5 minutes).

<Warning>
  Always call `sbx.kill()` in a `finally` block. If your process crashes before calling `kill()`, the sandbox lives until its timeout expires and continues consuming server resources.
</Warning>

***

## Verify your setup

After installing the SDK and setting your environment variables, run a quick smoke test:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from declaw import Sandbox

    sbx = Sandbox.create(template="python", timeout=60)
    try:
        result = sbx.commands.run("uname -a")
        print(result.stdout)
        assert result.exit_code == 0
        print("Declaw is working correctly.")
    finally:
        sbx.kill()
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { Sandbox } from "@declaw/sdk";

    const sbx = await Sandbox.create({ template: "python", timeout: 60 });
    try {
      const result = await sbx.commands.run("uname -a");
      console.log(result.stdout);
      if (result.exitCode !== 0) throw new Error("Unexpected exit code");
      console.log("Declaw is working correctly.");
    } finally {
      await sbx.kill();
    }
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    package main

    import (
        "context"
        "fmt"
        "log"

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

    func main() {
        ctx := context.Background()
        sbx, err := declaw.Create(ctx,
            declaw.WithTemplate("python"),
            declaw.WithTimeout(60),
        )
        if err != nil {
            log.Fatal(err)
        }
        defer sbx.Kill(ctx)

        result, err := sbx.Commands.Run(ctx, "uname -a")
        if err != nil {
            log.Fatal(err)
        }
        fmt.Println(result.Stdout)
        fmt.Println("Declaw is working correctly.")
    }
    ```
  </Tab>
</Tabs>

If you see a Linux kernel string in the output, your SDK is connected and sandboxes are booting correctly.

***

## Common errors

| Error (Python/TS → Go)                             | Cause                                                  | Fix                                                                     |
| -------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------- |
| `AuthenticationException` / `*AuthenticationError` | `DECLAW_API_KEY` is missing or invalid                 | Set the correct key in your environment or config                       |
| `Connection refused`                               | `DECLAW_DOMAIN` points to an unreachable server        | Verify the server is running and the domain/port are correct            |
| `NotFoundException` / `*NotFoundError`             | Sandbox ID does not exist (e.g., it already timed out) | Re-create the sandbox; check your timeout value                         |
| `TimeoutException` / `*TimeoutError`               | A command exceeded its timeout                         | Increase `timeout` on the run call or break the work into smaller steps |

***

## Next steps

* [Quickstart](/quickstart) — five-minute tutorial covering sandboxes, commands, filesystem, and security policies
* [Deployment overview](/deployment/overview) — stand up a Declaw server on GCP, AWS, Docker, or bare metal
* [Python SDK reference](/sdks/python/overview) — full API reference for the Python client
* [TypeScript SDK reference](/sdks/typescript/overview) — full API reference for the TypeScript client
* [Go SDK reference](/sdks/go/overview) — full API reference for the Go client