Embedenv WebSocket Protocol API Documentation

Anatomy of a WebSocket TCP Pipeline

A step-by-step sequential workflow of the bi-directional communication channels inside Embedenv active virtual environments:

Init connection handshake {"type": "init"} Dispatches credentials payload and sets up verified join key.

Inject project file tree {"type": "project"} Maps and syncs the code repository structure to the container.

Write file content streams {"type": "write"} Streams text updates instantly to virtual files with debounced syncs.

Execute script commands {"type": "shell"} Compiles or runs scripts inside isolated VM container and pipes outputs.

Terminate VM processes Ctrl+C / Kill Safely aborts running compilers or shuts down active web server ports.

1. Connect & Handshake

Initialize a secure collaborative workspace session to the live sandboxing clusters. Pass your valid public_key and secret_key in the handshake payload. 1 credit will be deducted from your paid credit pool upon a successful handshake connection.

A. Secure Workspace Initialization (Host) JSON

Starts a fresh sandboxed container. This action requires credentials and deducts 1 credit.

{
  "type": "init",
  "public_key": "YOUR_PUBLIC_KEY",
  "secret_key": "YOUR_SECRET_KEY"
}

Exact Server Response JSON

{
  "type": "init",
  "join": "GENERATED_JOIN_KEY",
  "remaining_credits": 999
}

B. Collaboration Workspace Joining (Collaborator) JSON

Join an already active room using the generated join key. This is free/legacy and requires no credentials.

{
  "type": "join",
  "join": "GENERATED_JOIN_KEY",
  "user": "collaborator",
  "color": "#6366f1"
}

Security Best Practice: Backend-to-Frontend Token Exchange

To prevent exposing your sensitive secret_key to end-users in frontend web applications, we strongly recommend implementing a secure Backend-to-Frontend Exchange architecture:

Your secure backend server connects to our WebSocket endpoint and sends {"type": "init", "public_key": "...", "secret_key": "..."} to host the session.
Our server charges the host's credit balance and responds with a safe, temporary join session key.
Your backend server forwards this join key to your frontend application.
Your frontend clients then connect directly to our WebSocket and join using {"type": "join", "join": "GENERATED_KEY", "user": "..."}. No credentials required, maximum security!

E2E Secure WebSocket Integration Example

Here is a step-by-step example showing how to connect to the WebSocket securely using Python (Backend) and native Javascript (Frontend).

This Python script initializes the session securely on your backend and retrieves the temporary join key.

import asyncio
import json
import websockets

async def get_secure_websocket_token():
    uri = "wss://embedenv.com/ws/spaces/defoult/"
    
    # Establish initialization connection
    async with websockets.connect(uri) as websocket:
        init_payload = {
            "type": "init",
            "public_key": "YOUR_PUBLIC_KEY_PLACEHOLDER",
            "secret_key": "YOUR_SECRET_KEY_PLACEHOLDER"
        }
        
        # Send initialization handshake
        await websocket.send(json.dumps(init_payload))
        
        # Receive connection response
        response = await websocket.recv()
        data = json.loads(response)
        
        if data.get("type") == "init" and "join" in data:
            join_key = data["join"]
            print(f"Secure Token obtained successfully: {join_key}")
            return join_key
        else:
            raise Exception("Secure Workspace Initialization failed.")

# Execute secure handshake
join_token = asyncio.run(get_secure_websocket_token())

This client-side Javascript code connects directly to the WebSocket proxy and joins using the secure token.

// Retrieve the temporary join token securely from your backend server
const secureJoinToken = "SECURE_TOKEN_FROM_YOUR_BACKEND"; 

// Connect to the WebSocket Proxy
const wsUri = "wss://embedenv.com/ws/spaces/defoult/";
const ws = new WebSocket(wsUri);

ws.onopen = function() {
    // Send secure join payload (no private keys exposed!)
    const joinPayload = {
        "type": "join",
        "join": secureJoinToken,
        "user": "developer_collaborator",
        "color": "#6366f1"
    };
    ws.send(JSON.stringify(joinPayload));
    console.log("WebSocket secure join handshake dispatched!");
};

ws.onmessage = function(event) {
    const response = JSON.parse(event.data);
    console.log("Message received from Bridge:", response);
};

2. Deploy Project Files

Prepare the remote sandbox architecture workspace with a custom virtual file tree mapping injection.

Request Payload JSON

{
  "type": "cmd",
  "project_name": "unified_workspace",
  "command": { "type": "project" },
  "file_structure": "{\"name\":\"project\",\"type\":\"folder\",\"children\":[{\"name\":\"main.py\",\"type\":\"file\",\"content\":\"print('Root File Loaded Successfully')\"}]}"
}

Exact Server Response JSON

{
  "type": "msg",
  "message": "project created"
}

3. Create New File

Instantiate a new workspace source module (e.g. utils.py) dynamically on the virtual container filesystem.

Request Payload JSON

{
  "type": "cmd",
  "project_name": "unified_workspace",
  "command": {
    "type": "create",
    "item": "file",
    "name": "utils.py",
    "rpath": "",
    "path": "project/utils.py",
    "root": {},
    "targetElementData": {}
  }
}

Exact Server Response JSON

/* Client managed update (No server logging frame response) */
{}

4. Update/Write File Content

Write high-fidelity code contents directly into a virtual file path, triggering atomic sync events on the execution target.

Request Payload JSON

{
  "type": "cmd",
  "project_name": "unified_workspace",
  "command": { "type": "write" },
  "path": "project/utils.py",
  "content": "def test_node():\n    return 'Utility Active'"
}

