Vercel Integration

Use the native Vercel SDK to create and operate your sandbox. APIZ supplies credential issuance and an optional installation command; no sandbox object is passed to APIZ. You retain images, files, commands, timeouts and deletion.

Prerequisites And Installation

First follow the Python installation or TypeScript installation. Install the optional provider package in that same host environment:

# In the virtual environment created by the Python guide
python -m pip install vercel==0.11.2
# In your Node host project
npm install @vercel/[email protected]

These are tested native SDK versions, not a promise of all future versions. Configure the four host APIZ values APIZ_USER_API_KEY, APIZ_SERVER_URL, APIZ_TEAM_ID, APIZ_CLIENT_ID from the language tutorial. Additionally set VERCEL_TOKEN, VERCEL_TEAM_ID, VERCEL_PROJECT_ID on the host. Provider credentials never go to the guest. Your Client must already have the intended Bindings and Policies configured.

The sandbox needs sh, tar, a supported downloader, CA certificates, a writable temporary directory and outbound access to APIZ and its CLI downloads. Native creation options must be chosen by the caller; APIZ does not create a provider template or bypass firewalls.

Python: Create, Grant, Run, Revoke, Delete

Save this as host.py in your host project. With the variables exported, run python host.py in that project with your virtual environment active. This is a live readiness exercise that creates a cloud sandbox; it does not make an upstream service request. Output from CLI inspect is captured.

import os

from apiz.management import Management
from apiz.access import issue_access
from apiz.cli import install_command
from vercel.api import session
from vercel.sandbox import sync as vercel

with Management(
    api_key=os.environ["APIZ_USER_API_KEY"],
    server_url=os.environ["APIZ_SERVER_URL"],
    team_id=os.environ["APIZ_TEAM_ID"],
) as api:
    credentials = vercel.SandboxCredentials(
        token=os.environ["VERCEL_TOKEN"],
        team_id=os.environ["VERCEL_TEAM_ID"],
        project_id=os.environ["VERCEL_PROJECT_ID"],
    )
    with session(
        service_options=[
            vercel.SandboxServiceOptions(credentials_factory=lambda: credentials)
        ]
    ):
        sandbox = vercel.create_sandbox(execution_time_limit=600, persistent=False)
        try:
            result = sandbox.run_process(
                "sh",
                ["-c", install_command(server_url=api.server_url)],
                capture_output=True,
                kill_after=120,
            )
            if result.returncode != 0:
                raise RuntimeError("CLI installation failed")
            with issue_access(
                api,
                client_id=os.environ["APIZ_CLIENT_ID"],
                ttl_seconds=600,
            ) as access:
                command = "/tmp/apiz/bin/apiz --output json client handoff inspect"
                result = sandbox.run_process(
                    "sh",
                    ["-c", command],
                    env=access.export_env(),
                    capture_output=True,
                    kill_after=30,
                )
                if result.returncode != 0:
                    raise RuntimeError("Guest command failed")
            print("PASS: CLI access ready and credential group revoked")
        finally:
            sandbox.destroy()

TypeScript SDK: Native Node Host

Save as host.mjs in the Node project where you installed both packages. With variables exported, run node host.mjs, or put them in a local .env and run node --env-file=.env host.mjs. This uses the same live readiness flow.

import { Management } from "@apiz/sdk/management";
import { issueAccess } from "@apiz/sdk/access";
import { installCommand } from "@apiz/sdk/cli";
import { Sandbox } from "@vercel/sandbox";

/** @param {string} name */
function required(name) {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}

