Compute API

Base URL: https://compute.cloud.eddisonso.com

Reference

Instance Types

Type	Arch	CPU Cores
`nano`	arm64	0.5
`micro`	arm64	1
`mini`	arm64	2
`tiny`	amd64	1
`small`	amd64	2
`medium`	amd64	4

Default Limits

Setting	Value
Max containers per user	3
Max SSH keys per user	10
Default memory	512 MB
Default storage	5 GB

Ingress Ports

Allowed external ports: 80, 443, 8000–8999. Setting port 443 automatically enables HTTPS routing via the gateway.

Containers

GET /compute/containers

List all containers for the authenticated user.

Auth: Session / API token Token Scope: compute.<uid>.containers with read

Example request:

curl https://compute.cloud.eddisonso.com/compute/containers \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "containers": [
    {
      "id": "abc12345",
      "name": "my-app",
      "status": "running",
      "hostname": "abc12345.compute.cloud.eddisonso.com",
      "memory_mb": 512,
      "memory_used_mb": 256,
      "storage_gb": 5,
      "storage_used_gb": 2.3,
      "instance_type": "nano",
      "created_at": "2024-01-15T10:30:00Z",
      "ssh_enabled": true,
      "https_enabled": false,
      "pull_policy": "IfNotPresent",
      "ssh_command": "ssh root@abc12345.compute.cloud.eddisonso.com"
    }
  ]
}

POST /compute/containers

Create a new container.

Auth: Session / API token Token Scope: compute.<uid>.containers with create

Param	Type	In	Required	Description
name	string	body	Yes	Container name
instance_type	string	body	No	Instance type (default `nano`)
memory_mb	int	body	No	Memory in MB (default 512)
storage_gb	int	body	No	Storage in GB (default 5)
ssh_key_ids	int[]	body	Yes	SSH key IDs to inject (at least one)
ssh_enabled	bool	body	No	Enable SSH access (default false)
mount_paths	string[]	body	No	Absolute paths to persist (default `["/root"]`)
image	string	body	No	Container image (default: Debian base). Must be `registry.cloud.eddisonso.com/<repo>:<tag>` or omitted. Use `GET /compute/images` to list available images.
pull_policy	string	body	No	`"Always"` or `"IfNotPresent"` (default `"IfNotPresent"`). When `"Always"`, the image is re-pulled on each (re)start.

Example request:

curl -X POST https://compute.cloud.eddisonso.com/compute/containers \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "instance_type": "nano",
    "ssh_key_ids": [1],
    "ssh_enabled": true
  }'

Response:

{
  "id": "abc12345",
  "name": "my-app",
  "status": "pending",
  "hostname": "abc12345.compute.cloud.eddisonso.com",
  "memory_mb": 512,
  "storage_gb": 5,
  "instance_type": "nano",
  "created_at": "2024-01-15T10:30:00Z",
  "ssh_enabled": true,
  "https_enabled": false,
  "pull_policy": "IfNotPresent"
}

GET /compute/containers/:id

Get a single container by ID.

Auth: Session / API token Token Scope: compute.<uid>.containers.<id> with read

Param	Type	In	Required	Description
id	string	path	Yes	Container ID

Example request:

curl https://compute.cloud.eddisonso.com/compute/containers/abc12345 \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "id": "abc12345",
  "name": "my-app",
  "status": "running",
  "hostname": "abc12345.compute.cloud.eddisonso.com",
  "memory_mb": 512,
  "memory_used_mb": 256,
  "storage_gb": 5,
  "storage_used_gb": 2.3,
  "instance_type": "nano",
  "created_at": "2024-01-15T10:30:00Z",
  "ssh_enabled": true,
  "https_enabled": false,
  "pull_policy": "IfNotPresent",
  "ssh_command": "ssh root@abc12345.compute.cloud.eddisonso.com"
}

DELETE /compute/containers/:id

Delete a container and its resources.

Auth: Session / API token Token Scope: compute.<uid>.containers.<id> with delete

Param	Type	In	Required	Description
id	string	path	Yes	Container ID

Example request:

curl -X DELETE https://compute.cloud.eddisonso.com/compute/containers/abc12345 \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "status": "ok"
}

