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

# Sandbox Lifecycle

> Walk through the full lifecycle of a Declaw sandbox: create, inspect, extend timeout, and destroy.

## What You'll Learn

* Creating a sandbox with metadata and environment variables
* Retrieving sandbox info (`id`, `state`, `template`) with `get_info()` / `getInfo()`
* Checking whether a sandbox is running with `is_running()` / `isRunning()`
* Verifying that environment variables are set inside the sandbox
* Extending the sandbox timeout with `set_timeout()` / `setTimeout()`
* Killing the sandbox and confirming it stopped

## Prerequisites

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

## Code Walkthrough

<Tabs>
  <Tab title="Python">
    Create a sandbox with `metadata` and `envs`:

    ```python theme={null}
    from declaw import Sandbox

    sbx = Sandbox.create(
        template="base",
        timeout=300,
        metadata={"project": "demo", "env": "test"},
        envs={"MY_VAR": "hello"},
    )
    ```

    Inspect the sandbox with `get_info()` and check its running state:

    ```python theme={null}
    info = sbx.get_info()
    print(f"  sandbox_id: {info.sandbox_id}")
    print(f"  state:      {info.state}")
    print(f"  template:   {info.template_id}")

    running = sbx.is_running()
    assert running, "Sandbox should be running after creation"
    ```

    Verify environment variables by running a command inside the sandbox:

    ```python theme={null}
    result = sbx.commands.run("echo $MY_VAR", envs={"MY_VAR": "hello"})
    print(f"  MY_VAR = {result.stdout.strip()}")
    ```

    Extend the timeout and then kill:

    ```python theme={null}
    sbx.set_timeout(600)
    print("  Timeout extended to 600 seconds.")

    killed = sbx.kill()
    running_after = sbx.is_running()
    assert not running_after, "Sandbox should not be running after kill"
    ```

    Always wrap in `try/finally` — `kill()` is idempotent:

    ```python theme={null}
    try:
        # ... all sandbox work ...
    finally:
        sbx.kill()  # safe to call even if already killed
    ```
  </Tab>

  <Tab title="TypeScript">
    Create a sandbox with `metadata` and `envs`:

    ```typescript theme={null}
    import { Sandbox } from "@declaw/sdk";

    const sbx = await Sandbox.create({
      template: "base",
      timeout: 300,
      metadata: { project: "demo", env: "test" },
      envs: { MY_VAR: "hello" },
    });
    ```

    Inspect the sandbox with `getInfo()` and check running state:

    ```typescript theme={null}
    const info = await sbx.getInfo();
    console.log(`  sandbox_id: ${info.sandboxId}`);
    console.log(`  state:      ${info.state}`);
    console.log(`  template:   ${info.templateId}`);

    const running = await sbx.isRunning();
    if (!running) throw new Error("Sandbox should be running after creation");
    ```

    Verify environment variables and extend timeout:

    ```typescript theme={null}
    const result = await sbx.commands.run("echo $MY_VAR");
    console.log(`  MY_VAR = ${result.stdout.trim()}`);

    await sbx.setTimeout(600);
    console.log("  Timeout extended to 600 seconds.");
    ```

    Kill and verify:

    ```typescript theme={null}
    const killed = await sbx.kill();
    const runningAfter = await sbx.isRunning();
    // runningAfter === false
    ```
  </Tab>
</Tabs>

## Expected Output

```
==================================================
Declaw Sandbox Lifecycle Example
==================================================

--- Creating Sandbox ---
Sandbox created: sbx_abc123

--- Getting Sandbox Info ---
  sandbox_id: sbx_abc123
  state:      running
  template:   base

--- Checking if Running ---
  is_running: True

--- Running Command with Environment Variables ---
  MY_VAR = hello

--- Extending Timeout ---
  Timeout extended to 600 seconds.

--- Killing Sandbox ---
  kill returned: True

--- Verifying Sandbox Stopped ---
  is_running: False

==================================================
Done!
==================================================
```