Skip to main content

​
Create Exec Instance

POST /api/containers/{id}/exec?envId=1
Creates an exec instance for running commands in a container. This is typically used to establish interactive terminal sessions. The returned exec ID can be used with a WebSocket connection to interact with the terminal.

​
Path Parameters

​
id
string
required
The container ID or name

​
Query Parameters

​
envId
string
required
The environment ID where the container is located

​
Request Body

​
shell
string
default:"/bin/sh"
The shell to execute. Common values:
  • /bin/sh - Bourne shell (most compatible)
  • /bin/bash - Bash shell
  • /bin/zsh - Z shell
  • /bin/ash - Almquist shell (Alpine Linux)
​
user
string
default:"root"
The user to run the command as. Can be:
  • Username (e.g., “root”, “www-data”)
  • UID (e.g., “1000”)
  • UID:GID (e.g., “1000:1000”)

​
Response

​
execId
string
The ID of the created exec instance. Use this with a WebSocket connection to interact with the terminal.
​
connectionInfo
object
Information about the Docker connection for establishing the WebSocket connection
​
type
string
Connection type: “socket”, “http”, “https”, or “hawser-edge”
​
host
string
Docker host address (for http/https connections)
​
port
number
Docker port (for http/https connections)

​
Error Responses

​
error
string
Error message if the request fails
Status Codes:
  • 200 - Exec instance created successfully
  • 401 - Unauthorized (authentication required)
  • 403 - Permission denied
  • 500 - Failed to create exec instance

​
Example

curl -X POST "https://your-dockhand.com/api/containers/abc123def456/exec?envId=1" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-cookie" \
  -d '{
    "shell": "/bin/bash",
    "user": "root"
  }'

​
Response Example

{
  "execId": "f1e2d3c4b5a6",
  "connectionInfo": {
    "type": "socket",
    "host": "localhost",
    "port": 2375
  }
}

​
Using the Exec Instance

After creating an exec instance, establish a WebSocket connection to interact with the terminal:

​
WebSocket Connection

Connect to the exec instance using a WebSocket: 
ws://your-dockhand.com/api/containers/exec/{execId}/attach?envId=1
The WebSocket connection provides:
  • Bidirectional communication: Send commands and receive output
  • Terminal control sequences: Full terminal emulation support
  • Real-time interaction: Interactive shell experience

​
Terminal Interaction

Once connected:
  1. Send terminal input through the WebSocket (keyboard input, control sequences)
  2. Receive terminal output through the WebSocket (command output, prompts)
  3. Handle terminal resize events by sending resize commands
  4. Close the WebSocket when done to terminate the session

​
Example Terminal Session

const execId = 'f1e2d3c4b5a6';
const ws = new WebSocket(
  `ws://your-dockhand.com/api/containers/exec/${execId}/attach?envId=1`
);

ws.onopen = () => {
  console.log('Terminal connected');
  // Send a command
  ws.send('ls -la\n');
};

ws.onmessage = (event) => {
  // Receive terminal output
  console.log('Output:', event.data);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('Terminal disconnected');
};

// Send more commands
setTimeout(() => {
  ws.send('pwd\n');
}, 1000);

// Close the connection
setTimeout(() => {
  ws.send('exit\n');
  ws.close();
}, 5000);

​
Terminal Resize

To resize the terminal (e.g., when the user’s window changes size), send a resize request: 
POST /api/containers/exec/{execId}/resize?h=24&w=80&envId=1
Parameters:
  • h: Height in rows (e.g., 24)
  • w: Width in columns (e.g., 80)
  • envId: Environment ID

​
Notes

  • The exec instance is created with TTY and stdin enabled for interactive use
  • Each exec instance is single-use - create a new one for each terminal session
  • The WebSocket connection must be established promptly after creating the exec instance
  • Closing the WebSocket terminates the exec session
  • All terminal emulation features are supported (colors, cursor movement, etc.)
  • The default shell /bin/sh is the most portable across different container images

Build docs developers (and LLMs) love

Get started for freeTalk to us