Open a live connection to a task's machine
curl --request POST \
--url https://api.runaether.dev/tasks/{taskID}/connect \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"protocols": [
123
],
"start_sandbox": true
}
'import requests
url = "https://api.runaether.dev/tasks/{taskID}/connect"
payload = {
"protocols": [123],
"start_sandbox": True
}
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({protocols: [123], start_sandbox: true})
};
fetch('https://api.runaether.dev/tasks/{taskID}/connect', 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.runaether.dev/tasks/{taskID}/connect",
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([
'protocols' => [
123
],
'start_sandbox' => true
]),
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.runaether.dev/tasks/{taskID}/connect"
payload := strings.NewReader("{\n \"protocols\": [\n 123\n ],\n \"start_sandbox\": true\n}")
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.runaether.dev/tasks/{taskID}/connect")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"protocols\": [\n 123\n ],\n \"start_sandbox\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.runaether.dev/tasks/{taskID}/connect")
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 = "{\n \"protocols\": [\n 123\n ],\n \"start_sandbox\": true\n}"
response = http.request(request)
puts response.read_body{
"frame_key": "<string>",
"live_connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"preview_url_template": "<string>",
"protocol": 1,
"state": "ready",
"ticket": "<string>",
"ticket_expires_at": "2023-11-07T05:31:56Z",
"websocket_url": "<string>"
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "user_suspended",
"error": "<string>",
"org_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"tier": "free",
"vm_size": "small"
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}Tasks
Open a live connection to a task's machine
Opens a live connection to the machine a task runs on, and answers ready with the socket's address and a ticket, starting while its sandbox is on its way up, or stopped.
Use this tool when you need to:
- Open the live socket that carries a task's files, git, terminals, ports, live agent text and activity
- Start a task's stopped sandbox, once the person chose to, and follow it until it is up
Examples:
- POST /tasks/{taskID}/connect {"protocols": [1]}
- POST /tasks/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/connect {"start_sandbox": true, "protocols": [1, 2]}
Hints:
- taskID is the task's lowercase uuid; protocols is required, the live protocol versions the client speaks (422 from the schema when missing or empty); start_sandbox is optional, false by default, so opening a page never starts a sandbox.
- Answers 200 with a union on state: ready carries live_connection_id, websocket_url, a ticket, ticket_expires_at, protocol, frame_key (null for a sandbox) and preview_url_template; starting carries since, retry_after_ms and waiting (sandbox_starting, sandbox_preparing, sandbox_stopping or sandbox_suspending, with a sentence): call again after the delay; stopped means the sandbox is stopped and start_sandbox was false: offer to start it, then call again with start_sandbox true.
- Dial websocket_url within 30 seconds, offering the WebSocket subprotocols bearer and the ticket, never in an address; the ticket opens one socket once. Every attempt to open a socket starts with a fresh call. For a sandbox, protocol is the highest one both the client and the sandbox's run speak; every sandbox speaks protocol 1, so a client that does not list 1 is refused with 409 live_protocol_unsupported.
- A task on a computer answers ready or is refused, never starting or stopped: websocket_url is the relay's, which joins the client's socket to the computer's machine bridge; protocol is the highest one both the client and that bridge list (409 live_protocol_unsupported when none); frame_key is 64 lower-case hex characters, the key that seals every frame between the two ends, which the relay never sees; preview_url_template is null. A computer whose bridge is not connected is refused with 409 computer_unreachable, and one whose bridge serves no live connection with 409 computer_cli_outdated: update the aether CLI there. At most 8 live connections are open to one computer: beyond them the call is refused with 409 too_many_live_connections; a connection the relay does not hold stops counting once its ticket has run out and the relay, asked at the cap or by the lease every 30 seconds, answers; while the relay cannot be asked it keeps counting. Try again with backoff.
- The task's can.connect_live shows every refusal before the call: 409 task_start_pending, task_start_failed, sandbox_deleted, sandbox_failed, sandbox_needs_message or task_creator_deleted, and for a task on a computer 409 computer_cli_outdated or computer_unreachable. sandbox_needs_message is a sandbox that is not running and that only the task's next message starts: it has no machine, or the task errored (a start never revives an errored task). The call answers the same codes for a task that changed since it was read.
- A start that a stop or suspend of the sandbox still holds answers starting (sandbox_stopping or sandbox_suspending, since that stop or suspend began).
- A start the platform has no room for right now is 503 with Retry-After in seconds: call again after it.
- A start that runtime admission refuses is a 402 whose code is the refusal kind (billing_blocked, org_task_concurrency_exceeded, credits_exhausted or workspace_run_unavailable), with tier, vm_size and org_id.
- Use getTask instead to read can.connect_live without opening anything.
- Restricted to the task's creator or an owner or admin of its organization, with a web or phone sign-in or an API key: another member is refused with 403 control_forbidden, a viewer or billing member with 403 org_role_insufficient, a suspended account or organization with 403 user_suspended or org_suspended, an agent's or a client app's grant, or a sign-in that names no session, with 403 credential_kind_not_admitted, and a task the caller cannot see is 404; a sign-in whose session has ended (signed out) is 401 unauthenticated, as authentication refuses a revoked API key; 503 when the membership or sign-in check is unavailable. A task on a computer is its person's alone, from a web or phone sign-in: an admin is refused with 403 control_forbidden, and an API key with 403 credential_kind_not_admitted.
POST
/
tasks
/
{taskID}
/
connect
Open a live connection to a task's machine
curl --request POST \
--url https://api.runaether.dev/tasks/{taskID}/connect \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"protocols": [
123
],
"start_sandbox": true
}
'import requests
url = "https://api.runaether.dev/tasks/{taskID}/connect"
payload = {
"protocols": [123],
"start_sandbox": True
}
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({protocols: [123], start_sandbox: true})
};
fetch('https://api.runaether.dev/tasks/{taskID}/connect', 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.runaether.dev/tasks/{taskID}/connect",
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([
'protocols' => [
123
],
'start_sandbox' => true
]),
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.runaether.dev/tasks/{taskID}/connect"
payload := strings.NewReader("{\n \"protocols\": [\n 123\n ],\n \"start_sandbox\": true\n}")
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.runaether.dev/tasks/{taskID}/connect")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"protocols\": [\n 123\n ],\n \"start_sandbox\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.runaether.dev/tasks/{taskID}/connect")
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 = "{\n \"protocols\": [\n 123\n ],\n \"start_sandbox\": true\n}"
response = http.request(request)
puts response.read_body{
"frame_key": "<string>",
"live_connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"preview_url_template": "<string>",
"protocol": 1,
"state": "ready",
"ticket": "<string>",
"ticket_expires_at": "2023-11-07T05:31:56Z",
"websocket_url": "<string>"
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "user_suspended",
"error": "<string>",
"org_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"tier": "free",
"vm_size": "small"
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}Authorizations
Path Parameters
Body
application/json
Response
OK
- Option 1
- Option 2
- Option 3
A live connection to the task's machine: ready, starting or stopped.