Run An Agent Safely In A Remote Sandbox

See Choose And Use An APIZ SDK for the host SDK versus Policy SDK boundary and runnable Python/TypeScript examples.

Use Client Handoff when a remote sandbox, CI runner, or ephemeral VM needs APIZ configuration without an operator login or plaintext package transfer. The operator creates a Credential Group once; its default APIZ token can recover only that group's encrypted Setup Manifest through the Data Plane.

Prepare Access In The Web Console

1. Create or choose a Client with only the required API Bindings and Policies.
2. Select Create credentials and create a Credential Group with a short expiry and only the bindings needed by the sandbox.
3. Use Copy APIZ token to save the default token. Do not copy the upstream credentials or the operator browser session.
4. Inject that token into the sandbox's secret mechanism as APIZ_TOKEN and inject the public Data Plane URL as APIZ_PROXY_URL.

The Setup Manifest contains APIZ-issued credentials and remains sensitive. The encrypted envelope is recoverable only while the group and default token remain active.

Recover Configuration In The Sandbox

Install the version-matched public apiz CLI, then run without an operator Context, Team, or Control Plane login:

apiz client handoff inspect --proxy "$APIZ_PROXY_URL"
apiz client handoff setup \
  --proxy "$APIZ_PROXY_URL" \
  --binding github \
  --format shell > apiz-setup.sh
chmod 600 apiz-setup.sh

For automation, APIZ_TOKEN or --token-stdin is supported. There is no --token <value> argument that would expose the value in process arguments. Use adapter formats such as aws-credentials, curl, dotenv, sdk-args, or cli-flags only when advertised by the Setup Manifest item.

Verify And Tear Down

Run one safe smoke request and one expected Policy denial. Access Logs should attribute both to the sandbox's Client and Credential Group without revealing the token or upstream credential.

Delete rendered plaintext after configuring the process. When the sandbox is destroyed or suspected compromised, revoke the group:

apiz client credentials revoke <credential-group-id>

Revocation invalidates every active credential from that issuance. It does not affect other Clients or require rotating upstream service credentials.

Safety Boundaries

• Handoff cannot create, extend, revoke, or manage Control Plane resources.
• The presented token derives Client and group scope; no Client id is trusted from the caller.
• Do not bake APIZ tokens or rendered setup into images, logs, prompts, or repository files.
• Use one Client or Credential Group per independently revocable sandbox.

Choose A Connection After Issuance

Create credentials from the Client page after reviewing APIs and expiry. The result provides Copy APIZ token independently of the service configuration. Choose the API, a compatible Connection (Path or Domain Routing), and format before copying configuration. This reuses the same credentials and expiry.

For remote use, inject the token as APIZ_TOKEN and the public endpoint as APIZ_PROXY_URL. apiz client handoff setup --format json returns prepared items and their connection ids. Use --connection item_id=connection_id with handoff setup or client setup render to select one. Values come from that manifest, not guessed adapter names. Old groups without connection snapshots retain their original endpoint. Changing an S3 endpoint requires signing a new request; never edit the hostname of an already signed URL.