const api = new Management({
  apiKey: required("APIZ_USER_API_KEY"),
  serverUrl: required("APIZ_SERVER_URL"),
  teamId: required("APIZ_TEAM_ID"),
});
try {
  const sandbox = await Sandbox.create({
    token: required("VERCEL_TOKEN"),
    teamId: required("VERCEL_TEAM_ID"),
    projectId: required("VERCEL_PROJECT_ID"),
    timeout: 600_000,
    persistent: false,
  });
  try {
    const installed = await sandbox.runCommand({
      cmd: "sh",
      args: ["-c", installCommand({ serverUrl: api.serverUrl })],
    });
    if (installed.exitCode !== 0) throw new Error("CLI installation failed");
    const access = await issueAccess(api, {
      clientId: required("APIZ_CLIENT_ID"),
      ttlSeconds: 600,
    });
    await access.withAccess(async () => {
      const command = "/tmp/apiz/bin/apiz --output json client handoff inspect";
      const result = await sandbox.runCommand({
        cmd: "sh",
        args: ["-c", command],
        env: access.exportEnv(),
        signal: AbortSignal.timeout(30_000),
      });
      if (result.exitCode !== 0) throw new Error("Guest command failed");
    });
    console.log("PASS: CLI access ready and credential group revoked");
  } finally {
    await sandbox.delete();
  }
} finally {
  await api.close();
}

Run Your Agent Or The Official-Tool Guest

After sandbox creation and before granting access, use the provider's native file API to upload your agent. For the shared S3 guest, read the guest_s3.py file from the guest tutorial into guest_source / guestSource, then upload it:

sandbox.fs.write_bytes("/tmp/guest_s3.py", guest_source.encode(), mode=0o600)

await sandbox.fs.writeFile("/tmp/guest_s3.py", Buffer.from(guestSource), {
  mode: 0o600,
});

Install Python/boto3 with native commands if the chosen image lacks them. Add APIZ_EXAMPLE_BINDING and APIZ_EXAMPLE_OBJECT_KEY through the grant's env option, together with APIZ_CLI_PATH=/tmp/apiz/bin/apiz, then replace the inspect command with python /tmp/guest_s3.py. The full setup/official SDK flow and expected Access Logs are explained in the Python tutorial. For your own agent, substitute its installed entrypoint and configure its official tools with APIZ CLI setup.

Async Python And Explicit Lifetime

Use the async vercel.sandbox.Sandbox under an async configured Vercel session with AsyncManagement and issue_access_async. Keep provider operations native and awaitable; APIZ receives no sandbox object.

with is optional: save the access object and call revoke() in finally; async callers use await access.revoke(). Inspect the cleanup report, especially unknown. TypeScript offers withAccess or explicit await access.revoke(). See Python lifecycle cases and TS lifecycle cases.

Provider-Specific Behavior

Keep the Python session alive

The synchronous Python sandbox uses the configured vercel.api.session for credentials. Keep the session around creation, APIZ preparation, guest commands and sandbox destruction. APIZ copies context variables into its bounded sync workers; it does not replace the Vercel session or discover your token.

The Python package is vercel, while TypeScript uses @vercel/sandbox. VERCEL_TEAM_ID is the Vercel account scope, not APIZ_TEAM_ID. Similarly the Vercel project is not an APIZ Client. If your secret is named VERCEL_API_TOKEN, map it explicitly to the VERCEL_TOKEN value used by this example.

Python returns returncode and optional captured stdout; TypeScript returns exitCode, with output retrieved through native result APIs. Choose a runtime with the CLI installer prerequisites. If adapting the boto3 guest, ensure Python and pip exist or select another official tool available in your runtime.

Cleanup And Troubleshooting

Revoke before closing management/provider scopes. Sandbox destruction and APIZ revocation are independent operations; deleting a sandbox does not replace credential revocation. Expiry is a fallback, not proof that cleanup succeeded. Do not capture active credential environments in reusable snapshots.

Support And Validation Scope

Earlier hosted Python/TS CLI-tool acceptance is recorded for Vercel. This explicit installation/issuance revision has local coverage, not a new hosted acceptance claim.

Native types and local toolchain tests do not establish connectivity for your account. Before relying on the integration, run a representative allowed and denied service request, inspect Access Logs, and confirm revocation and native sandbox cleanup.

Native reference: Vercel documentation.