> For the complete documentation index, see [llms.txt](https://docs.computesdk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.computesdk.com/providers/namespace.md).

# Namespace

Namespace provider for ComputeSDK - Deploy and manage containerized sandboxes on Namespace's cloud infrastructure.

## Installation & Setup

```bash
npm install @computesdk/namespace
```

Add your Namespace credentials to a `.env` file:

```bash
NSC_TOKEN=your_namespace_nsc_token
```

## Usage

```typescript
import { namespace } from '@computesdk/namespace';

const compute = namespace({
  token: process.env.NSC_TOKEN,
});

// Create a new sandbox
const sandbox = await compute.sandbox.create();
console.log(`Sandbox created: ${sandbox.sandboxId}`);

// Get sandbox info
const info = await sandbox.getInfo();
console.log(`Sandbox status: ${info.status}`);

// Clean up when done
await sandbox.destroy();
```

### Customizing Instance Resources

You can customize the compute resources allocated to your sandboxes:

```typescript
const compute = namespace({
  token: process.env.NSC_TOKEN,
  virtualCpu: 4,
  memoryMegabytes: 8192,
});

const sandbox = await compute.sandbox.create();
```

### Configuration Reference

| Option                | Environment Variable | Required | Description                                                                 |
| --------------------- | -------------------- | -------- | --------------------------------------------------------------------------- |
| `token`               | `NSC_TOKEN`          | Yes\*    | Your Namespace API token                                                    |
| `tokenFile`           | `NSC_TOKEN_FILE`     | Yes\*    | Path to a JSON token file (e.g. from `nsc login`) containing `bearer_token` |
| `virtualCpu`          | -                    | No       | Number of virtual CPU cores (default: 2)                                    |
| `memoryMegabytes`     | -                    | No       | Memory allocation in MB (default: 4096)                                     |
| `machineArch`         | -                    | No       | Machine architecture (default: 'amd64')                                     |
| `os`                  | -                    | No       | Operating system (default: 'linux')                                         |
| `documentedPurpose`   | -                    | No       | Documented purpose for the instance                                         |
| `destroyReason`       | -                    | No       | Reason recorded when destroying instances (default: 'ComputeSDK cleanup')   |
| `targetContainerName` | -                    | No       | Target container name for command execution (default: 'main-container')     |

\* Provide either `token` (or `NSC_TOKEN`) or `tokenFile` (or `NSC_TOKEN_FILE`).

```typescript
interface NamespaceConfig {
  /** Namespace API token - if not provided, uses NSC_TOKEN env var */
  token?: string;
  /** Path to a JSON token file (e.g. from `nsc login`) containing bearer_token - falls back to NSC_TOKEN_FILE */
  tokenFile?: string;
  /** Virtual CPU cores for the instance (default: 2) */
  virtualCpu?: number;
  /** Memory in megabytes for the instance (default: 4096) */
  memoryMegabytes?: number;
  /** Machine architecture (default: 'amd64') */
  machineArch?: string;
  /** Operating system (default: 'linux') */
  os?: string;
  /** Documented purpose for the instance */
  documentedPurpose?: string;
  /** Reason for destroying instances (default: 'ComputeSDK cleanup') */
  destroyReason?: string;
  /** Target container name for command execution (default: 'main-container') */
  targetContainerName?: string;
}
```

## Next Steps

* Learn about [sandbox lifecycle management](https://github.com/computesdk/computesdk/tree/main/docs/reference/compute.sandbox)
* Explore [Sandbox methods](https://github.com/computesdk/computesdk/tree/main/docs/reference/sandbox/README.md)
* View the [@computesdk/namespace package](https://github.com/computesdk/computesdk/blob/main/packages/namespace/README.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.computesdk.com/providers/namespace.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.