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 a 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, and 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 a 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 a 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, and 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, and 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 a 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 the internal server process on custom port 3000 inside a 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, and stop Web Server (Ctrl+C)

Send standard interrupt kill sequences (Ctrl+C) to kill 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" }