Links, tokens and SSH

Эта страница ещё не переведена на язык «русский»: вот она на английском.

Links to its ports

GET /v1/sandboxes/{id}/url?port=3000 (glac sandboxes url web 3000) gives a link to that port: https://<port>-<sandbox id>-<signature>.glac.run/. The SDKs sign the link themselves, with no request (sbx.url(3000)).

• The link is the credential. Whoever has it can open the port, and from one port’s link another’s cannot be worked out. Nothing has to be registered first, and whoever opens the link wakes the sandbox.
• New links. POST /v1/sandboxes/{id}/url-secret changes the secret, and every old link stops working.
• Public ports. Ports in public_ports (--public-port 8080) also have a short link without a signature, https://<port>-<sandbox id>.glac.run/, that anyone may open.
• Your own domain can point at a port of a sandbox: POST /v1/domains with {domain, sandbox, port}, as for an app (addresses).
• Direct. A link reaches the sandbox through the proxy in front of the platform; the same first part under direct.glac.run skips it, for larger uploads, longer answers and protocols the proxy does not carry (addresses).

A request through a link counts as a request, and the answer as traffic out. Links are served under glac.run, apart from our own sites. Until glac.run is on the Public Suffix List, a page served under one name can set a cookie for all of glac.run that pages of other customers can read: do not trust cookies scoped to the whole domain.

Tokens for one sandbox

A token opens one sandbox, and nothing else, for a while. Give one to a browser, a user or a program that should reach this sandbox but not the project.

curl -X POST https://api.glac.ai/v1/sandboxes/web/tokens \
  -H "Authorization: Bearer $GLAC_API_KEY" -H 'Content-Type: application/json' \
  -d '{"scopes": ["exec", "files"], "expires_in_seconds": 3600}'

token = sbx.token(scopes=["url", "tty"], expires_in_seconds=600)

• Scopes: url (its ports’ links), exec (commands), files, tty (terminals). url unless you say.
• How long: an hour unless you say, 30 days at the most.
• How it is used: Authorization: Bearer st_…, in place of a key. A GET may carry it in ?sandbox_token= instead, for browsers, which cannot set headers on EventSource and WebSocket. On a link, a browser that comes with the token in the address is sent to the address without it, and the token is kept in a cookie scripts cannot read.
• With the command line: GLAC_API_KEY=st_… glac sandboxes exec web ls works for exec, cp, shell and url on that sandbox.
• A token lasts until it expires, or until the sandbox’s tokens are revoked: POST /v1/sandboxes/{id}/tokens/revoke (glac sandboxes tokens revoke web, sbx.revoke_tokens() in Python) refuses every token signed for the sandbox until then, and tokens asked for after it work as before.
• One token alone: the same call with {"token": "st_…"}, or with {"token_id": "tok_…"} (the id the token came with), refuses that token and no other, through restarts, sleeps and moves, until it would have expired: glac sandboxes tokens revoke web tok_…, sbx.revoke_token(token) in Python, and the MCP server’s sandbox_revoke_tokens with token. A sandbox keeps 1 000 such at the most (409 too_many_revoked_tokens past them): revoking every token makes room again.

SSH

Register a public key (POST /v1/ssh-keys), then any SSH client gets into the project’s sandboxes through the SSH gateway:

glac sandboxes ssh-keys add ~/.ssh/id_ed25519.pub --name laptop
glac sandboxes ssh web --gateway ssh.glac.ai     # prints the ssh, scp and sftp command lines
ssh web@ssh.glac.ai                              # a shell in the sandbox web
ssh web@ssh.glac.ai 'make test'                  # one command; its exit code is ssh's

• The user name is the sandbox, by id or name; <user>+<sandbox> runs as another user in it.
• A key opens every sandbox of the project, or only the one given (--sandbox web), until --expires-at. Only the public half is ever read; a file that holds a private key is refused.
• glac sandboxes ssh-keys rm ends the key’s sessions within half a minute.
• A session holds on through a restart of its sandbox’s machine (a release, for one): the sandbox sleeps through it with what runs in it, and the session waits for the machine to come back and goes on where it was. Nothing of what the command printed is lost or shown twice, and what you type meanwhile goes in once the machine is back. A machine that is not back within a minute ends the session, saying so.
• When the sandbox moves to another machine, or its machine is withdrawn, its sessions are told why and end, and ssh exits 255; a new session through a withdrawn machine is refused, with the reason. Connect again: after a move, the session reaches the sandbox where it is now, with its processes.
• Registering and deleting keys needs a key with the admin scope: a key that can register SSH keys can get into every sandbox of the project.