POST /compute/containers/:id/start

Start a stopped container.

Auth: Session / API token Token Scope: compute.<uid>.containers.<id> with start

Param	Type	In	Required	Description
id	string	path	Yes	Container ID

Example request:

curl -X POST https://compute.cloud.eddisonso.com/compute/containers/abc12345/start \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "id": "abc12345",
  "name": "my-app",
  "status": "pending",
  "hostname": "abc12345.compute.cloud.eddisonso.com",
  "memory_mb": 512,
  "storage_gb": 5,
  "instance_type": "nano",
  "created_at": "2024-01-15T10:30:00Z",
  "ssh_enabled": true,
  "https_enabled": false,
  "pull_policy": "IfNotPresent"
}

POST /compute/containers/:id/stop

Stop a running container.

Auth: Session / API token Token Scope: compute.<uid>.containers.<id> with stop

Param	Type	In	Required	Description
id	string	path	Yes	Container ID

Example request:

curl -X POST https://compute.cloud.eddisonso.com/compute/containers/abc12345/stop \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "id": "abc12345",
  "name": "my-app",
  "status": "stopped",
  "hostname": "abc12345.compute.cloud.eddisonso.com",
  "memory_mb": 512,
  "storage_gb": 5,
  "instance_type": "nano",
  "created_at": "2024-01-15T10:30:00Z",
  "ssh_enabled": true,
  "https_enabled": false,
  "pull_policy": "IfNotPresent"
}

GET /compute/images

List available container images (builtin defaults and images from the internal registry).

Auth: Session / API token Token Scope: compute.<uid>.containers with read

Example request:

curl https://compute.cloud.eddisonso.com/compute/images \
  -H "Authorization: Bearer eyJhbGci..."

Response:

[
  {
    "name": "Debian (Base)",
    "image": "eddisonso/ecloud-compute-base:latest",
    "source": "builtin"
  },
  {
    "name": "my-app:v1.0",
    "image": "registry.cloud.eddisonso.com/my-app:v1.0",
    "source": "registry"
  }
]

Each entry has:

name — human-readable label
image — full image reference to pass as the image field when creating a container
source — "builtin" for default images, "registry" for images from the internal registry

Admin

GET /compute/admin/containers

List all containers across every user. Admin-only: the caller's session must belong to the configured admin user (ADMIN_USERNAME); all other callers receive 403 Forbidden.

Auth: Session (admin user only)

Example request:

curl https://compute.cloud.eddisonso.com/compute/admin/containers \
  -H "Authorization: Bearer eyJhbGci..."

Response:

[
  {
    "id": "abc12345",
    "user_id": "u_9f3a2b",
    "owner": "alice",
    "name": "my-app",
    "hostname": "abc12345.cloud.eddisonso.com",
    "status": "running",
    "external_ip": "10.0.0.5",
    "memory_mb": 512,
    "storage_gb": 5,
    "created_at": 1705326600,
    "ssh_enabled": true,
    "https_enabled": false
  }
]

Each entry includes the owning user_id and owner (username) in addition to the standard container fields.

SSH Keys

GET /compute/ssh-keys

List all SSH keys for the authenticated user.

Auth: Session / API token Token Scope: compute.<uid>.keys with read

Example request:

curl https://compute.cloud.eddisonso.com/compute/ssh-keys \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "ssh_keys": [
    {
      "id": 1,
      "name": "laptop",
      "public_key": "ssh-ed25519 AAAA...",
      "created_at": "2024-01-10T15:20:00Z"
    }
  ]
}

POST /compute/ssh-keys

Add a new SSH key.

Auth: Session / API token Token Scope: compute.<uid>.keys with create

Param	Type	In	Required	Description
name	string	body	Yes	Key name
public_key	string	body	Yes	SSH public key (OpenSSH format)

Accepted key types: ssh-rsa, ssh-ed25519, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521.

Example request:

curl -X POST https://compute.cloud.eddisonso.com/compute/ssh-keys \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "laptop",
    "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@laptop"
  }'

Response:

{
  "id": 1,
  "name": "laptop",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@laptop",
  "created_at": "2024-01-10T15:20:00Z"
}

