Agent Instance Command Execution (exec)

Agent Instance Command Execution (exec)#

Description#

This API executes commands inside an already-created Agent instance’s own container. The command runs directly in the agent instance’s own sandbox; no additional sandbox container is created.

Differences from other instance APIs:

Invoke Agent Instance (invoke): invokes the function logic hosted by the agent instance;
Sandbox APIs: create a separate sub-sandbox to run commands.

exec reuses the instance’s own container and can be combined with Agent Instance File Operations (file upload/download, directory creation) for file management and environment inspection inside the instance.

Constraints#

instanceId must be the instance_id (UUID) returned when the Agent instance was created. A non-existent or already-deleted instance returns 404.
Authentication goes through frontend’s global GlobalJWTAuthMiddleware, consistent with other function service REST APIs. When enable_func_token_auth is on, a valid JWT must be carried (see the auth section of Agent Instance Protocol Invocation Channels).
The request body must be valid JSON; command is a required field. Type errors in working\_dir, env, or timeout return 400.
The request body and response body size cap is 512MB; exceeding it returns 413.
timeout must be greater than 0. If empty, the default timeout of 300 seconds applies. After the timeout, the command’s process group (including child processes) is force-killed with SIGKILL and returncode returns -1.
This API blocks synchronously until the command completes or times out. Do not run long-hanging commands.
When the Executor’s concurrent request limit is exceeded, 503 is returned; retry later.

Interface Definition#

URI: POST /api/agent/{instanceId}/exec

The request method is POST with Content-Type application/json (JSON request body).

Request Path Parameters#

Parameter	Required	Type	Description
instanceId	Yes	string	Instance ID (the UUID returned at creation).

Request Parameters (Body, JSON)#

Parameter	Required	Type	Description
command	Yes	string or `array<string>`	The command to execute. A string is executed through `/bin/sh -c`; an array is executed directly as argv.
working_dir	No	string	Working directory for command execution. If empty, the instance process’s current working directory is used.
env	No	`object<string, string>`	Environment variables for command execution. If empty, the instance process’s environment is inherited.
timeout	No	number	Timeout in seconds; must be greater than 0. If empty, the default timeout of 300 seconds applies. After the timeout the command’s process group is force-killed and returncode returns -1.

Response Parameters#

Name	Type	Description
returncode	int	Command return code. 0 means success; -1 means timeout or execution error.
stdout	string	Standard output.
stderr	string	Standard error. Contains timeout information on timeout.

Note: HTTP 200 only indicates the command execution flow completed; whether the command itself succeeded is determined by returncode (0 means success, -1 means timeout or execution error).

Request Examples#

Execute a simple command (string form, executed via /bin/sh -c):

curl -X POST "http://{frontend}:8888/api/agent/{instanceId}/exec" \
  -H "Content-Type: application/json" \
  -H "X-Auth: {access_token}" \
  -d '{"command": "ls -la /tmp"}'

With working directory and environment variables:

curl -X POST "http://{frontend}:8888/api/agent/{instanceId}/exec" \
  -H "Content-Type: application/json" \
  -H "X-Auth: {access_token}" \
  -d '{"command": "echo $MY_VAR", "working_dir": "/home/agentos", "env": {"MY_VAR": "hello"}}'

command as an array (argv form):

curl -X POST "http://{frontend}:8888/api/agent/{instanceId}/exec" \
  -H "Content-Type: application/json" \
  -H "X-Auth: {access_token}" \
  -d '{"command": ["/bin/sh", "-c", "echo hello > /tmp/out.txt"]}'

Response Examples#

Command succeeded:

{"returncode": 0, "stdout": "total 8\ndrwxr-xr-x 2 root root 4096 ...", "stderr": ""}

Command timed out (e.g. the caller set "timeout": 5):

{"returncode": -1, "stdout": "", "stderr": "Command timed out after 5 seconds"}

Error Codes#

HTTP status	Description
200	Command execution completed. `returncode` may be non-zero; see `returncode`/`stdout`/`stderr` for details.
400	Bad request. `command` field missing, `working_dir`/`env`/`timeout` type errors, or the request body is not valid JSON.
404	Instance does not exist or has been deleted.
413	Request body or response body exceeds the 512MB limit.
500	Internal server error.
503	Executor overloaded (concurrent request limit exceeded).

Usage Notes#

Commands run inside the agent instance’s own container and can access the instance filesystem. Combined with file upload/download and directory creation APIs, in-instance file management is possible (see Agent Instance File Operations).
A string command is equivalent to shell execution and supports pipes, redirection, and other shell syntax. Use the array form when precise argv control is needed or to avoid shell parsing ambiguity.
Set a reasonable timeout for long-running commands; on timeout the process group (including child processes) is killed with SIGKILL and stderr contains timeout information.
This API blocks synchronously until the command completes or times out. Do not run long-hanging commands (e.g. persistent foreground processes); such scenarios should be handled by the business logic hosted in the instance itself.