Lease a build host with the API
A build host is a machine you hold for a while under a lease. These are the requests behind sandscale build.
Build host routes live under your organization: /api/v1/orgs/{orgID}/build. sandscale whoami --json prints your organization ID as org_id. Every request is in the Build hosts and lab hosts API reference.
BUILD=https://api.sandscale.dev/api/v1/orgs/$ORG_ID/build
AUTH="Authorization: Bearer $SANDSCALE_API_KEY"
1. Pick a pool
curl "$BUILD/pools" -H "$AUTH"
A pool is a kind of machine an administrator has set up: its sizes, how long a lease may last, who may use it and whether a lease needs approval. You see only the pools you may lease from.
2. Take a lease
curl -X POST "$BUILD/pools/$POOL_ID/leases" -H "$AUTH" -H "Content-Type: application/json" \
-d '{"size": "SIZE", "ttl_seconds": 7200, "purpose": "release build", "repo": "github.com/acme/app"}'
size is one of the pool’s sizes. The answer is 201 with the lease: its id, state, size, expires_at, hard_expires_at and, once ready, its host. A pool that needs approval answers with the lease pending until someone approves it in the approvals inbox. Quotas for your organization, for you and for the pool are checked before anything starts. On a lab pool, devices asks for specific hardware.
3. Connect
Ask for a short-lived SSH certificate for your own public key:
curl -X POST "$BUILD/leases/$LEASE_ID/ssh/certificate" -H "$AUTH" -H "Content-Type: application/json" \
-d "{\"public_key\": \"$(cat ~/.ssh/id_ed25519.pub)\"}"
The answer has the certificate, its validity (valid_after, valid_before) and the ssh details to connect with. Interactive SSH counts as activity, so the lease does not end for being idle while you work.
4. Record runs
curl -X POST "$BUILD/leases/$LEASE_ID/runs" -H "$AUTH" -H "Content-Type: application/json" \
-d '{"argv": ["make", "release"], "cwd": "/workspace/app"}'
A run is recorded before it starts, so the lease keeps a history of what ran, with exit codes and logs. GET .../leases/{leaseID}/runs lists them. Build artifacts and caches are kept with the lease and the pool.
5. Renew or release
curl -X POST "$BUILD/leases/$LEASE_ID/renew" -H "$AUTH" -H "Content-Type: application/json" -d '{"ttl_seconds": 3600}'
curl -X POST "$BUILD/leases/$LEASE_ID/release" -H "$AUTH"
A renewal can never pass the lease’s hard_expires_at. When a lease ends, by release, expiry, idleness or the kill switch, its cloud host is deleted and a lab host is torn down before anyone else can lease it. A request on a lease that has ended answers 409 lease_expired.