DELETE /compute/ssh-keys/:id

Delete an SSH key.

Auth: Session / API token Token Scope: compute.<uid>.keys with delete

Param	Type	In	Required	Description
id	int	path	Yes	SSH key ID

Example request:

curl -X DELETE https://compute.cloud.eddisonso.com/compute/ssh-keys/1 \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "status": "ok"
}

SSH Access

GET /compute/containers/:id/ssh

Get SSH access status for a container.

Auth: Session / API token Token Scope: compute.<uid>.containers.<id> with read

Param	Type	In	Required	Description
id	string	path	Yes	Container ID

Example request:

curl https://compute.cloud.eddisonso.com/compute/containers/abc12345/ssh \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "ssh_enabled": true
}

PUT /compute/containers/:id/ssh

Enable or disable SSH access for a container.

Auth: Session / API token Token Scope: compute.<uid>.containers.<id> with update

Param	Type	In	Required	Description
id	string	path	Yes	Container ID
ssh_enabled	bool	body	Yes	Enable or disable SSH

Example request:

curl -X PUT https://compute.cloud.eddisonso.com/compute/containers/abc12345/ssh \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"ssh_enabled": true}'

Response:

{
  "ssh_enabled": true
}

Ingress Rules

GET /compute/containers/:id/ingress

List ingress rules for a container.

Auth: Session / API token Token Scope: compute.<uid>.containers.<id> with read

Param	Type	In	Required	Description
id	string	path	Yes	Container ID

Example request:

curl https://compute.cloud.eddisonso.com/compute/containers/abc12345/ingress \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "rules": [
    {
      "id": 1,
      "port": 8080,
      "target_port": 8080,
      "created_at": 1705326600
    }
  ]
}

POST /compute/containers/:id/ingress

Add an ingress rule. Allowed external ports: 80, 443, 8000–8999.

Auth: Session / API token Token Scope: compute.<uid>.containers.<id> with update

Param	Type	In	Required	Description
id	string	path	Yes	Container ID
port	int	body	Yes	External port
target_port	int	body	No	Internal container port (default: same as `port`)

Example request:

curl -X POST https://compute.cloud.eddisonso.com/compute/containers/abc12345/ingress \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"port": 8080, "target_port": 3000}'

Response:

{
  "id": 1,
  "port": 8080,
  "target_port": 3000,
  "created_at": 1705326600
}

DELETE /compute/containers/:id/ingress/:port

Remove an ingress rule.

Auth: Session / API token Token Scope: compute.<uid>.containers.<id> with update

Param	Type	In	Required	Description
id	string	path	Yes	Container ID
port	int	path	Yes	External port to remove

Example request:

curl -X DELETE https://compute.cloud.eddisonso.com/compute/containers/abc12345/ingress/8080 \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "status": "ok"
}

Mount Paths

GET /compute/containers/:id/mounts

Get persistent mount paths for a container.

Auth: Session / API token Token Scope: compute.<uid>.containers.<id> with read

Param	Type	In	Required	Description
id	string	path	Yes	Container ID

Example request:

curl https://compute.cloud.eddisonso.com/compute/containers/abc12345/mounts \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "mount_paths": ["/root", "/var/data"]
}

PUT /compute/containers/:id/mounts

Update mount paths. Restarts the container if it is running.

Auth: Session / API token Token Scope: compute.<uid>.containers.<id> with update

Param	Type	In	Required	Description
id	string	path	Yes	Container ID
mount_paths	string[]	body	Yes	Absolute paths to persist (at least one)

Example request:

curl -X PUT https://compute.cloud.eddisonso.com/compute/containers/abc12345/mounts \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"mount_paths": ["/root", "/var/data", "/data"]}'

Response:

{
  "mount_paths": ["/root", "/var/data", "/data"],
  "restarted": true
}

Image Pull Policy

PUT /compute/containers/:id/pull-policy

Update the image pull policy for a container. Takes effect on the next (re)start.

Auth: Session / API token Token Scope: compute.<uid>.containers.<id> with update

Param	Type	In	Required	Description
id	string	path	Yes	Container ID
pull_policy	string	body	Yes	`"Always"` or `"IfNotPresent"`

