Add sandbox operations

Author: santicastro

README.md

@@ -130,6 +130,52 @@ stream.pipe(fs.createWriteStream('./downloaded.txt'));
 await storage.delete('myfile.txt');
 ```
 
+### 7. Sandboxes
+
+Create isolated sandboxes, then drive them with **gRPC**: run shell commands and manage files inside the sandbox VM. The SDK uses TLS to the sandbox `grpcServerUrl` and sends the API key in the `x-api-key` metadata header.
+
+```js
+const { YepCodeSandbox } = require('@yepcode/run');
+
+const sandboxes = new YepCodeSandbox({ apiToken: '****' });
+
+const instance = await sandboxes.create({
+  imageId: 'your-image-id', // required by the API
+  name: 'my-sandbox',
+  timeoutMs: 300_000,
+  publicHttpPorts: [8080],
+  // Traefik basicAuth `user:secret` — plain `user:password` or hashed (bcrypt $2y$/$2a$, Apache MD5 $apr1$, SHA-1)
+  publicHttpPortsBasicAuth: 'user:password',
+  metadata: { purpose: 'demo' },
+});
+
+// REST helpers on YepCodeSandbox (by sandbox id)
+// await sandboxes.updateTimeout(instance.data.id, { timeoutMs: 120_000 });
+// await sandboxes.kill(instance.data.id);
+
+// Instance API (REST + gRPC)
+await instance.updateTimeout({ timeoutMs: 120_000 });
+
+await instance.mkDir('/tmp/work');
+await instance.uploadFile('/tmp/work/hello.txt', Buffer.from('hello'));
+const bytes = await instance.downloadFile('/tmp/work/hello.txt');
+
+const run = await instance.runCommand({
+  command: 'pwd',
+  args: [],
+  workingDirectory: '/',
+  env: { MY_VAR: 'value' },
+});
+console.log(run.stdout.toString(), run.exitCode);
+
+await instance.kill();
+```
+
+**Behaviour notes**
+
+- `runCommand`, `uploadFile`, `mkDir`, and `downloadFile` wait until gRPC health reports **ready** (poll every 250 ms, up to **10 s**), then reuse that readiness for later calls on the same instance.
+- `instance.data` is the current **Sandbox** payload (`grpcServerUrl`, `grpcApiKey`, `id`, `imageId`, etc.); see [SandboxInstance](#sandboxinstance).
+
 ## Prompt to use if you are asking LLM to write code
 
 You can use the following prompt to ask LLM to write code that the YepCode Run SDK can execute.
@@ -392,6 +438,114 @@ interface Process {
 }
 ```
 
+### YepCodeSandbox
+
+High-level wrapper around [`YepCodeApi`](#yepcodeapi) for sandbox **REST** operations. `create` returns a [`SandboxInstance`](#sandboxinstance) bound to the same API client for `updateTimeout` / `kill` on that instance.
+
+#### Constructor
+
+```typescript
+constructor(config?: YepCodeApiConfig)
+```
+
+Uses the same options as [`YepCodeApi`](#yepcodeapi) (`apiToken`, `apiHost`, `teamId`, `clientId` / `clientSecret`, etc.).
+
+#### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `create(data: CreateSandboxInput)` | `Promise<SandboxInstance>` | Create sandbox and return a connected instance |
+| `updateTimeout(id: string, data: UpdateSandboxTimeoutInput)` | `Promise<Sandbox>` | Update timeout by sandbox **id** |
+| `kill(id: string)` | `Promise<Sandbox>` | Kill sandbox by **id** |
+
+```typescript
+interface CreateSandboxInput {
+  imageId: string;
+  name?: string;
+  metadata?: Record<string, string>;
+  timeoutMs?: number;
+  publicHttpPorts?: number[];
+  /**
+   * Traefik basicAuth `users` format: `username:passwordOrHash`.
+   * Plain `user:password` or hashed (Traefik: bcrypt `$2y$` / `$2a$`, Apache MD5 `$apr1$`, SHA-1).
+   */
+  publicHttpPortsBasicAuth?: string;
+}
+
+interface UpdateSandboxTimeoutInput {
+  timeoutMs: number;
+}
+```
+
+### SandboxInstance
+
+Represents one sandbox. **gRPC** is used for commands and in-VM file storage; **REST** (via the linked `YepCodeApi`) for `updateTimeout` and `kill`.
+
+#### `data` (getter)
+
+Current **Sandbox** record:
+
+```typescript
+interface Sandbox {
+  id: string;
+  name: string;
+  grpcServerUrl: string;
+  grpcApiKey: string;
+  imageId: string;
+  publicHttpPorts?: number[];
+  metadata?: Record<string, string>;
+  timeoutAt: string;
+}
+```
+
+#### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `updateTimeout(input: UpdateSandboxTimeoutInput)` | `Promise<SandboxInstance>` | Refresh timeout; updates `data` |
+| `kill()` | `Promise<SandboxInstance>` | Stop sandbox; updates `data` |
+| `runCommand(input: RunCommandInput)` | `Promise<RunCommandResult>` | gRPC `RunCommand` (streaming stdout/stderr); waits for health first |
+| `uploadFile(path: string, content: Buffer \| Uint8Array)` | `Promise<SandboxStorageUploadResult>` | gRPC client-streaming upload |
+| `mkDir(path: string)` | `Promise<SandboxStorageMkDirResult>` | gRPC `MakeDirectory` |
+| `downloadFile(path: string)` | `Promise<Buffer>` | gRPC server-streaming download |
+
+```typescript
+interface RunCommandInput {
+  command: string;
+  args?: string[];
+  workingDirectory?: string;
+  env?: Record<string, string>;
+  background?: boolean;
+  timeoutSeconds?: number;
+}
+
+interface RunCommandResult {
+  pid?: number;
+  startedAt?: number;
+  stdout: Buffer;
+  stderr: Buffer;
+  exitCode?: number;
+  exited?: boolean;
+  status?: number;
+  error?: string;
+  endStartedAt?: number;
+  finishedAt?: number;
+}
+
+interface SandboxStorageUploadResult {
+  success: boolean;
+  absolutePath?: string;
+  bytesWritten?: number;
+  errorMessage?: string;
+}
+
+interface SandboxStorageMkDirResult {
+  success: boolean;
+  absolutePath?: string;
+  errorMessage?: string;
+}
+```
+
 ### YepCodeStorage
 
 Manages file storage in your YepCode workspace. Allows you to upload, list, download, and delete files using the YepCode API.