Resume an idle-suspended machine before using it.

curl --request POST \
  --url https://api.instabox.sh/v1/machines/{id}/wake \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

url = "https://api.instabox.sh/v1/machines/{id}/wake"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.instabox.sh/v1/machines/{id}/wake', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.instabox.sh/v1/machines/{id}/wake",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.instabox.sh/v1/machines/{id}/wake"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.instabox.sh/v1/machines/{id}/wake")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.instabox.sh/v1/machines/{id}/wake")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "name": "<string>",
  "desiredState": "creating",
  "state": "creating",
  "revision": 123,
  "operationId": "<string>",
  "template": {
    "id": "<string>",
    "version": "<string>",
    "digest": "<string>",
    "kernel": "<string>"
  },
  "spec": {
    "vcpus": 123,
    "memMiB": 123,
    "persistentDiskGiB": 123,
    "rootDiskGiB": 123
  },
  "storage": {
    "sizeGiB": 123,
    "mountPath": "/data",
    "persistent": true,
    "synced": true,
    "snapshotSeq": 123
  },
  "runtime": {
    "ready": true,
    "processesPreserved": true
  },
  "autoSuspendAfterSeconds": 123,
  "maxRunMinutes": 1073741823,
  "runStartedAt": "2023-11-07T05:31:56Z",
  "cooldownUntil": "2023-11-07T05:31:56Z",
  "metadata": {},
  "vault": true,
  "guestUser": "alice",
  "orgId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "snapshot": {
    "id": "<string>"
  },
  "image": {
    "id": "<string>"
  },
  "lastError": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  },
  "archiveAt": "2023-11-07T05:31:56Z",
  "deleteAt": "2023-11-07T05:31:56Z",
  "readyAt": "2023-11-07T05:31:56Z",
  "cooldownReason": "abuse_egress_blocklist",
  "abuseLock": {
    "at": "2023-11-07T05:31:56Z",
    "explanation": "<string>",
    "what": "<string>",
    "appeal": "<string>",
    "dst": "<string>",
    "port": 123,
    "kind": "<string>",
    "count": 123,
    "coreShare": 123,
    "process": "<string>",
    "pool": "<string>"
  },
  "autoSuspendedAt": "2023-11-07T05:31:56Z",
  "envNames": [
    "<string>"
  ],
  "free": true,
  "earlyAllowanceEnded": true,
  "oomKills": 123,
  "lastOom": {
    "at": "2023-11-07T05:31:56Z",
    "pid": 123,
    "process": "<string>",
    "rssBytes": 123,
    "anonRssBytes": 123,
    "cgroup": true,
    "uid": 123
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

Lifecycle

Resume an idle-suspended machine before using it.

Records activity on a running machine, or waits up to 45 seconds for an idle suspend and its resume to finish. Concurrent callers share the operation. A manual stop/suspend or archive is not undone. No Idempotency-Key is needed. A 409 operation_conflict includes the operation ID if it is still in progress; no workload was executed. The body is optional and takes no fields: {} or none; any key is 400 unknown_field. API keys: needs one of the scopes machines:write, machines:exec, machines:ssh.

POST

machines

{id}

wake

Resume an idle-suspended machine before using it.

curl --request POST \
  --url https://api.instabox.sh/v1/machines/{id}/wake \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

url = "https://api.instabox.sh/v1/machines/{id}/wake"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.instabox.sh/v1/machines/{id}/wake', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.instabox.sh/v1/machines/{id}/wake",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.instabox.sh/v1/machines/{id}/wake"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.instabox.sh/v1/machines/{id}/wake")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.instabox.sh/v1/machines/{id}/wake")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "name": "<string>",
  "desiredState": "creating",
  "state": "creating",
  "revision": 123,
  "operationId": "<string>",
  "template": {
    "id": "<string>",
    "version": "<string>",
    "digest": "<string>",
    "kernel": "<string>"
  },
  "spec": {
    "vcpus": 123,
    "memMiB": 123,
    "persistentDiskGiB": 123,
    "rootDiskGiB": 123
  },
  "storage": {
    "sizeGiB": 123,
    "mountPath": "/data",
    "persistent": true,
    "synced": true,
    "snapshotSeq": 123
  },
  "runtime": {
    "ready": true,
    "processesPreserved": true
  },
  "autoSuspendAfterSeconds": 123,
  "maxRunMinutes": 1073741823,
  "runStartedAt": "2023-11-07T05:31:56Z",
  "cooldownUntil": "2023-11-07T05:31:56Z",
  "metadata": {},
  "vault": true,
  "guestUser": "alice",
  "orgId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "snapshot": {
    "id": "<string>"
  },
  "image": {
    "id": "<string>"
  },
  "lastError": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  },
  "archiveAt": "2023-11-07T05:31:56Z",
  "deleteAt": "2023-11-07T05:31:56Z",
  "readyAt": "2023-11-07T05:31:56Z",
  "cooldownReason": "abuse_egress_blocklist",
  "abuseLock": {
    "at": "2023-11-07T05:31:56Z",
    "explanation": "<string>",
    "what": "<string>",
    "appeal": "<string>",
    "dst": "<string>",
    "port": 123,
    "kind": "<string>",
    "count": 123,
    "coreShare": 123,
    "process": "<string>",
    "pool": "<string>"
  },
  "autoSuspendedAt": "2023-11-07T05:31:56Z",
  "envNames": [
    "<string>"
  ],
  "free": true,
  "earlyAllowanceEnded": true,
  "oomKills": 123,
  "lastOom": {
    "at": "2023-11-07T05:31:56Z",
    "pid": 123,
    "process": "<string>",
    "rssBytes": 123,
    "anonRssBytes": 123,
    "cgroup": true,
    "uid": 123
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "<string>",
    "requestId": "<string>",
    "retryable": true,
    "operationId": "<string>",
    "reason": "missing_key",
    "hint": "<string>",
    "docs": "<string>",
    "docs_url": "<string>",
    "requiredScopes": [
      "<string>"
    ],
    "retryAfterSeconds": 2,
    "at": "2023-11-07T05:31:56Z"
  }
}