Example request:

curl -X PUT https://compute.cloud.eddisonso.com/compute/containers/abc12345/pull-policy \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"pull_policy": "Always"}'

Response:

{
  "pull_policy": "Always"
}

WebSocket

GET /compute/ws

WebSocket connection for real-time container status updates.

Auth: Session / API token Token Scope: compute.<uid> with read

Connection:

wss://compute.cloud.eddisonso.com/compute/ws

On connect the server sends the full container list, then pushes status changes as they happen.

Initial message:

{
  "type": "containers",
  "data": [
    {
      "id": "abc12345",
      "name": "my-app",
      "status": "running"
    }
  ]
}

Status update:

{
  "type": "container_status",
  "data": {
    "container_id": "abc12345",
    "status": "running",
    "external_ip": "10.0.0.5"
  }
}

Status values: pending, initializing, running, stopped, failed.

GET /compute/containers/:id/terminal

WebSocket terminal session into a running container.

Auth: Session / API token Token Scope: compute.<uid>.containers.<id> with update

Connection:

wss://compute.cloud.eddisonso.com/compute/containers/:id/terminal

The container must be running. The server allocates a PTY (xterm-256color, 24x80) and proxies binary data between the WebSocket and the container's SSH session.

GET /compute/containers/:id/logs

WebSocket log stream for a running container. Streams stdout/stderr lines with RFC3339Nano timestamps.

Auth: Session / API token Token Scope: compute.<uid>.containers.<id> with read

Param	Type	In	Required	Description
id	string	path	Yes	Container ID
tail	int	query	No	Number of historical lines to send before following (default `100`)

Connection:

wss://compute.cloud.eddisonso.com/compute/containers/:id/logs?tail=100

The auth token may be passed as a token query parameter when a Authorization header is not possible (e.g., browser WebSocket connections):

wss://compute.cloud.eddisonso.com/compute/containers/:id/logs?token=<session_token>&tail=100

The container must be running. Each WebSocket message is one log line in the format:

2026-03-15T17:00:01.123456789Z Server started on :8080

The stream follows the container until the client disconnects or the container stops.

Reference​

Instance Types​

Default Limits​

Ingress Ports​

Containers​

GET /compute/containers​

POST /compute/containers​

GET /compute/containers/:id​

DELETE /compute/containers/:id​

POST /compute/containers/:id/start​

POST /compute/containers/:id/stop​

GET /compute/images​

Admin​

GET /compute/admin/containers​

SSH Keys​

GET /compute/ssh-keys​

POST /compute/ssh-keys​

DELETE /compute/ssh-keys/:id​

SSH Access​

GET /compute/containers/:id/ssh​

PUT /compute/containers/:id/ssh​

Ingress Rules​

GET /compute/containers/:id/ingress​

POST /compute/containers/:id/ingress​

DELETE /compute/containers/:id/ingress/:port​

Mount Paths​

GET /compute/containers/:id/mounts​

PUT /compute/containers/:id/mounts​

Image Pull Policy​

PUT /compute/containers/:id/pull-policy​

WebSocket​

GET /compute/ws​

GET /compute/containers/:id/terminal​

GET /compute/containers/:id/logs​

Reference

Instance Types

Default Limits

Ingress Ports

Containers

GET /compute/containers

POST /compute/containers

GET /compute/containers/:id

DELETE /compute/containers/:id

POST /compute/containers/:id/start

POST /compute/containers/:id/stop

GET /compute/images

Admin

GET /compute/admin/containers

SSH Keys

GET /compute/ssh-keys

POST /compute/ssh-keys

DELETE /compute/ssh-keys/:id

SSH Access

GET /compute/containers/:id/ssh

PUT /compute/containers/:id/ssh

Ingress Rules

GET /compute/containers/:id/ingress

POST /compute/containers/:id/ingress

DELETE /compute/containers/:id/ingress/:port

Mount Paths

GET /compute/containers/:id/mounts

PUT /compute/containers/:id/mounts

Image Pull Policy

PUT /compute/containers/:id/pull-policy

WebSocket

GET /compute/ws

GET /compute/containers/:id/terminal

GET /compute/containers/:id/logs