feat: support for agent sandboxes

docs/sandboxes.md

@@ -0,0 +1,154 @@
+# Sandbox Quickstart
+
+## Install
+
+```bash
+npm install github:adobe/aio-lib-runtime#agent-sandboxes
+```
+
+## Init
+
+```js
+const { init } = require('@adobe/aio-lib-runtime')
+
+const runtime = await init({
+  apihost: process.env.AIO_RUNTIME_APIHOST,
+  namespace: process.env.AIO_RUNTIME_NAMESPACE,
+  api_key: process.env.AIO_RUNTIME_AUTH
+})
+```
+
+## Create Sandbox
+
+```js
+const sandbox = await runtime.compute.sandbox.create({
+  name: 'my-sandbox',
+  type: 'cpu:nodejs',
+  workspace: 'workspace',
+  maxLifetime: 3600,
+  envs: {
+    API_KEY: 'your-api-key'
+  }
+})
+```
+
+## Get Status
+
+```js
+const status = await runtime.compute.sandbox.getStatus(sandbox.id)
+console.log('status:', status)
+```
+
+## Preview URLs
+
+Use preview URLs to get access to servers or web services running in a sandbox on a particular port: 
+
+```js
+const url = await sandbox.getUrl({ port: 3000 })
+console.log('preview:', url)
+// https://sb-abc123-va6-0-xK3mPq2nAeB-3000.sandbox-adobeioruntime.net
+```
+
+## Exec
+
+```js
+const result = await sandbox.exec('ls -al', { timeout: 10000 })
+console.log('stdout:', result.stdout.trim())
+console.log('exit code:', result.exitCode)
+```
+
+## File Management
+
+```js
+const script = `console.log('hello from sandbox script', process.version)\n`
+await sandbox.writeFile('hello.js', script)
+
+const content = await sandbox.readFile('hello.js')
+console.log('readFile content:', content.trim())
+
+const entries = await sandbox.listFiles('.')
+console.log('listFiles entries:', entries)
+```
+
+## Exec a File
+
+```js
+const result = await sandbox.exec('node hello.js', { timeout: 10000 })
+console.log('stdout:', result.stdout.trim())
+console.log('stderr:', result.stderr.trim())
+console.log('exit code:', result.exitCode)
+```
+
+## Curl a Site
+
+```js
+const result = await sandbox.exec('curl -s --connect-timeout 5 -o /dev/null -w "%{http_code}" https://github.com', { timeout: 10000 })
+console.log(`  github.com   (allowed) → HTTP ${result.stdout.trim()}`)
+```
+
+## Write to Stdin
+
+### Command start
+```js
+const result = await sandbox.exec('python process_csv.py', {
+  stdin: 'col1,col2\nval1,val2\n',
+  timeout: 10000
+})
+console.log('stdout:', result.stdout.trim())
+```
+
+### Running command
+```js
+const execPromise = sandbox.exec('cat')
+sandbox.writeStdin(execPromise.execId, 'line 1\n')
+sandbox.writeStdin(execPromise.execId, 'line 2\n')
+sandbox.closeStdin(execPromise.execId)
+
+const result = await execPromise
+console.log('stdout:', result.stdout.trim())
+```
+
+## Destroy
+
+```js
+await sandbox.destroy()
+```
+
+---
+
+## Network Policies
+
+Sandboxes are default-deny. All outbound traffic is blocked unless explicitly allowed.
+
+Pass a `policy.network.egress` array at creation time to allowlist outbound endpoints, paths, or HTTP verbs.
+
+```js
+const sandbox = await runtime.compute.sandbox.create({
+  name: 'policy-sandbox',
+  workspace: 'policy-test',
+  maxLifetime: 300,
+  policy: {
+    network: {
+      egress: [
+        { host: 'httpbin.org', port: 443 },
+        {
+          host: 'api.github.com',
+          port: 443,
+          rules: [{ methods: ['GET'], pathPattern: '/repos/**' }]
+        }
+      ]
+    }
+  }
+})
+```
+
+### Allow All (Not recommended for production)
+
+```js
+const sandbox = await runtime.compute.sandbox.create({
+  name: 'policy-allow-all',
+  workspace: 'policy-test',
+  maxLifetime: 300,
+  policy: { network: { egress: 'allow-all' } }
+})
+```

package.json

@@ -28,7 +28,8 @@
     "openwhisk-fqn": "0.0.2",
     "proxy-from-env": "^1.1.0",
     "sha1": "^1.1.1",
-    "webpack": "^5.26.3"
+    "webpack": "^5.26.3",
+    "ws": "^8.19.0"
   },
   "deprecated": false,
   "description": "Adobe I/O Runtime Lib",

src/ComputeAPI.js

@@ -0,0 +1,29 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+const SandboxAPI = require('./SandboxAPI')
+
+/**
+ * Compute management API.
+ */
+class ComputeAPI {
+  /**
+   * @param {string} apiHost Runtime API host
+   * @param {string} namespace Runtime namespace
+   * @param {string} apiKey Runtime auth key
+   * @param {object} [options] SDK transport options
+   */
+  constructor (apiHost, namespace, apiKey, options = {}) {
+    this.sandbox = new SandboxAPI(apiHost, namespace, apiKey, options)
+  }
+}
+
+module.exports = ComputeAPI

src/RuntimeAPI.js

@@ -17,6 +17,7 @@ const deepCopy = require('lodash.clonedeep')
 const aioLogger = require('@adobe/aio-lib-core-logging')('@adobe/aio-lib-runtime:RuntimeAPI', { provider: 'debug', level: process.env.LOG_LEVEL })
 const LogForwarding = require('./LogForwarding')
 const LogForwardingLocalDestinationsProvider = require('./LogForwardingLocalDestinationsProvider')
+const ComputeAPI = require('./ComputeAPI')
 const { patchOWForTunnelingIssue } = require('./openwhisk-patch')
 const { getProxyAgent } = require('./utils')
 
@@ -106,6 +107,12 @@ class RuntimeAPI {
         new LogForwardingLocalDestinationsProvider(),
         clonedOptions.auth_handler
       ),
+      compute: new ComputeAPI(
+        clonedOptions.apihost,
+        clonedOptions.namespace,
+        clonedOptions.api_key,
+        clonedOptions
+      ),
       initOptions: clonedOptions
     }
   }

src/SDKErrors.js

@@ -49,3 +49,8 @@ module.exports = {
 
 // Define your error codes with the wrapper
 E('ERROR_SDK_INITIALIZATION', 'SDK initialization error(s). Missing arguments: %s')
+E('ERROR_SANDBOX_CLIENT', 'Sandbox client error: %s')
+E('ERROR_SANDBOX_NOT_FOUND', 'Sandbox not found: %s')
+E('ERROR_SANDBOX_UNAUTHORIZED', 'Sandbox authorization error: %s')
+E('ERROR_SANDBOX_TIMEOUT', 'Sandbox timeout error: %s')
+E('ERROR_SANDBOX_WEBSOCKET', 'Sandbox WebSocket error: %s')