Make a code for setting up from another computer

POST

/setup/code

curl --request POST \
  --url http://127.0.0.1:7700/api/setup/code \
  --header 'Authorization: Bearer <token>'

• On the box itself (the default listen address)
• From another device, with a paired device token, when BOX_LISTEN allows it

Only on the box’s own screen (anyone else gets 403), and only while setup is open (else 409). Makes a one-time code valid for 30 minutes and opens a setup port, 7701 or BOX_SETUP_PORT, so another computer can reach the API. The port is plain HTTP, and the image’s firewall opens it to private networks only, as it does port 7700. Set a cloud computer up from its provider’s console, or over a private network such as Tailscale. That computer trades the code at POST /pair with kind: "setup" for a token that works until setup finishes, or for two hours at most. POST /setup/stop, or finishing setup, closes the port and ends those tokens. See AGENT-SETUP.md in the source tree.

Authorizations

• deviceToken
• accessToken

Responses

200

The code and where the setup port answers.

Media typeapplication/json

object

code

required

Eight hexadecimal characters. Works once.

string

expiresAt

required

string format: date-time

open

required

boolean

until

When the port closes by itself.

string format: date-time

port

integer

urls

The addresses another computer can use.

Array<string>

remote

The box’s remote access address

string

devices

Array<object>

object

name

string

since

string format: date-time

Example

{
  "code": "a1b2c3d4",
  "expiresAt": "2026-10-24T09:47:03.000Z",
  "open": true,
  "until": "2026-10-24T11:17:03.000Z",
  "port": 7701,
  "urls": [
    "http://192.0.2.10:7701"
  ],
  "devices": []
}

403

The owner’s route, called by someone who is not the box’s own screen or a device paired as the owner.

Media typeapplication/json

object

error

required

What went wrong

string

Example

{
  "error": "only this computer's own screen or the owner's paired device can do this"
}

409

Setup is finished. Open it again first.

Media typeapplication/json

object

error

required

What went wrong

string

Example ^generated

{
  "error": "example"
}