Skip to main content
Version: 1.6.x

API Reference

This guide provides detailed information about the core API services provided by the ROCK platform, including sandbox environment management and GEM environment interaction.

1. Overview​

The ROCK platform provides two core API services:

  • Sandbox API: Sandbox environment management
  • GEM API: GEM environment interaction

All API interfaces follow RESTful design principles and support JSON format data exchange.

2. Sandbox API​

Full lifecycle management functions for sandbox environments:

Sandbox Management Interfaces​

  1. Start Sandbox - Start a sandbox environment

    • Create a new sandbox instance
    • Support specifying image, resource configuration and other parameters

  2. Start Sandbox Async - Asynchronously start a sandbox environment

    • Asynchronously create a sandbox instance
    • Suitable for scenarios requiring quick response

  3. Check Sandbox Alive Status - Check sandbox alive status

    • Verify if the sandbox is running normally

  4. Get Sandbox Statistics - Get sandbox statistics

    • Get resource usage statistics of the sandbox

  5. Get Sandbox Status - Get detailed sandbox status

    • Get complete status information of the sandbox

  6. Stop Sandbox - Stop sandbox environment

    • Safely shut down the sandbox instance

  7. Commit Sandbox - Commit sandbox as image

    • Save current sandbox state as a new image

Command Execution Interfaces​

  1. Execute Command - Execute command in sandbox

    • Run specified command directly in the sandbox

  2. Create Bash Session - Create Bash session

    • Create a persistent Bash session environment

  3. Run Command in Session - Run command in session

    • Execute command in a created session

  4. Close Session - Close session

    • Release session resources

File Operation Interfaces​

  1. Read File - Read sandbox file

    • Read specified file content from the sandbox

  2. Write File - Write sandbox file

    • Write file to the sandbox

  3. Upload File - Upload file to sandbox

    • Upload local file to the sandbox

3. GEM API​

GEM environment interaction functions:

  1. Make Environment - Create GEM environment

    • Initialize a new GEM environment instance

  2. Reset Environment - Reset GEM environment

    • Reset GEM environment to initial state

  3. Step Environment - Execute GEM environment step

    • Execute an action step in the GEM environment

  4. Close Environment - Close GEM environment

    • Release GEM environment resources

4. HTTP API Usage Examples​

4.1 Sandbox API Examples​

Start Sandbox​

curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/start' \
-H 'Content-Type: application/json' \
-d '{
  "image": "python:3.11",
  "resources": {
    "cpu": "2",
    "memory": "8g"
  }
}'

Asynchronously Start Sandbox​

curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/start_async' \
-H 'Content-Type: application/json' \
-d '{
  "image": "python:3.11",
  "resources": {
    "cpu": "2",
    "memory": "8g"
  }
}'

Execute Command​

curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/execute' \
-H 'Content-Type: application/json' \
-d '{
  "sandbox_id": "sandbox-12345",
  "command": "ls -la"
}'

Create Session​

curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/create_session' \
-H 'Content-Type: application/json' \
-d '{
  "sandbox_id": "sandbox-12345",
  "session": "my_session"
}'

Run Command in Session​

curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/run_in_session' \
-H 'Content-Type: application/json' \
-d '{
  "sandbox_id": "sandbox-12345",
  "session": "my_session",
  "command": "python script.py"
}'

Upload File​

curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/upload' \
-F 'file=@./local_file.txt' \
-F 'target_path=./remote_file.txt' \
-F 'sandbox_id=sandbox-12345'

Stop Sandbox​

curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/stop' \
-H 'Content-Type: application/json' \
-d '{
  "sandbox_id": "sandbox-12345"
}'

4.2 GEM API Examples​

# Create GEM environment
curl -X POST 'http://localhost:8080/apis/v1/envs/gem/make' \
-H 'Content-Type: application/json' \
-d '{"env_id": "game:Sokoban-v0-easy"}'

# Reset environment
curl -X POST 'http://localhost:8080/apis/v1/envs/gem/reset' \
-H 'Content-Type: application/json' \
-d '{"sandbox_id": "sandbox-12345", "seed": 42}'

# Execute step
curl -X POST 'http://localhost:8080/apis/v1/envs/gem/step' \
-H 'Content-Type: application/json' \
-d '{"sandbox_id": "sandbox-12345", "action": "random_action"}'

# Close environment
curl -X POST 'http://localhost:8080/apis/v1/envs/gem/close' \
-H 'Content-Type: application/json' \
-d '{"sandbox_id": "sandbox-12345"}'