From b1d088d50a8e2b304059204ff7a594ea1bb21f2a Mon Sep 17 00:00:00 2001 From: Parteek Singh Date: Mon, 12 Jan 2026 15:27:43 -0800 Subject: [PATCH 1/4] Updates - Fix inaccurate domain info in CLI commands - Add default resource configuration info - Add sandbox CLI commands - Remove legacy object storage CLI commands - Add CLI command for API key (authenticated) --- content/Reference/CLI/debugging.mdx | 3 + content/Reference/CLI/deployment.mdx | 32 ++-- content/Reference/CLI/getting-started.mdx | 8 + content/Reference/CLI/index.mdx | 2 +- content/Reference/CLI/sandbox.mdx | 183 +++++++++++++++++++++- content/Reference/CLI/storage.mdx | 57 ------- 6 files changed, 207 insertions(+), 78 deletions(-) diff --git a/content/Reference/CLI/debugging.mdx b/content/Reference/CLI/debugging.mdx index fc6fc3e8..1468e953 100644 --- a/content/Reference/CLI/debugging.mdx +++ b/content/Reference/CLI/debugging.mdx @@ -19,6 +19,9 @@ agentuity cloud ssh proj_abc123xyz # SSH into specific deployment agentuity cloud ssh dep_abc123xyz +# SSH into a sandbox +agentuity cloud ssh sbx_abc123xyz + # Run a command and exit agentuity cloud ssh 'ps aux' diff --git a/content/Reference/CLI/deployment.mdx b/content/Reference/CLI/deployment.mdx index 3f10b640..c190089c 100644 --- a/content/Reference/CLI/deployment.mdx +++ b/content/Reference/CLI/deployment.mdx @@ -244,10 +244,6 @@ Removing a deployment permanently deletes it. You cannot rollback to a removed d ## Custom Domains -You can configure custom domains using either the configuration file or CLI commands. - -### Option 1: Configuration File - Configure custom domains in `agentuity.json`: ```json @@ -313,25 +309,23 @@ After deployment with custom domains, the CLI only shows custom URLs: The project URL and deployment-specific URLs still exist but custom domains take precedence in the output. -### Option 2: CLI Commands - -Manage custom domains directly from the CLI: - -```bash -# List configured domains -agentuity cloud domain list - -# Add a domain -agentuity cloud domain add api.example.com +## Resource Configuration -# Remove a domain -agentuity cloud domain remove api.example.com +Configure CPU, memory, and disk limits in `agentuity.json`: -# Verify DNS configuration -agentuity cloud domain verify api.example.com +```json +{ + "deployment": { + "resources": { + "cpu": "500m", + "memory": "512Mi", + "disk": "1Gi" + } + } +} ``` -Use the configuration file for domains that should persist across deployments. Use CLI commands for quick testing or temporary domains. +**Defaults:** `cpu: "500m"`, `memory: "500Mi"`, `disk: "500Mi"` ## Environment Variables diff --git a/content/Reference/CLI/getting-started.mdx b/content/Reference/CLI/getting-started.mdx index 8d953453..ed49eb60 100644 --- a/content/Reference/CLI/getting-started.mdx +++ b/content/Reference/CLI/getting-started.mdx @@ -64,6 +64,14 @@ Check your authentication status: agentuity auth whoami ``` +### Get Your API Key + +Display the API key for your authenticated account: + +```bash +agentuity auth apikey +``` + ### Create a New Account Sign up for a new Agentuity account directly from the CLI: diff --git a/content/Reference/CLI/index.mdx b/content/Reference/CLI/index.mdx index b75071fb..b04f4a1c 100644 --- a/content/Reference/CLI/index.mdx +++ b/content/Reference/CLI/index.mdx @@ -20,7 +20,7 @@ See [Getting Started](/Reference/CLI/getting-started) for installation options, | [Getting Started](/Reference/CLI/getting-started) | `login`, `logout`, `new` | Install, authenticate, create projects | | [Development](/Reference/CLI/development) | `dev` | Local development server | | [Deployment](/Reference/CLI/deployment) | `deploy`, `cloud project` | Deploy and manage cloud projects | -| [Storage](/Reference/CLI/storage) | `cloud kv`, `cloud vector`, `cloud object`, `cloud redis` | Manage KV, vector, object, and Redis storage | +| [Storage](/Reference/CLI/storage) | `cloud kv`, `cloud vector`, `cloud s3`, `cloud redis` | Manage KV, vector, object, and Redis storage | | [Configuration](/Reference/CLI/configuration) | `cloud env`, `cloud secret`, `cloud apikey` | Manage env vars, secrets, and API keys | | [Debugging](/Reference/CLI/debugging) | `cloud ssh`, `cloud session` | SSH access, session inspection | | [AI Commands](/Reference/CLI/ai-commands) | `ai` | AI coding agent utilities | diff --git a/content/Reference/CLI/sandbox.mdx b/content/Reference/CLI/sandbox.mdx index 5db6fac1..2bad0350 100644 --- a/content/Reference/CLI/sandbox.mdx +++ b/content/Reference/CLI/sandbox.mdx @@ -20,8 +20,16 @@ All sandbox commands require the `cloud` prefix. For example: `agentuity cloud s | `sandbox delete ` | Destroy sandbox | | `sandbox exec -- ` | Execute in existing sandbox | | `sandbox cp` | Copy files to/from sandbox | +| `sandbox files ` | List files in sandbox | +| `sandbox mkdir ` | Create directory | +| `sandbox rmdir ` | Remove directory | +| `sandbox rm ` | Remove file | +| `sandbox download ` | Download as archive | +| `sandbox upload ` | Upload and extract archive | | `sandbox snapshot` | Manage snapshots | | `sandbox execution` | View execution history | +| `sandbox runtime list` | List available runtimes | +| `sandbox env ` | Manage environment variables | **Alias:** `sb` (e.g., `agentuity cloud sb list`) @@ -143,7 +151,9 @@ agentuity cloud sandbox delete sbx_abc123 --confirm # Skip prompt ## File Operations -Copy files to and from sandboxes. +### Copy Files + +Copy individual files or directories to and from sandboxes. ```bash agentuity cloud sandbox cp @@ -160,6 +170,124 @@ agentuity cloud sandbox cp sbx_abc123:/workspace/output.json ./output.json agentuity cloud sandbox cp ./src sbx_abc123:/workspace/src ``` +### List Files + +List files and directories in a sandbox. + +```bash +agentuity cloud sandbox files [path] [options] +``` + +| Option | Description | +|--------|-------------| +| `-l, --long` | Show permissions and timestamps | +| `--json` | JSON output | + +**Alias:** `lsf` + +```bash +# List root directory +agentuity cloud sandbox files sbx_abc123 + +# List specific directory +agentuity cloud sandbox files sbx_abc123 /workspace/src + +# Long format with details +agentuity cloud sandbox files sbx_abc123 -l +``` + +### Create Directory + +```bash +agentuity cloud sandbox mkdir [options] +``` + +| Option | Description | +|--------|-------------| +| `-p, --parents` | Create parent directories as needed | + +```bash +# Create a directory +agentuity cloud sandbox mkdir sbx_abc123 /workspace/output + +# Create nested directories +agentuity cloud sandbox mkdir sbx_abc123 /workspace/data/processed -p +``` + +### Remove Files and Directories + +```bash +# Remove a file +agentuity cloud sandbox rm + +# Remove a directory +agentuity cloud sandbox rmdir [options] +``` + +| Option | Description | +|--------|-------------| +| `-r, --recursive` | Remove directory and all contents | + +```bash +# Remove a file +agentuity cloud sandbox rm sbx_abc123 /workspace/temp.txt + +# Remove empty directory +agentuity cloud sandbox rmdir sbx_abc123 /workspace/old + +# Remove directory with contents +agentuity cloud sandbox rmdir sbx_abc123 /workspace/cache -r +``` + +### Download Archive + +Download sandbox files as a compressed archive. + +```bash +agentuity cloud sandbox download [options] +``` + +| Option | Description | +|--------|-------------| +| `--path ` | Download specific directory (defaults to root) | +| `--format ` | Archive format: `tar.gz` (default) or `zip` | + +**Alias:** `dl` + +```bash +# Download entire sandbox +agentuity cloud sandbox download sbx_abc123 ./backup.tar.gz + +# Download as zip +agentuity cloud sandbox download sbx_abc123 ./backup.zip --format zip + +# Download specific directory +agentuity cloud sandbox download sbx_abc123 ./src.tar.gz --path /workspace/src +``` + +### Upload Archive + +Upload and extract an archive into a sandbox. + +```bash +agentuity cloud sandbox upload [options] +``` + +| Option | Description | +|--------|-------------| +| `--path ` | Destination path (defaults to root) | +| `--format ` | Archive format (auto-detected if not specified) | + +**Alias:** `ul` + +```bash +# Upload and extract to root +agentuity cloud sandbox upload sbx_abc123 ./project.tar.gz + +# Upload to specific directory +agentuity cloud sandbox upload sbx_abc123 ./deps.zip --path /workspace/node_modules +``` + ## Snapshot Commands Manage sandbox snapshots for creating pre-configured environments. @@ -317,6 +445,59 @@ agentuity cloud sandbox get sbx_abc123 --json agentuity cloud sandbox snapshot list --json ``` +## Runtime Commands + +List available sandbox runtimes. + +### List Runtimes + +```bash +agentuity cloud sandbox runtime list [options] +``` + +| Option | Description | +|--------|-------------| +| `--limit ` | Max results (default: 50, max: 100) | +| `--offset ` | Pagination offset | +| `--json` | JSON output | + +```bash +# List available runtimes +agentuity cloud sandbox runtime list + +# With pagination +agentuity cloud sandbox runtime list --limit 10 --offset 20 +``` + +**Alias:** `rt` (e.g., `agentuity cloud sandbox rt list`) + +## Environment Variables + +Manage environment variables on a running sandbox. + +```bash +agentuity cloud sandbox env [KEY=VALUE...] [options] +``` + +| Option | Description | +|--------|-------------| +| `--delete ` | Delete variable (repeatable, alias: `-d`) | +| `--json` | JSON output | + +```bash +# Set an environment variable +agentuity cloud sandbox env sbx_abc123 MY_VAR=value + +# Set multiple variables +agentuity cloud sandbox env sbx_abc123 VAR1=value1 VAR2=value2 + +# Delete a variable +agentuity cloud sandbox env sbx_abc123 --delete MY_VAR + +# Delete multiple variables +agentuity cloud sandbox env sbx_abc123 -d VAR1 -d VAR2 +``` + ## Next Steps - [Sandbox Overview](/Sandbox): Understand sandbox concepts, security defaults, and when to use each execution mode diff --git a/content/Reference/CLI/storage.mdx b/content/Reference/CLI/storage.mdx index da5d811b..60bf04f6 100644 --- a/content/Reference/CLI/storage.mdx +++ b/content/Reference/CLI/storage.mdx @@ -143,63 +143,6 @@ agentuity cloud s3 delete **In agents:** Use Bun's `s3` API (`import { s3 } from "bun"`). See [Object Storage (S3)](/Storage/object). -## Object Storage (Legacy) - -The `cloud obj` commands provide bucket-based object management. For new projects, consider using `cloud s3` instead. - -### Interactive REPL - -```bash -agentuity cloud obj repl -``` - -### Upload a File - -```bash -# Upload from file path -agentuity cloud obj put uploads images/logo.png @./logo.png - -# Store JSON directly -agentuity cloud obj put assets config.json '{"api":"https://api.example.com"}' - -# With custom content type -agentuity cloud obj put backups db.sql @~/backup.sql --content-type application/sql -``` - -### Download a File - -```bash -agentuity cloud obj get uploads images/logo.png -agentuity cloud obj get assets config.json -``` - -### Delete a File - -```bash -agentuity cloud obj delete uploads old-image.png -``` - -### Generate Public URL - -```bash -# Permanent URL -agentuity cloud obj url uploads images/logo.png - -# Temporary URL (expires in 1 hour) -agentuity cloud obj url uploads private-doc.pdf --expires 3600 - -# 5-minute presigned URL -agentuity cloud obj presigned backups db.sql --expires 300 -``` - -### List Buckets and Files - -```bash -agentuity cloud obj list-buckets -agentuity cloud obj list-keys uploads -agentuity cloud obj ls assets # Using alias -``` - ## Vector Storage Search and inspect vector embeddings. From 66369268f2f3a0392db8598f367a6b04b83b88e1 Mon Sep 17 00:00:00 2001 From: Parteek Singh Date: Wed, 14 Jan 2026 10:48:34 -0800 Subject: [PATCH 2/4] Add more sandbox, snapshot, runtime info --- content/Reference/CLI/deployment.mdx | 5 +- content/Reference/CLI/sandbox.mdx | 190 ++++++++++++++++++++++++- content/Reference/CLI/storage.mdx | 6 + content/Services/Sandbox/index.mdx | 85 ++++++++--- content/Services/Sandbox/sdk-usage.mdx | 17 ++- content/Services/Sandbox/snapshots.mdx | 86 ++++++++++- content/index.mdx | 2 +- 7 files changed, 355 insertions(+), 36 deletions(-) diff --git a/content/Reference/CLI/deployment.mdx b/content/Reference/CLI/deployment.mdx index c190089c..b7c6f06f 100644 --- a/content/Reference/CLI/deployment.mdx +++ b/content/Reference/CLI/deployment.mdx @@ -320,13 +320,16 @@ Configure CPU, memory, and disk limits in `agentuity.json`: "cpu": "500m", "memory": "512Mi", "disk": "1Gi" - } + }, + "domains": [] } } ``` **Defaults:** `cpu: "500m"`, `memory: "500Mi"`, `disk: "500Mi"` +The `domains` array is empty by default. Add custom domains when needed (see [Custom Domains](#custom-domains)). + ## Environment Variables The deploy command syncs variables from `.env.production` (or `.env` as fallback): diff --git a/content/Reference/CLI/sandbox.mdx b/content/Reference/CLI/sandbox.mdx index 2bad0350..af5df62d 100644 --- a/content/Reference/CLI/sandbox.mdx +++ b/content/Reference/CLI/sandbox.mdx @@ -27,6 +27,8 @@ All sandbox commands require the `cloud` prefix. For example: `agentuity cloud s | `sandbox download ` | Download as archive | | `sandbox upload ` | Upload and extract archive | | `sandbox snapshot` | Manage snapshots | +| `sandbox snapshot build ` | Build snapshot from declarative file | +| `sandbox snapshot generate` | Generate template snapshot build file | | `sandbox execution` | View execution history | | `sandbox runtime list` | List available runtimes | | `sandbox env ` | Manage environment variables | @@ -51,6 +53,11 @@ agentuity cloud sandbox run [options] -- | `--network` | Enable outbound network access | | `--timeout ` | Execution timeout (e.g., `30s`, `5m`) | | `--snapshot ` | Create from snapshot | +| `--runtime ` | Runtime name (e.g., `bun:1`, `python:3.14`) | +| `--dependency ` | Apt packages to install (repeatable) | +| `--env ` | Environment variables (repeatable) | +| `--file ` | Files to create (repeatable) | +| `--project-id ` | Associate with project | | `--json` | JSON output | ### Examples @@ -87,6 +94,15 @@ agentuity cloud sandbox create [options] | `--network` | Enable outbound network | | `--snapshot ` | Create from snapshot | | `--idle-timeout ` | Auto-destroy after idle (e.g., `1h`) | +| `--runtime ` | Runtime name (e.g., `bun:1`, `python:3.14`) | +| `--name ` | Sandbox name | +| `--description ` | Sandbox description | +| `--port ` | Port to expose (1024-65535) | +| `--dependency ` | Apt packages to install (repeatable) | +| `--env ` | Environment variables (repeatable) | +| `--file ` | Files to create (repeatable) | +| `--metadata ` | User-defined metadata (JSON) | +| `--project-id ` | Associate with project | ```bash # Create with defaults @@ -97,6 +113,12 @@ agentuity cloud sandbox create --memory 1Gi --cpu 1000m --network # Create from snapshot agentuity cloud sandbox create --snapshot python-ml + +# Create with port exposed to internet +agentuity cloud sandbox create --port 3000 --network --name my-server + +# Create associated with a project +agentuity cloud sandbox create --project-id proj_abc123 ``` ### Execute Command @@ -120,13 +142,18 @@ agentuity cloud sandbox list [options] | Option | Description | |--------|-------------| -| `--status ` | Filter by status (`idle`, `running`, `creating`) | -| `--limit ` | Max results | +| `--status ` | Filter by status (`idle`, `running`, `creating`, `terminated`, `failed`) | +| `--project-id ` | Filter by project | +| `--all` | List all sandboxes (bypass project filter) | +| `--limit ` | Max results (default: 50, max: 100) | +| `--offset ` | Pagination offset | | `--json` | JSON output | ```bash agentuity cloud sandbox list agentuity cloud sandbox list --status idle +agentuity cloud sandbox list --project-id proj_abc123 +agentuity cloud sandbox list --all # Show all sandboxes agentuity cloud sandbox list --json ``` @@ -149,6 +176,59 @@ agentuity cloud sandbox delete sbx_abc123 agentuity cloud sandbox delete sbx_abc123 --confirm # Skip prompt ``` +## Port Mapping + +Expose a port from a sandbox to the public internet. This allows you to run web servers, APIs, or any network service inside a sandbox and access it from external clients. + +### Create with Port + +```bash +agentuity cloud sandbox create --port 3000 --network --name my-server +``` + +Port constraints: +- Must be between 1024 and 65535 (no privileged ports) +- Requires `--network` flag for outbound access +- Each sandbox can expose one port + +### Access the Public URL + +After creating a sandbox with a port, use `get` to retrieve the public URL: + +```bash +agentuity cloud sandbox get sbx_abc123 +``` + +The output includes the public URL when a port is configured: + +``` +ID: sbx_abc123 +Status: running +Port: 3000 +URL: https://my-server-abc123.agentuity.cloud +``` + +### Example: Run a Web Server + +```bash +# Create sandbox with port 3000 +agentuity cloud sandbox create --port 3000 --network --name my-api +# sbx_abc123 + +# Upload server code +agentuity cloud sandbox cp ./server.js sbx_abc123:/home/agentuity/ + +# Start the server +agentuity cloud sandbox exec sbx_abc123 -- bun run /home/agentuity/server.js + +# Get the public URL +agentuity cloud sandbox get sbx_abc123 +# URL: https://my-api-abc123.agentuity.cloud + +# Test from anywhere +curl https://my-api-abc123.agentuity.cloud/api/health +``` + ## File Operations ### Copy Files @@ -360,6 +440,106 @@ agentuity cloud sandbox snapshot delete snp_xyz789 agentuity cloud sandbox snapshot delete snp_xyz789 --confirm ``` +### Build Snapshot from File + +Build a snapshot from a declarative YAML or JSON file. This provides reproducible, version-controlled snapshot definitions. + +```bash +agentuity cloud sandbox snapshot build [options] +``` + +| Option | Description | +|--------|-------------| +| `--file ` | Path to build file (defaults to `agentuity-snapshot.yaml`) | +| `--tag ` | Snapshot tag (defaults to `latest`) | +| `--name ` | Snapshot name (overrides build file) | +| `--description ` | Snapshot description (overrides build file) | +| `--env ` | Environment variable substitution (repeatable) | +| `--metadata ` | Metadata key-value pairs (repeatable) | +| `--force` | Force rebuild even if content unchanged | + +```bash +# Build from current directory +agentuity cloud sandbox snapshot build . + +# Build with custom file and tag +agentuity cloud sandbox snapshot build ./project --file custom-build.yaml --tag production + +# Build with environment substitution +agentuity cloud sandbox snapshot build . --env API_KEY=secret --env VERSION=1.0.0 + +# Force rebuild +agentuity cloud sandbox snapshot build . --force +``` + +#### Build File Format + +Create an `agentuity-snapshot.yaml` file. Use glob patterns to include files and prefix with `!` to exclude: + +```yaml +# Required: Schema version +version: 1 + +# Required: Runtime environment +runtime: bun:1 + +# Optional: Snapshot name +name: my-snapshot + +# Optional: Description +description: My sandbox snapshot + +# Optional: Apt packages to install +dependencies: + - curl + - ffmpeg + - imagemagick + +# Optional: Files to include (supports globs and exclusions) +# Prefix with ! to exclude files +files: + - "*.js" + - src/** + - config/*.json + - "!**/*.test.js" # Exclude test files + - "!node_modules/**" # Exclude node_modules + +# Optional: Environment variables +env: + NODE_ENV: production + API_URL: https://api.example.com + SECRET_KEY: ${SECRET_KEY} # Substituted via --env flag + +# Optional: Metadata +metadata: + version: ${VERSION} + author: team-name +``` + +### Generate Build Template + +Generate a template snapshot build file to get started: + +```bash +agentuity cloud sandbox snapshot generate [options] +``` + +| Option | Description | +|--------|-------------| +| `--format ` | Output format: `yaml` (default) or `json` | + +```bash +# Generate YAML template (default) +agentuity cloud sandbox snapshot generate > agentuity-snapshot.yaml + +# Generate JSON template +agentuity cloud sandbox snapshot generate --format json > agentuity-snapshot.json +``` + + +The generated template includes helpful comments explaining each field. See [Creating and Using Snapshots](/Services/Sandbox/snapshots) for workflows and use cases. + + ## Execution History View past command executions within a sandbox. @@ -500,6 +680,6 @@ agentuity cloud sandbox env sbx_abc123 -d VAR1 -d VAR2 ## Next Steps -- [Sandbox Overview](/Sandbox): Understand sandbox concepts, security defaults, and when to use each execution mode -- [SDK Usage](/Sandbox/sdk-usage): Use sandboxes programmatically in agents and routes -- [Snapshots](/Sandbox/snapshots): Pre-configure environments for faster cold starts +- [Sandbox Overview](/Services/Sandbox): Understand sandbox concepts, security defaults, and when to use each execution mode +- [SDK Usage](/Services/Sandbox/sdk-usage): Use sandboxes programmatically in agents and routes +- [Snapshots](/Services/Sandbox/snapshots): Pre-configure environments for faster cold starts diff --git a/content/Reference/CLI/storage.mdx b/content/Reference/CLI/storage.mdx index 60bf04f6..5d36d840 100644 --- a/content/Reference/CLI/storage.mdx +++ b/content/Reference/CLI/storage.mdx @@ -247,8 +247,14 @@ agentuity cloud db list ```bash agentuity cloud db create --name my-database +agentuity cloud db create --name analytics-db --description "Analytics data warehouse" ``` +| Option | Description | +|--------|-------------| +| `--name ` | Custom database name | +| `--description ` | Optional database description | + This adds `DATABASE_URL` to your local `.env` file automatically. ### Get Database Details diff --git a/content/Services/Sandbox/index.mdx b/content/Services/Sandbox/index.mdx index 455c1110..8b6845d3 100644 --- a/content/Services/Sandbox/index.mdx +++ b/content/Services/Sandbox/index.mdx @@ -5,6 +5,14 @@ description: Run code in isolated, secure containers with configurable resources Execute code in isolated Linux containers with configurable resource limits, network controls, and execution timeouts. +## Three Ways to Use Sandboxes + +| Method | Best For | +|--------|----------| +| **[Web App](https://app-v1.agentuity.com)** | Visual management, browsing runtimes and snapshots | +| **[SDK](/Services/Sandbox/sdk-usage)** | Programmatic use in agents and routes (`ctx.sandbox`) | +| **[CLI](/Reference/CLI/sandbox)** | Local development, scripting, CI/CD | + Your agents are written in TypeScript, but the sandbox can run any language safely. Use `ctx.sandbox.run()` to execute Python, Node.js, shell scripts, or anything available via `apt install` in isolated containers. @@ -13,16 +21,61 @@ Your agents are written in TypeScript, but the sandbox can run any language safe | Concept | Description | |---------|-------------| -| **Sandbox** | A running container where you execute commands | -| **Execution** | A single command run within a sandbox | -| **Snapshot** | A saved filesystem state used to create new sandboxes | +| **Runtime** | A pre-configured base environment (OS + language tools) provided by Agentuity | +| **Sandbox** | A running container created from a runtime where you execute commands | +| **Snapshot** | A saved sandbox state that can be used to create new sandboxes | + +These build on each other: **Runtime → Sandbox → Snapshot**. Here's an example of how to use all three: + +1. Pick a **runtime** (e.g., `bun:1` or `node:latest`) +2. Create a **sandbox** from that runtime +3. Optionally save a **snapshot** to reuse your configured environment + +## Runtimes + +Runtimes are pre-configured base environments that Agentuity provides. Each includes an operating system, language toolchain, and common utilities. + +### Language Runtimes + +Use these for general code execution: + +| Runtime | Description | +|---------|-------------| +| `bun:1` | Bun 1.x with JavaScript/TypeScript support (default) | +| `node:latest` | Node.js latest version | +| `node:lts` | Node.js LTS version | +| `base:latest` | Minimal runtime with essential tools | + +### Agent Runtimes - -A snapshot captures the filesystem state of a sandbox at a point in time. Think of it like a Docker image: you create new sandboxes *from* a snapshot rather than running it directly. +Pre-configured AI coding assistants: -To use snapshots: create a sandbox, configure it, save a snapshot, then create new sandboxes from that snapshot. +| Runtime | Description | +|---------|-------------| +| `claude-code:latest` | Claude Code AI assistant | +| `amp:latest` | Amp AI coding assistant | +| `codex:latest` | OpenAI Codex CLI agent | +| `gemini-cli:latest` | Google Gemini CLI agent | +| `opencode:latest` | OpenCode AI coding assistant | + + +Run `agentuity cloud sandbox runtime list` to see all available runtimes, or view them in the [Agentuity App](https://app-v1.agentuity.com) under **Services > Sandbox > Runtimes**. +## Snapshots + +A snapshot captures the filesystem state of a sandbox. You create new sandboxes *from* a snapshot rather than running it directly. + +Snapshots build on top of runtimes. When you create a snapshot, it includes everything from the base runtime plus your installed dependencies and files. + +**Workflow:** +1. Create a sandbox from a runtime +2. Install dependencies and configure the environment +3. Save a snapshot +4. Create new sandboxes from that snapshot (fast, no reinstallation needed) + +See [Creating and Using Snapshots](/Services/Sandbox/snapshots) for details. + ## Two Execution Modes Choose based on your use case: @@ -72,22 +125,20 @@ const agent = createAgent('ProjectBuilder', { }); ``` -## Access Patterns +## SDK Access -| Context | Access | Example | -|---------|--------|---------| -| Agents | `ctx.sandbox` | `await ctx.sandbox.run({...})` | -| Routes | `c.var.sandbox` | `await c.var.sandbox.create({...})` | -| CLI | Commands | `agentuity cloud sandbox run ...` | +| Context | Access | +|---------|--------| +| Agents | `ctx.sandbox` | +| Routes | `c.var.sandbox` | - -The sandbox API is identical in agents and routes. `ctx.sandbox.run()` and `c.var.sandbox.run()` work the same way. - +The API is identical in both contexts. ## Configuration Options | Option | Description | Example | |--------|-------------|---------| +| `runtime` | Runtime environment | `'bun:1'`, `'python:3.14'` | | `resources.memory` | Memory limit (Kubernetes-style) | `'512Mi'`, `'1Gi'` | | `resources.cpu` | CPU limit in millicores | `'500m'`, `'1000m'` | | `resources.disk` | Disk space limit | `'1Gi'` | @@ -119,6 +170,6 @@ Sandboxes provide isolation through: ## Next Steps -- [SDK Usage](/Sandbox/sdk-usage): Detailed API for file I/O, streaming, and advanced configuration -- [Snapshots](/Sandbox/snapshots): Skip dependency installation with pre-configured environments +- [SDK Usage](/Services/Sandbox/sdk-usage): Detailed API for file I/O, streaming, and advanced configuration +- [Snapshots](/Services/Sandbox/snapshots): Skip dependency installation with pre-configured environments - [CLI Commands](/Reference/CLI/sandbox): Debug sandboxes and create snapshots manually diff --git a/content/Services/Sandbox/sdk-usage.mdx b/content/Services/Sandbox/sdk-usage.mdx index 2a15251a..50cf2ad5 100644 --- a/content/Services/Sandbox/sdk-usage.mdx +++ b/content/Services/Sandbox/sdk-usage.mdx @@ -170,7 +170,7 @@ try { Start sandboxes from pre-configured snapshots for faster cold starts: -A snapshot is a saved filesystem state, similar to a Docker image. You create sandboxes *from* snapshots rather than running them directly. See [Snapshots](/Sandbox/snapshots) for how to create them. +A snapshot is a saved filesystem state. You create sandboxes *from* snapshots rather than running them directly. See [Snapshots](/Services/Sandbox/snapshots) for how to create them. ```typescript @@ -269,8 +269,11 @@ export default router; ```typescript const { sandboxes, total } = await ctx.sandbox.list({ - status: 'idle', // Filter by status + status: 'idle', // Filter by status + projectId: 'proj_x', // Filter by project + snapshotId: 'snp_y', // Filter by snapshot limit: 10, + offset: 0, }); for (const info of sandboxes) { @@ -309,6 +312,9 @@ await ctx.sandbox.destroy('sbx_abc123'); | Option | Type | Description | |--------|------|-------------| +| `runtime` | `string` | Runtime environment: `'bun:1'`, `'python:3.14'` | +| `name` | `string` | Optional sandbox name | +| `description` | `string` | Optional description | | `resources.memory` | `string` | Memory limit: `'256Mi'`, `'1Gi'` | | `resources.cpu` | `string` | CPU in millicores: `'500m'`, `'1000m'` | | `resources.disk` | `string` | Disk limit: `'512Mi'`, `'2Gi'` | @@ -318,6 +324,7 @@ await ctx.sandbox.destroy('sbx_abc123'); | `dependencies` | `string[]` | Apt packages: `['python3', 'git']` | | `snapshot` | `string` | Snapshot ID or tag to restore from | | `env` | `Record` | Environment variables | +| `metadata` | `Record` | User-defined metadata for tracking | ### ExecuteOptions @@ -340,13 +347,13 @@ await ctx.sandbox.destroy('sbx_abc123'); ## Best Practices -- **Set appropriate resource limits**: Prevent runaway processes from consuming resources +- **Set [resource limits](#sandboxcreateoptions)**: Control memory and CPU usage for predictable performance - **Use timeouts**: Always set execution timeouts for untrusted code -- **Disable network by default**: Only enable when needed (package installation, API calls) +- **Enable network when needed**: Required for package installation, API calls, and external requests - **Clean up interactive sandboxes**: Use try/finally to ensure `destroy()` is called - **Use snapshots for common environments**: Pre-install dependencies to reduce cold start time ## Next Steps -- [Snapshots](/Sandbox/snapshots): Skip dependency installation with pre-configured environments +- [Snapshots](/Services/Sandbox/snapshots): Skip dependency installation with pre-configured environments - [CLI Commands](/Reference/CLI/sandbox): Debug sandboxes and create snapshots from the terminal diff --git a/content/Services/Sandbox/snapshots.mdx b/content/Services/Sandbox/snapshots.mdx index 237a819d..6079a449 100644 --- a/content/Services/Sandbox/snapshots.mdx +++ b/content/Services/Sandbox/snapshots.mdx @@ -5,10 +5,23 @@ description: Save and restore sandbox filesystem states for faster cold starts Skip slow dependency installation on every run by saving sandbox filesystem states as snapshots. +Manage snapshots via the [Web App](https://app-v1.agentuity.com), [SDK](/Services/Sandbox/sdk-usage), or [CLI](/Reference/CLI/sandbox). + -A snapshot captures the filesystem state of a sandbox at a point in time. Think of it like Docker: a snapshot is an image, a sandbox is a running container. You create new sandboxes *from* snapshots. +A snapshot captures the filesystem state of a sandbox at a point in time. You create new sandboxes *from* snapshots, not run them directly. +## How Snapshots Work + +Snapshots build on top of [runtimes](/Services/Sandbox#runtimes). When you create a snapshot: + +1. Start with a **runtime** (e.g., `bun:1`) as the base layer +2. Add your **dependencies** (apt packages, npm modules, etc.) +3. Include your **files** (source code, config) +4. The snapshot captures everything: runtime + dependencies + files + +When you create a sandbox from a snapshot, it starts with all of this pre-configured. + ## The Snapshot Workflow 1. Create a sandbox @@ -17,13 +30,72 @@ A snapshot captures the filesystem state of a sandbox at a point in time. Think 4. Later, create new sandboxes from that snapshot 5. New sandboxes start with everything pre-configured -## Creating a Snapshot +## Declarative Snapshots (Recommended) + +Define snapshots in a YAML file for reproducible, version-controlled environments. This approach is ideal for CI/CD pipelines and team collaboration. + +### Quick Start + +Generate a template with helpful comments explaining each field: + +```bash +agentuity cloud sandbox snapshot generate > agentuity-snapshot.yaml +``` + +The generated file includes documentation for all options: runtime selection, apt dependencies, file patterns, environment variables, and metadata. Customize it for your needs, then build: + +```bash +agentuity cloud sandbox snapshot build . +``` + +### Build File Example + +```yaml +version: 1 +runtime: bun:1 # Base runtime - snapshot layers on top of this +description: Node.js environment with common dependencies + +dependencies: # Apt packages to install + - curl + - jq + +files: # Files to include from your project + - src/** + - package.json + - "!**/*.test.ts" # Exclude test files + - "!node_modules/**" # Exclude node_modules + +env: + NODE_ENV: production +``` + +### Build Options + +```bash +# Build with a custom tag +agentuity cloud sandbox snapshot build . --tag production + +# Build with environment variable substitution +agentuity cloud sandbox snapshot build . --env API_KEY=secret + +# Force rebuild even if content unchanged +agentuity cloud sandbox snapshot build . --force +``` + +### When to Use Declarative vs Manual + +| Approach | Best For | +|----------|----------| +| **Declarative** | CI/CD pipelines, reproducible environments, team collaboration, version control | +| **Manual** | Quick experimentation, one-off debugging, exploring new configurations | + +## Creating a Snapshot Manually -Snapshots are created via CLI from an existing sandbox: +Create a sandbox, configure it, then save a snapshot: ```bash -# Create a sandbox and configure it -agentuity cloud sandbox create --memory 1Gi --network +# Create a sandbox with a runtime +agentuity cloud sandbox create --runtime bun:1 --memory 1Gi --network # Returns: sbx_abc123 # Install dependencies @@ -222,9 +294,9 @@ Snapshots don't include: - **Tag important snapshots**: Use descriptive tags like `python-ml-v2` instead of relying on IDs - **Keep snapshots lean**: Only include necessary dependencies to minimize size - **Version your snapshots**: Use semantic versioning tags for reproducibility -- **Clean up unused snapshots**: Delete old snapshots to free storage +- **Clean up unused snapshots**: Delete snapshots you no longer need ## Next Steps -- [SDK Usage](/Sandbox/sdk-usage): File I/O, streaming, and advanced configuration options +- [SDK Usage](/Services/Sandbox/sdk-usage): File I/O, streaming, and advanced configuration options - [CLI Commands](/Reference/CLI/sandbox): Debug sandboxes and manage snapshots from the terminal diff --git a/content/index.mdx b/content/index.mdx index bf4d206e..a2c2de05 100644 --- a/content/index.mdx +++ b/content/index.mdx @@ -36,7 +36,7 @@ This agent uses the AI SDK to call OpenAI and respond to messages. Deploy with ` - **Routes & Triggers**: HTTP, WebSocket, SSE, cron - **Storage**: Key-value, vector, object storage, durable streams -- **[Sandbox](/Sandbox)**: Execute code in isolated containers with controlled resources and network access +- **[Sandbox](/Services/Sandbox)**: Execute code in isolated containers with controlled resources and network access - **[Evaluations](/Agents/evaluations)**: Automated quality checks that run after each agent execution - **[AI Gateway](/Agents/ai-gateway)**: Route LLM calls through OpenAI, Anthropic, Google, and more - **Type Safety**: Built-in schema validation with `@agentuity/schema`, Zod, or Valibot From 85baad71d0b9d7fa76fb5930522df6374b56de48 Mon Sep 17 00:00:00 2001 From: Parteek Singh Date: Wed, 14 Jan 2026 11:12:19 -0800 Subject: [PATCH 3/4] Tweaks --- content/Services/Sandbox/sdk-usage.mdx | 13 +++++++++++++ content/Services/Sandbox/snapshots.mdx | 2 +- 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/content/Services/Sandbox/sdk-usage.mdx b/content/Services/Sandbox/sdk-usage.mdx index 50cf2ad5..a3951d1b 100644 --- a/content/Services/Sandbox/sdk-usage.mdx +++ b/content/Services/Sandbox/sdk-usage.mdx @@ -335,6 +335,19 @@ await ctx.sandbox.destroy('sbx_abc123'); | `timeout` | `string` | Override execution timeout | | `signal` | `AbortSignal` | Cancel the execution | +### Execution + +Returned by `sandbox.execute()`: + +| Field | Type | Description | +|-------|------|-------------| +| `executionId` | `string` | Unique execution ID for debugging | +| `status` | `string` | `'queued'`, `'running'`, `'completed'`, `'failed'`, `'timeout'`, `'cancelled'` | +| `exitCode` | `number` | Process exit code (when completed) | +| `durationMs` | `number` | Execution duration in milliseconds | +| `stdoutStreamUrl` | `string` | URL to fetch stdout stream | +| `stderrStreamUrl` | `string` | URL to fetch stderr stream | + ### SandboxRunResult | Field | Type | Description | diff --git a/content/Services/Sandbox/snapshots.mdx b/content/Services/Sandbox/snapshots.mdx index 6079a449..da9c89ef 100644 --- a/content/Services/Sandbox/snapshots.mdx +++ b/content/Services/Sandbox/snapshots.mdx @@ -5,7 +5,7 @@ description: Save and restore sandbox filesystem states for faster cold starts Skip slow dependency installation on every run by saving sandbox filesystem states as snapshots. -Manage snapshots via the [Web App](https://app-v1.agentuity.com), [SDK](/Services/Sandbox/sdk-usage), or [CLI](/Reference/CLI/sandbox). +Manage snapshots via the [Web App](https://app-v1.agentuity.com) under **Services > Sandbox > Snapshots**, the [SDK](/Services/Sandbox/sdk-usage), or [CLI](/Reference/CLI/sandbox). A snapshot captures the filesystem state of a sandbox at a point in time. You create new sandboxes *from* snapshots, not run them directly. From a33a30daed6a2afad7be2ebdbfe77c1226e491cd Mon Sep 17 00:00:00 2001 From: Parteek Singh Date: Wed, 14 Jan 2026 12:14:28 -0800 Subject: [PATCH 4/4] Fix --- content/Reference/CLI/deployment.mdx | 2 +- content/Reference/CLI/sandbox.mdx | 2 +- content/Services/Sandbox/snapshots.mdx | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/Reference/CLI/deployment.mdx b/content/Reference/CLI/deployment.mdx index b7c6f06f..fd3c7281 100644 --- a/content/Reference/CLI/deployment.mdx +++ b/content/Reference/CLI/deployment.mdx @@ -326,7 +326,7 @@ Configure CPU, memory, and disk limits in `agentuity.json`: } ``` -**Defaults:** `cpu: "500m"`, `memory: "500Mi"`, `disk: "500Mi"` +**Defaults:** `cpu: "500m"`, `memory: "500Mi"`, `disk: "500Mi"`. Increase as needed for your workload. The `domains` array is empty by default. Add custom domains when needed (see [Custom Domains](#custom-domains)). diff --git a/content/Reference/CLI/sandbox.mdx b/content/Reference/CLI/sandbox.mdx index af5df62d..575f4fd8 100644 --- a/content/Reference/CLI/sandbox.mdx +++ b/content/Reference/CLI/sandbox.mdx @@ -188,7 +188,7 @@ agentuity cloud sandbox create --port 3000 --network --name my-server Port constraints: - Must be between 1024 and 65535 (no privileged ports) -- Requires `--network` flag for outbound access +- Requires `--network` flag to enable network connectivity - Each sandbox can expose one port ### Access the Public URL diff --git a/content/Services/Sandbox/snapshots.mdx b/content/Services/Sandbox/snapshots.mdx index da9c89ef..ef000511 100644 --- a/content/Services/Sandbox/snapshots.mdx +++ b/content/Services/Sandbox/snapshots.mdx @@ -215,14 +215,14 @@ Create snapshots for each language you support: ```bash # Python with common packages -agentuity cloud sandbox create --network +agentuity cloud sandbox create --runtime base:latest --network agentuity cloud sandbox exec sbx_... -- apt-get update agentuity cloud sandbox exec sbx_... -- apt-get install -y python3 python3-pip agentuity cloud sandbox exec sbx_... -- pip install numpy pandas requests agentuity cloud sandbox snapshot create sbx_... --tag python-data # Node.js with TypeScript -agentuity cloud sandbox create --network +agentuity cloud sandbox create --runtime bun:1 --network agentuity cloud sandbox exec sbx_... -- npm install -g typescript tsx agentuity cloud sandbox snapshot create sbx_... --tag node-typescript ```