Authorizations

Authorization

string

header

required

Opaque instabox access token (1 hour). Refresh with /v1/auth/refresh (refresh token valid 30 days, rotates on use).

Path Parameters

string

required

Sandbox ID (m_ + 26 lowercase base32 characters).

Pattern: ^m_[a-z2-7]{26}$

Body

application/json

The optional body of POST /v1/machines/{id}/wake, which takes no fields; any key is refused with 400 unknown_field.

Response

Running machine; activity recorded.

A sandbox.

string

required

name

string

required

desiredState

enum<string>

required

Available options:

creating,

starting,

running,

stopping,

stopped,

suspending,

suspended,

resuming,

deleting,

deleted,

error

state

enum<string>

required

Available options:

creating,

starting,

running,

stopping,

stopped,

suspending,

suspended,

resuming,

deleting,

deleted,

error

revision

integer<int64>

required

Increases with each accepted change.

operationId

string | null

required

The active operation, if any.

template

object

required

Show child attributes

spec

object

required

A sandbox's size.

Show child attributes

storage

object

required

The sandbox's storage (/data, where HOME lives).

Show child attributes

runtime

object

required

Show child attributes

autoSuspendAfterSeconds

integer | null

required

The running sandbox is paused once it has been idle this many seconds (no agent working, no terminal input or output, little CPU); null: off. Pause, resume, stop and start keep it.

maxRunMinutes

integer

required

Maximum continuous runtime in minutes. -1 is unlimited; 0 sleeps immediately. Independent of idle auto-pause; whichever condition is reached first pauses the sandbox. Free machines default to 480 and only an admin session can change them. The service manages free runtime and may pause a run earlier. The response reports the current limit from runStartedAt; it can change during the run. Paid machines default to -1 and their users can change this setting. Max-run suspension starts a cooldown, returning 409 machine_cooldown with Retry-After on every wake path. By default it is 5 to 20 minutes (5 plus a random 0 to 15) on a paid plan and for the first such pause in a row on the free plan. Back-to-back pauses on the free plan rest longer (60 to 75, then 120 to 135 minutes): "Longer cooldowns on the free plan" at https://instabox.sh/docs/machines/auto-pause#longer-cooldowns-on-the-free-plan. Once cooldown ends, 0 still refuses wake with 409 max_run_disabled until changed.

