Skip to main content
Manage the lifecycle of your containers with these operations.

​
Start Container

POST /api/containers/:id/start
Starts a stopped container. If the container was removed from Docker but exists in the database, it will be automatically recreated with the same configuration and data.

​
Path Parameters

​
id
string
required
Container ID (Docker ID or database ID)

​
Request Headers

​
Authorization
string
required
Bearer token for authentication

​
Response

​
message
string
Success message: “container started” or “container recreated and started”
​
id
string
Container Docker ID
​
name
string
Container name
​
status
string
New status: “running”
​
recreated
boolean
True if container was recreated (only present when recreated)
​
volume_kept
boolean
True if volume data was preserved (only present when recreated)

​
Status Codes

  • 200 OK - Container started successfully
  • 401 Unauthorized - Missing or invalid API token
  • 403 Forbidden - Guest session expired or insufficient permissions
  • 404 Not Found - Container not found
  • 500 Internal Server Error - Failed to start container

​
Examples

curl -X POST https://your-rexec-instance.com/api/containers/a3b5c7d9e1f2/start \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
Response Example

{
  "message": "container started",
  "id": "a3b5c7d9e1f2",
  "name": "dev-environment",
  "status": "running"
}

​
Recreation Response

{
  "message": "container recreated and started",
  "id": "f9e8d7c6b5a4",
  "old_id": "a3b5c7d9e1f2",
  "name": "dev-environment",
  "status": "running",
  "recreated": true,
  "volume_kept": true
}
Automatic Recreation: If a container was removed from the Docker host but still exists in the database, starting it will automatically recreate the container with the same configuration. Your data is preserved if the volume still exists.

​
Stop Container

POST /api/containers/:id/stop
Stops a running container. The container’s data is preserved and can be started again later.

​
Path Parameters

​
id
string
required
Container ID (Docker ID or database ID)

​
Request Headers

​
Authorization
string
required
Bearer token for authentication

​
Response

​
message
string
Success message: “container stopped”
​
id
string
Container Docker ID
​
name
string
Container name
​
status
string
New status: “stopped”

​
Status Codes

  • 200 OK - Container stopped successfully
  • 401 Unauthorized - Missing or invalid API token
  • 404 Not Found - Container not found
  • 500 Internal Server Error - Failed to stop container

​
Examples

curl -X POST https://your-rexec-instance.com/api/containers/a3b5c7d9e1f2/stop \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
Response Example

{
  "message": "container stopped",
  "id": "a3b5c7d9e1f2",
  "name": "dev-environment",
  "status": "stopped"
}
For Agents: Stopping an agent (ID with agent: prefix) disconnects the WebSocket connection but doesn’t affect the remote server. The agent can reconnect automatically.

​
Delete Container

DELETE /api/containers/:id
Deletes a container. This is a soft delete - the container is stopped and marked as deleted in the database. Data may be retained based on your instance’s cleanup policy.

​
Path Parameters

​
id
string
required
Container ID (Docker ID or database ID)

​
Request Headers

​
Authorization
string
required
Bearer token for authentication

​
Response

​
message
string
Success message: “container deleted”
​
id
string
Container Docker ID
​
db_id
string
Container database ID
​
name
string
Container name

​
Status Codes

  • 200 OK - Container deleted successfully
  • 401 Unauthorized - Missing or invalid API token
  • 404 Not Found - Container not found
  • 500 Internal Server Error - Failed to delete container

​
Examples

curl -X DELETE https://your-rexec-instance.com/api/containers/a3b5c7d9e1f2 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
Response Example

{
  "message": "container deleted",
  "id": "a3b5c7d9e1f2",
  "db_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "dev-environment"
}
Data Deletion: Deleting a container stops it and removes it from Docker. Volume data may be retained based on your instance configuration. Check with your administrator about data retention policies.

​
Update Container Settings

PATCH /api/containers/:id
Updates container settings including name and resource allocation. Resource changes require recreating the container (it will be automatically restarted).

​
Path Parameters

​
id
string
required
Container ID (Docker ID or database ID)

​
Request Headers

​
Authorization
string
required
Bearer token for authentication
​
Content-Type
string
required
Must be application/json

​
Request Body

​
name
string
required
New container name (1-64 characters, alphanumeric and hyphens)
​
memory_mb
integer
required
Memory allocation in MB (validated against tier limits)
​
cpu_shares
integer
required
CPU allocation in millicores (validated against tier limits)
​
disk_mb
integer
required
Disk quota in MB (validated against tier limits)

​
Response

​
message
string
Success message: “settings updated”
​
restarted
boolean
Whether the container was restarted due to resource changes
​
container
object

​
Status Codes

  • 200 OK - Settings updated successfully
  • 400 Bad Request - Invalid parameters
  • 401 Unauthorized - Missing or invalid API token
  • 404 Not Found - Container not found
  • 500 Internal Server Error - Failed to update settings

​
Examples

curl -X PATCH https://your-rexec-instance.com/api/containers/a3b5c7d9e1f2 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-api",
    "memory_mb": 4096,
    "cpu_shares": 4000,
    "disk_mb": 20480
  }'

​
Response Example

{
  "message": "settings updated",
  "restarted": true,
  "container": {
    "id": "f9e8d7c6b5a4",
    "db_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "production-api",
    "image": "ubuntu:24.04",
    "status": "running",
    "role": "node",
    "resources": {
      "memory_mb": 4096,
      "cpu_shares": 4000,
      "disk_mb": 20480
    }
  }
}
Resource Changes: Changing memory, CPU, or disk resources requires recreating the container with gVisor. The container is automatically stopped, removed, and recreated with the new limits. Your data is preserved on the volume.
Role Reinstallation: If disk size changes, development tools (role packages) are automatically reinstalled in the background. The container is usable immediately while installation completes.

​
Error Responses

All management endpoints return consistent error responses: 
{
  "error": "error description"
}
Common errors:
  • “unauthorized” - Invalid or missing API token
  • “container not found” - Container ID doesn’t exist or you don’t have access
  • “not authorized” - Container belongs to another user
  • “guest session expired” - Guest users cannot restart expired containers
  • “failed to start container” / “failed to stop container” - Docker operation failed

​
WebSocket Events

All container management operations trigger real-time WebSocket events: 
{
  "type": "container_started",
  "data": {
    "id": "a3b5c7d9e1f2",
    "name": "dev-environment",
    "status": "running"
  }
}
Event types:
  • container_started
  • container_stopped
  • container_deleted
  • container_updated

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us