Ports and terminal

GET/v1/sandboxes/{id}/ports

Auth: API key

List this sandbox's preview URLs.

Parameters

idrequiredpath · string

Answer 200 · PortList · application/json

portsrequiredPort[]

sandbox_idrequiredstring

POST/v1/sandboxes/{id}/ports

Auth: API key

Mint a preview URL for a port in the sandbox. Anyone holding the URL can reach the port — it is a bearer token in a link, so pass ttl_s to make it stop working on its own rather than relying on someone remembering to revoke it. url is the form to use; path_url and host_url are always returned by name, so a client that needs one specifically never has to parse url.

Parameters

idrequiredpath · string

Request body PortOpen · application/json

portrequiredinteger

1–65535.

Answer 200 · Port · application/json

created_unix_nsinteger | null

Unix nanoseconds.

host_url_labelstring | null

The same publication addressed by name rather than by path. Apps that emit absolute paths need this form.

portinteger | null

The port inside the sandbox.

sandbox_idrequiredstring

tokenstring | null

The token the URL carries. Pass it to DELETE /v1/sandboxes/{id}/ports/{token_or_port} to revoke this one URL.

urlstring | null

The URL to open.

DELETE/v1/sandboxes/{id}/ports/{token_or_port}

Auth: API key

Revoke one URL by its token, or every URL for a port by the port number.

Parameters

idrequiredpath · string

token_or_portrequiredpath · string

Answer 200 · PortsRevoked · application/json

okrequiredboolean

revokedrequiredstring[]

The tokens that were revoked. Revoking by port number revokes every URL minted for that port, so this can hold more than one.

sandbox_idrequiredstring

GET/v1/sandboxes/{id}/pty

Auth: API key · upgrades to a WebSocket

A WebSocket terminal, relayed byte for byte. ?cols=&rows=&cmd=. Authenticated by the Authorization header, never a query string. Its open event carries resume: send it back in the promigence-resume header (from a browser, as the subprotocol promigence.resume.<resume>), with ?received= the output bytes you have, to pick the same terminal up where it left off after a dropped connection or a service update. If some of its output was not kept meanwhile, the open event's dropped says how many bytes. One that can no longer be picked up again answers 404.

Parameters

idrequiredpath · string

cmdquery · string

colsquery · integer

receivedquery · integer

rowsquery · integer

GET/v1/sandboxes/{id}/ssh

Auth: API key

The keys this sandbox will accept over SSH, and for how long.

Parameters

idrequiredpath · string

Answer 200 · SshAccessList · application/json

host_keystring | null

Absent when the sandbox has never been asked for SSH access.

host_key_fingerprintstring | null

idle_timeout_srequiredinteger

keysrequiredSshKey[]

sandbox_idrequiredstring

POST/v1/sandboxes/{id}/ssh

Auth: API key

Authorise an ssh-ed25519 public key for this sandbox and mint the short-lived credential an SSH connection to it uses. The login name is the sandbox id; the answer carries the sandbox's own host key, so a client can pin it instead of turning host verification off.

Parameters

idrequiredpath · string

Request body SshAccessRequest · application/json

idle_timeout_sinteger | null

Seconds an idle connection is kept.

public_keyrequiredstring

An OpenSSH public key line.

ttl_sinteger | null

Seconds the key is accepted.

Answer 200 · SshAccess · application/json

expires_atrequiredstring

When the key and the token both stop working (RFC 3339).

fingerprintrequiredstring

SHA256:… of the public key that was authorised, as ssh-keygen -lf prints it.

hostrequiredstring

The host to give ssh. It is an alias resolved by the tunnel, not a routable name.

host_keyrequiredstring

The sandbox's own host key, as a known_hosts line body (ssh-ed25519 AAAA…). Pin it instead of turning host verification off; it is minted for this sandbox and dies with it.

host_key_fingerprintrequiredstring

SHA256:… of host_key, which is what ssh prints on a first connection.

idle_timeout_srequiredinteger

Seconds of inactivity after which an open session is closed.

key_idrequiredstring

Identifier for the authorised key, for revoking it later.

proxy_commandrequiredstring

The ProxyCommand that carries the connection: promigence sandbox ssh <id> --proxy.

sandbox_idrequiredstring

The sandbox this access is for.

ssh_commandrequiredstring

A complete ssh command line, for pasting.

tokenrequiredstring

The short-lived credential the tunnel authenticates with. Shown once.

userrequiredstring

The login name to use. It is the sandbox id: a key is authorised for one name only.

DELETE/v1/sandboxes/{id}/ssh/{key_id}

Auth: API key

Revoke one key by id or fingerprint, and the access credential issued with it. Idempotent: revoked: false means neither existed.

Parameters

idrequiredpath · string

key_idrequiredpath · string

Answer 200 · SshRevoked · application/json

key_idrequiredstring

revokedrequiredboolean

sandbox_idrequiredstring

GET/v1/sandboxes/{id}/ssh/connect

Auth: API key · upgrades to a WebSocket

A WebSocket carrying the SSH byte stream, relayed byte for byte. Accepts either an API key or the short-lived per-sandbox credential from POST /v1/sandboxes/:id/ssh, in the Authorization header. This is what promigence sandbox ssh <id> --proxy speaks; you do not call it by hand.

Parameters

idrequiredpath · string