Docs

Volcano Engine Function as a Service

Sandbox instances

A sandbox instance is a secure and isolated container runtime environment that is implemented in the cloud sandbox based on the sandbox image. After creating a sandbox application, you can create a sandbox instance based on a sandbox image. This topic mainly introduces the methods for creating and managing sandbox instances.

Creating sandbox instances

Prerequisites

A sandbox application has been created. For details, see Creating sandbox applications.

Procedure

In the top navigation bar, select the target region.

In the left navigation pane, click Cloud sandbox > Sandbox app. Find the target sandbox application and click its name.

On the details page of that sandbox application, select the Sandbox instances tab and click Create sandbox Instances.

Configure the sandbox instance parameters according to the following description.

Parameter	Description
For sandbox images
Container image	Configure container images for sandbox instances: Use the same image: reuse the container image that was used when creating the instance application. There is no need to configure start command and listening port for instance in this case. Use another image: use another image instead of reusing the old one. You can select a public image or custom image as needed, and then configure start command and listening port.
Startup command	The start command for sandbox instances. If you need to execute a script file instead, ensure entering an absolute path and the script file has execute permission.
Listening port	The listening port of the HTTP Server for the sandbox instance. warning Avoid using the ports that are already occupied by veFaaS: 9000, 9001, 9990. The enabled HTTP server needs to listen on 0.0.0.0:Port or *:Port. Otherwise, a request timeout error will occur.
Instance configuration
Instance specification	Set the number of vCPU and memory capacity for the instance. By default, the instance specification set with the sandbox application will be applied. You can also adjust it as needed according to the prompts on the page.
Instance lifetime	Sandbox instance lifetime. Instances will be terminated upon reaching the end of their lifetime.
Environment variables
Environment variables	The environment variables of each sandbox instance. If not configured, the ones from the sandbox application will be applied instead. If a sandbox instance and the application both have an environment variable with the same key, the value set for the former instance will overwrite that for the latter.
Advanced settings
Instance metadata	The metadata of the instance label. Example: user:2100******. You can use metadata <key,value> to filter sandbox instances. Here are some scenarios: using it to associate sandbox instances with user sessions. using it to store custom user data for sandbox instances, e.g., API secret keys. Associate a sandbox instance with a user ID to facilitate subsequent connections to the cloud sandbox.
Execution timeout	Set an execution timeout as needed. If the instance does not start up within the timeout specified here, the process will quit and return an error.
TOS storage configuration	If TOS mount is enabled for a sandbox application, the subdirectories of a TOS Bucket can be mounted to instances. If not enabled, the TOS configuration of the sandbox application will be applied.

Check the billing information, then click Confirm to start creating the sandbox instance.

Viewing and managing sandbox instances

After successfully creating a sandbox instance, you can search for it by using the search box on the Sandbox instance tab and perform actions on it by using the options in Actions column.

Operation	Description
Search box	You can search instances by name, metadata, or image address. When searching using instance metadata, enter a key-value pair in the key=value format to find the sandbox instance.
View logs	View logs related to the sandbox instance.
Webshell	Log in to the instance Webshell and execute commands to perform operations such as viewing the environment information of the instance, and performing function debugging. The following commands can be used to view the environment information of instances: Get the proc id of the Sandbox service: ps aux \| grep "sandbox" tip If you are using a custom image, you need to change sandbox to the main process name of your custom image application. View the process env: cat /proc/${your_sandbox_proc_id}/environ \| tr '\0' '\n' tip Replace ${your_sandbox_proc_id} with the actual Sandbox service process ID you get in previous step. For example, if the process ID is 15, the complete command is: cat /proc/15/environ \| tr '\0' '\n'.
Modify lifetime	Modify the lifetime of the cloud sandbox instance. The instance will be terminated upon reaching the end of the lifetime.
Delete	Delete a sandbox instance. This action cannot be undone.

Accessing sandbox instances

Domain names for accessing sandbox instances can be found on the Sandbox instances tab if the corresponding sandbox application already has Gateway routing enabled. You can access a specific sandbox instance by using either a unified domain name or a wildcard domain name.

When configuring a unified domain name for gateway routing, you can use a unified APIG domain name to access the specified sandbox instance. Parameters can be passed in by using two methods.

tip

A request sent to a unified domain without either the query parameter or the header will be forwarded to a random sandbox instance.

Include the faasInstanceName field (sandbox instance name) as a query parameter. From the instance list, you can directly obtain the URL generated by concatenating the domain name and query parameter.

Include x-faas-instance-name (sandbox instance name) in the request headers.

If a wildcard domain is applied in gateway routing, each instance will have a unique access address.

Last updated: 2026.08.19 14:06:07