Container Exec

Execute commands and create interactive terminal sessions in containers

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

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

JavaScript WebSocket

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