Sign in
Tasks

Submit and run new task

Changed on
post/tasks

Request

  • Base URL: http://localhost:10998/api
  • URL: http://localhost:10998/api/tasks
  • Auth: none declared

Request body

idstring required

Unique task ID assigned by dstack server

namestring required

Task name. Used to construct unique container name

registry_usernamestring

Private container registry username

registry_passwordstring

Private container registry password

image_namestring required
container_userstring

If not set, the default image user is used. As of 0.18.24, dstack always uses root

privilegedboolean

Start container in privileged mode

gpuinteger

Number of GPUs allocated for the container. A special value -1 means "all available, even if none", 0 means "zero GPUs"

cpunumber

Amount of CPU resources available to the container. A special value 0 means "all". Fractional values are allowed, e.g., 1.5 — one and a half CPUs

memorynumber

Amount of memory available to the container, in bytes. A special value 0 means "all"

shm_sizeinteger

POSIX shared memory, bytes. A special value 0 means "use the default value (64MiB)". If > 0, tmpfs is mounted with the exec option, unlike the default mount options

network_mode'host' | 'bridge'
host_ssh_userstring

Instance (host) user for SSH access, either directly (ssh {run_name}-host) or for ProxyJumping inside the container. Ignored if host_ssh_keys is not set

host_ssh_keysstring[]

SSH public keys for access to the instance (host). If set, the keys will be added to the host_ssh_user's ~/.ssh/authorized_keys when the run starts and removed when the run exits.

container_ssh_keysstring[]

SSH public keys for container_user. As of 0.18.24, dstack submits two keys: project key (generated by the server) and user key (either generated by the CLI client or provided by the user)

Example request

{
  "id": "23a2c7a0-6c88-48ee-8028-b9ad9f6f5c24",
  "name": "horrible-mule-1-0-0",
  "registry_username": "registry-user",
  "registry_password": "registry-token",
  "image_name": "ubuntu:22.04",
  "container_user": "root",
  "shm_size": 1073741824,
  "host_ssh_user": "root",
  "container_ssh_keys": [
    "ssh-rsa <BASE64> project@dstack",
    "ssh-ed25519 <BASE64> me@laptop"
  ]
}

Response

Task info

idstring required

Unique task ID assigned by dstack server

status'pending' | 'preparing' | 'pulling' | 'creating' | 'running' | 'terminated' required
termination_reason'executor_error' | 'creating_container_error' | 'container_exited_with_error' | 'done_by_runner' | 'terminated_by_user' | 'terminated_by_server' | 'max_duration_exceeded' required
termination_messagestring required

A shim-generated message or N last lines from the container logs

container_namestring required
container_idstring required
gpu_idsGpuID[] nullable required

An array of GPU identifiers or null if this information is not yet available

Example response

{
  "id": "23a2c7a0-6c88-48ee-8028-b9ad9f6f5c24",
  "status": "terminated",
  "ports": [
    {
      "host": 32770,
      "container": 80
    }
  ],
  "container_name": "horrible-mule-1-0-0-44f7cb95",
  "container_id": "a6bb8d4bb8af8ec72482ecd194ff92fac9974521aa5ad8a46abfc4f0ba858775",
  "gpu_ids": [
    "GPU-2b79666e-d81f-f3f8-fd47-9903f118c3f5"
  ]
}

Changes

  • 690333cca1b0Revision changes
    • breaking

      added subschema #2 to the request property allOf list

    • breaking

      removed the enum value bridge of the request property

    • breaking

      removed the enum value host of the request property

    • breaking

      the request property type changed from string to no type

    • info

      the request property default value host was removed

  • 0539598ae503Revision changes
    • info

      api tag Tasks added