Required range: -1 <= x <= 2147483647

runStartedAt

string<date-time> | null

required

Start of the current continuous run, conservatively initialized on a first error observation too; resets only after confirmed sleep.

cooldownUntil

string<date-time> | null

required

All wake paths are refused until this deadline, including admin actions: after a max-run suspension, or the 24-hour lock of an automatic abuse check's pause (cooldownReason).

metadata

object

required

String labels. At most 32 keys of 1-64 characters [A-Za-z0-9_.-], values of at most 512 characters, 8 KiB as JSON.

Show child attributes

vault

boolean

required

Whether legacy Vault delivery is enabled. Independent of org Secret selections and delivery status at the sandbox's /secrets endpoint.

guestUser

string

required

read-only

The Linux user in the sandbox that SSH sessions, exec and the terminal log in as, fixed at create: the guestUser the create named, else user (a create from a snapshot: the snapshot's user). dev on sandboxes from templates without the guest-user capability, and on every sandbox created before the field.

Example:

"alice"

orgId

string

required

read-only

The org the sandbox counts against (docs/orgs.md).

createdAt

string<date-time>

required

updatedAt

string<date-time>

required

snapshot

object

Show child attributes

image

object

deprecated

Deprecated: snapshot, under its old name (same value).

Show child attributes

lastError

object

Show child attributes

archiveAt

string<date-time> | null

When the sandbox is stopped if it is running (set at creation with archiveSeconds): its files are kept and a start brings it back. Resuming does not clear it; a sandbox that is not running when it passes only has it cleared. Absent: none.

deleteAt

string<date-time> | null

When the sandbox is deleted, whatever its state (set at creation with deleteAfterSeconds). The delete is an ordinary delete operation (trigger: delete_at), queued at deleteAt (within about a second) once no other operation is in progress. Absent: never.

readyAt

string<date-time>

read-only

When the running sandbox last became ready (runtime.ready turned true: SSH, exec and files work). For a new sandbox, readyAt minus createdAt is its create time; after a start or resume it is that start's. Absent while the sandbox is not ready, and on a sandbox that was already ready before the field existed (until its next start or resume).

cooldownReason

enum<string>

While cooldownUntil has not passed, the automatic abuse check whose pause locks the sandbox, the same as a wake's 409 machine_cooldown Error.reason: abuse_egress_blocklist (it tried to connect to a blocked destination on the egress blocklist, not a DNS lookup), abuse_network_flows (scanning or attack traffic), abuse_cpu (mining). Absent for a max-run cooldown, and once the lock ends.

Available options:

abuse_egress_blocklist,

abuse_network_flows,

abuse_cpu

abuseLock

object

With cooldownReason: what the owner is told about the pause behind the lock. Absent when cooldownReason is.

Show child attributes

autoSuspendedAt

string<date-time>

When the sandbox was queued to pause automatically; a successful automatic resume or its next explicit operation clears it. Absent: none.

envNames

string[]

The names of the sandbox's create-time env, sorted. Absent when it has none. The values are never shown: read them in the sandbox.

free

boolean

read-only

A free-tier org's sandbox (docs/pricing.md): never billed, pauses after 30 idle minutes (another autoSuspendAfterSeconds is refused with 403). On a paid plan every sandbox is billed.

earlyAllowanceEnded

boolean

read-only

Set on a stopped or paused free sandbox that cannot be started because its org's early free-sandbox allowance ended and as many free sandboxes as the standard limit allows are running: a start is refused (402 early_allowance_ended) until one is paused or deleted. Absent otherwise.

oomKills

integer<int64>

read-only

Processes the sandbox's kernel OOM killer killed since the sandbox was created (out of memory, or a memory cgroup's limit). Read from the sandbox about once a minute while it runs, and after an exec that exits non-zero; 0 on sandboxes whose host or guest agent predates the reading (absent from older servers).

lastOom

object

The newest OOM kill (absent until one is seen, or when the kernel log no longer held it).

Show child attributes