Exact Server Response JSON

/* Client managed update (No server logging frame response) */
{}

5. Rename File/Folder

Alter the directory coordinates of a workspace element cleanly using path renaming operations.

Request Payload JSON

{
  "type": "cmd",
  "project_name": "unified_workspace",
  "command": {
    "type": "rename"
  },
  "path": "project/utils.py",
  "rpath": "utils.py",
  "name": "core_utils.py",
  "root": {}
}

Exact Server Response JSON

/* Client managed update (No server logging frame response) */
{}

6. Delete File/Folder

Perform complete, safe unlinking of specific codebase components inside the sandbox structure.

Request Payload JSON

{
  "type": "cmd",
  "project_name": "unified_workspace",
  "command": {
    "type": "delete"
  },
  "path": "project/core_utils.py",
  "rpath": "core_utils.py",
  "targetElementData": {}
}

Exact Server Response JSON

/* Client managed update (No server logging frame response) */
{}

7. Run Simple Python App

Execute shell commands inside the remote sandbox environment, receiving console stdout/stderr streams in real-time.

Request Payload JSON

{
  "type": "cmd",
  "project_name": "unified_workspace",
  "command": {
    "type": "shell",
    "command": "cd project && python -u main.py"
  }
}

Exact Server Response Stream JSON Stream

{
  "type": "terminal-data",
  "data": "Root File Loaded Successfully"
}
{
  "type": "terminal-newline",
  "data": ""
}
{
  "type": "terminal-data-end"
}

8. Inject Interactive Input Code

Overwrite the entry script (main.py) with code expecting interactive stdin prompt values.

Request Payload JSON

{
  "type": "cmd",
  "project_name": "unified_workspace",
  "command": { "type": "write" },
  "path": "project/main.py",
  "content": "val = input('PROMPT: Enter Target String Name:')\nprint(f'Engine Captured Input Data Block: {val}')"
}

Exact Server Response JSON

/* Client managed update (No server logging frame response) */
{}

9. Run Interactive Input App

Launch the modified interactive script, opening an interactive execution buffer waiting for input packets.

Request Payload JSON

{
  "type": "cmd",
  "project_name": "unified_workspace",
  "command": {
    "type": "shell",
    "command": "cd project && python -u main.py"
  }
}

Exact Server Response Stream JSON Stream

{
  "type": "terminal-data",
  "data": "PROMPT: Enter Target String Name:"
}
{
  "type": "terminal-newline",
  "data": ""
}

10. Send Standard Input Value

Send raw keyboard strings into the active input stream buffer to satisfy runtime requirements.

Request Payload JSON

{
  "type": "cmd",
  "project_name": "unified_workspace",
  "command": {
    "type": "shell",
    "command": "CloudIDEEngineAdminUserPassed"
  }
}

Exact Server Response Stream JSON Stream

{
  "type": "terminal-data",
  "data": "Engine Captured Input Data Block: CloudIDEEngineAdminUserPassed"
}
{
  "type": "terminal-newline",
  "data": ""
}
{
  "type": "terminal-data-end"
}

11. Start Local Web Server

Launch an internal server process on custom port 3000 inside the secure execution container.

Request Payload JSON

{
  "type": "cmd",
  "project_name": "unified_workspace",
  "command": {
    "type": "shell",
    "command": "cd project && python -m http.server 3000"
  }
}

Exact Server Response Stream JSON Stream

{
  "type": "terminal-data",
  "data": "Serving HTTP on 0.0.0.0 port 3000 (http://0.0.0.0:3000/) ..."
}
{
  "type": "terminal-newline",
  "data": ""
}

12. Curl Web Proxy App Data

Verify internal port bindings by executing high-fidelity proxy requests inside the container proxy loop.

Request Payload JSON

{
  "type": "cmd",
  "project_name": "unified_workspace",
  "command": { "type": "curl" },
  "method": "GET",
  "url": "http://localhost:3000",
  "headers": {},
  "data": ""
}

Exact Server Chunked Splitted Response JSON (Stream Fragments)

{ "type": "chunk", "content": "<!DOCTYPE html>" }
{ "type": "chunk", "content": "<html lang=\"en\">" }
{ "type": "head><meta charset=\"utf-8\"/></head>" }
{ "type": "body", "content": "Fixed HTML Trigger Engine!" }
{ "type": "chunk", "content": "</html>" }
{ "type": "end" }

13. Terminate Web Server (Ctrl+C)

Send standard interrupt kill sequences (Ctrl+C) to terminate active long-running network servers.

Request Payload JSON

{
  "type": "cmd",
  "project_name": "unified_workspace",
  "command": {
    "type": "shell",
    "command": "Ctrl+C"
  }
}

Exact Server Response JSON

{
  "type": "terminal-data-end"
}

14. Verify Storage Space (ls -la)

Scan remaining items, checking relative paths and permission masks of compiled artifacts.

Request Payload JSON

{
  "type": "cmd",
  "project_name": "unified_workspace",
  "command": {
    "type": "shell",
    "command": "cd project && ls -la"
  }
}

Exact Server Response Stream JSON Stream

{ "type": "terminal-data", "data": "total 8" }
{ "type": "terminal-data", "data": "drwxr-sr-x. 2 user user 37 May 18 10:21 ." }
{ "type": "terminal-data", "data": "-rw-r--r--. 1 user user 99 May 18 10:23 main.py" }
{ "type": "terminal-data", "data": "-rw-r--r--. 1 user user 62 May 18 10:21 utils.py" }
{ "type": "terminal-data-end" }