Skip to main content
POST
/
api
/
containers
Create Container
curl --request POST \
  --url https://api.example.com/api/containers \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "image": "<string>",
  "name": "<string>",
  "custom_image": "<string>",
  "role": "<string>",
  "shell": {
    "shell.enhanced": true,
    "shell.theme": "<string>",
    "shell.autosuggestions": true,
    "shell.syntax_highlight": true,
    "shell.history_search": true,
    "shell.git_aliases": true,
    "shell.system_stats": true,
    "shell.use_tmux": true
  },
  "memory_mb": 123,
  "cpu_shares": 123,
  "disk_mb": 123
}
'
{
  "id": "<string>",
  "db_id": "<string>",
  "user_id": "<string>",
  "name": "<string>",
  "image": "<string>",
  "role": "<string>",
  "status": "<string>",
  "created_at": "<string>",
  "async": true,
  "message": "<string>",
  "resources": {
    "resources.memory_mb": 123,
    "resources.cpu_shares": 123,
    "resources.disk_mb": 123
  },
  "expires_at": "<string>",
  "session_limit_seconds": 123,
  "error": "<string>",
  "current": 123,
  "limit": 123,
  "tier": "<string>",
  "supported_images": [
    {}
  ]
}

​
Endpoint

POST /api/containers
Creates a new container with the specified configuration. Container creation is asynchronous - the API returns immediately with a creating status, and the container becomes running once initialization completes.

​
Request Headers

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

​
Request Body

​
image
string
required
Base image to use for the container. Supported values:
  • ubuntu:24.04 - Ubuntu 24.04 LTS
  • debian:bookworm - Debian 12
  • alpine:latest - Alpine Linux
  • archlinux:latest - Arch Linux
  • custom - Use a custom Docker image (requires custom_image field)
​
name
string
Container name (1-64 characters, alphanumeric and hyphens only). Auto-generated if not provided (e.g., “swift-lion-742”).
​
custom_image
string
Required when image is “custom”. Specify a valid Docker image reference (e.g., “node:20-alpine”, “python:3.11”).
​
role
string
Pre-configured development environment. Options:
  • node - Node.js development (nvm, npm, yarn)
  • python - Python development (pyenv, pip, poetry)
  • go - Go development tools
  • rust - Rust toolchain
  • devops - Docker, kubectl, terraform, ansible
  • barebone - Minimal setup, fastest startup
Leave empty for a basic shell environment.
​
shell
object
Shell customization options
​
memory_mb
integer
Memory limit in MB (256-4096 for free tier, higher for paid tiers). Defaults to tier limit if not specified.
​
cpu_shares
integer
CPU allocation in millicores (250-4000, where 1000 = 1 CPU core). Defaults to tier limit if not specified.
​
disk_mb
integer
Disk quota in MB (1024-16384 for free tier). Defaults to tier limit if not specified.

​
Response

​
id
string
Unique container identifier (database ID during creation, Docker ID once running)
​
db_id
string
Database record identifier
​
user_id
string
Owner user ID
​
name
string
Container name
​
image
string
Base image used
​
role
string
Development role (if specified)
​
status
string
Current status: creating, running, stopped, or error
​
created_at
string
ISO 8601 timestamp of creation
​
async
boolean
Always true - indicates asynchronous creation
​
message
string
Human-readable status message
​
resources
object
​
expires_at
string
(Free/Guest users only) ISO 8601 timestamp when session expires
​
session_limit_seconds
integer
(Free/Guest users only) Remaining session time in seconds

​
Status Codes

  • 202 Accepted - Container creation started successfully
  • 400 Bad Request - Invalid parameters (e.g., invalid image, name format)
  • 401 Unauthorized - Missing or invalid API token
  • 403 Forbidden - Container limit reached or insufficient permissions
  • 409 Conflict - Container name already exists
  • 500 Internal Server Error - Server-side error

​
Error Responses

​
error
string
Error message describing what went wrong
​
current
integer
(For limit errors) Current number of containers
​
limit
integer
(For limit errors) Maximum containers allowed
​
tier
string
(For limit errors) Your current subscription tier
​
supported_images
array
(For image errors) List of supported image names

​
Examples

curl -X POST https://your-rexec-instance.com/api/containers \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "ubuntu:24.04",
    "name": "dev-environment",
    "role": "node",
    "memory_mb": 2048,
    "cpu_shares": 2000,
    "shell": {
      "enhanced": true,
      "theme": "rexec",
      "use_tmux": true
    }
  }'

​
Response Examples

​
Success Response (202 Accepted)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "db_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "usr_123abc",
  "name": "dev-environment",
  "image": "ubuntu:24.04",
  "role": "node",
  "status": "creating",
  "created_at": "2024-01-15T10:30:00Z",
  "async": true,
  "message": "Container is being created. This may take a moment if the image needs to be pulled.",
  "resources": {
    "memory_mb": 2048,
    "cpu_shares": 2000,
    "disk_mb": 10240
  }
}

​
Container Limit Error (403)

{
  "error": "container limit reached",
  "current": 5,
  "limit": 5,
  "tier": "free",
  "message": "Upgrade your plan to create more containers"
}

​
Invalid Image Error (400)

{
  "error": "unsupported image type",
  "supported_images": [
    "ubuntu:24.04",
    "debian:bookworm",
    "alpine:latest",
    "archlinux:latest",
    "custom"
  ]
}

​
WebSocket Progress Updates

For real-time creation progress, connect to the WebSocket events endpoint: 
wss://your-rexec-instance.com/ws/events?token=YOUR_API_TOKEN
You’ll receive progress events: 
{
  "type": "container_progress",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "stage": "pulling",
    "message": "Pulling image...",
    "progress": 15
  }
}
Progress stages: validating → pulling → creating → starting → configuring → ready

​
Notes

Async Creation: Container creation is asynchronous to prevent timeout issues. The API returns immediately with status: "creating". Use WebSocket events or poll the Get Container endpoint to monitor progress.
macOS Containers: macos and macos-legacy images require Enterprise tier or admin permissions.
Resource Limits: Requested resources are validated against your tier limits. Values exceeding limits are automatically clamped to the maximum allowed.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us