gRPC API

​

Installation

​

Endpoint

boxd.sh:9443

• Transport. TLS, with the same certificate the cluster’s HTTPS domains use. Plain HTTP/2 (h2c) is still accepted on the same port so clients released before TLS keep working. New integrations should connect over TLS. Auth is short-lived JWTs either way.
• Reflection. gRPC server reflection (the v1 protocol) is enabled, so tools like grpcurl 1.9+ work without the proto file.
• Service. boxd.api.v1.BoxdApi.

​

The proto

​

Authentication

​

1. Create an API key

boxd auth login
boxd auth keys create my-app

​

2. Exchange for a JWT

curl -X POST https://app.boxd.sh/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key":"bxd_..."}'

{
  "token": "eyJhbGciOi...",
  "expires_at": 1735689600,
  "user_id": "usr_4f1c..."
}

​

3. Send it on every gRPC call

authorization: Bearer eyJhbGciOi...

​

What an API-key session can do

​

Commands

​

Hello world

# Set your JWT
export BOXD_JWT="$(curl -s -X POST https://app.boxd.sh/api/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"bxd_..."}' | jq -r .token)"

# Whoami
grpcurl \
  -H "authorization: Bearer $BOXD_JWT" \
  boxd.sh:9443 boxd.api.v1.BoxdApi/Whoami

# Create a machine
grpcurl \
  -H "authorization: Bearer $BOXD_JWT" \
  -d '{"name": "myapp"}' \
  boxd.sh:9443 boxd.api.v1.BoxdApi/CreateVm

# List machines
grpcurl \
  -H "authorization: Bearer $BOXD_JWT" \
  boxd.sh:9443 boxd.api.v1.BoxdApi/ListVms

cd gen
protoc --go_out=. --go_opt=paths=source_relative \
       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       api.proto

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "strings"

    boxdv1 "yourmodule/gen"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/metadata"
)

func exchange(apiKey string) string {
    body := strings.NewReader(`{"api_key":"` + apiKey + `"}`)
    resp, err := http.Post("https://app.boxd.sh/api/v1/auth/token",
        "application/json", body)
    if err != nil { log.Fatal(err) }
    defer resp.Body.Close()
    var out struct{ Token string }
    json.NewDecoder(resp.Body).Decode(&out)
    return out.Token
}

func main() {
    jwt := exchange("bxd_...")

    conn, err := grpc.NewClient("boxd.sh:9443",
        grpc.WithTransportCredentials(credentials.NewTLS(nil)))
    if err != nil { log.Fatal(err) }
    defer conn.Close()

    client := boxdv1.NewBoxdApiClient(conn)
    ctx := metadata.AppendToOutgoingContext(context.Background(),
        "authorization", "Bearer "+jwt)

    me, err := client.Whoami(ctx, &boxdv1.WhoamiRequest{})
    if err != nil { log.Fatal(err) }
    fmt.Println("user:", me.UserId)

    vm, err := client.CreateVm(ctx, &boxdv1.CreateVmRequest{
        Name: "myapp",
    })
    if err != nil { log.Fatal(err) }
    fmt.Printf("created %s at %s (%dms)\n",
        vm.Name, vm.Url, vm.BootTimeMs)
}

npm install @grpc/grpc-js @grpc/proto-loader

import * as grpc from '@grpc/grpc-js';
import * as protoLoader from '@grpc/proto-loader';

async function exchange(apiKey: string): Promise<string> {
  const r = await fetch('https://app.boxd.sh/api/v1/auth/token', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ api_key: apiKey }),
  });
  const { token } = await r.json();
  return token;
}

async function main() {
  const jwt = await exchange('bxd_...');

  const def = protoLoader.loadSync('./api.proto', {
    keepCase: true, longs: String, enums: String, defaults: true,
  });
  const proto = grpc.loadPackageDefinition(def) as any;

  const meta = new grpc.Metadata();
  meta.set('authorization', `Bearer ${jwt}`);

  const client = new proto.boxd.api.v1.BoxdApi(
    'boxd.sh:9443',
    grpc.credentials.createSsl(),
  );

  client.Whoami({}, meta, (err: any, me: any) => {
    if (err) throw err;
    console.log('user:', me.user_id);

    client.CreateVm({ name: 'myapp' }, meta, (err: any, vm: any) => {
      if (err) throw err;
      console.log(`created ${vm.name} at ${vm.url} (${vm.boot_time_ms}ms)`);
    });
  });
}

main();

pip install grpcio grpcio-tools requests
python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. api.proto

import grpc
import requests
import api_pb2 as pb
import api_pb2_grpc as rpc

def exchange(api_key: str) -> str:
    r = requests.post(
        "https://app.boxd.sh/api/v1/auth/token",
        json={"api_key": api_key},
    )
    r.raise_for_status()
    return r.json()["token"]

def main():
    jwt = exchange("bxd_...")
    meta = (("authorization", f"Bearer {jwt}"),)

    with grpc.secure_channel("boxd.sh:9443", grpc.ssl_channel_credentials()) as ch:
        client = rpc.BoxdApiStub(ch)

        me = client.Whoami(pb.WhoamiRequest(), metadata=meta)
        print("user:", me.user_id)

        vm = client.CreateVm(pb.CreateVmRequest(name="myapp"), metadata=meta)
        print(f"created {vm.name} at {vm.url} ({vm.boot_time_ms}ms)")

if __name__ == "__main__":
    main()

​

Usage and cost

# Every machine in the org, last 28 days
grpcurl \
  -H "authorization: Bearer $BOXD_JWT" \
  -d '{"org": "acme"}' \
  boxd.sh:9443 boxd.api.v1.BoxdApi/GetOrgUsage

# One machine over its whole life (also works after it is deleted)
grpcurl \
  -H "authorization: Bearer $BOXD_JWT" \
  -d '{"vm_id": "myapp", "org": "acme"}' \
  boxd.sh:9443 boxd.api.v1.BoxdApi/GetVmUsage

# What was actually charged
grpcurl \
  -H "authorization: Bearer $BOXD_JWT" \
  -d '{"org": "acme", "page_size": 100}' \
  boxd.sh:9443 boxd.api.v1.BoxdApi/ListBillingActivity

• Money. Amounts are in micro-units (1e-6) of the org’s currency ("eur" or "usd"), so cost_micro / 1e6 is the amount.
• Windows. Windows are unix seconds, [since, until), at most 366 days.
• Costs are estimates. Usage is metered every second and settled every 15 minutes, and costs are priced at the org’s current rates. ListBillingActivity is what was charged: one usage_charge per 15 minutes for the whole org.
• complete. The flag on a machine (and on the GetOrgUsage response) is true once all of its usage in the window is metered, so the figure will not grow. Metering lags by up to about 25 minutes. A machine that still exists is never complete in a window that runs to now. To record what a deleted machine cost, read it again until complete is true.
• Shared names. A deleted machine’s name can be reused. If several deleted machines carried the name you pass, GetVmUsage answers INVALID_ARGUMENT and lists their ids.

​

Machine specs

# Create a machine from a spec
grpcurl \
  -H "authorization: Bearer $BOXD_JWT" \
  -d '{"name": "mike-dev", "org": "acme", "spec": {"version": 1, "base": {"team": "eng"}, "size": "2x8", "networks": ["eng"], "connections": {"github": "shared:eng-bot"}, "agents": ["claude"], "packages": ["apt-get update", "apt-get install -y nginx"]}}' \
  boxd.sh:9443 boxd.api.v1.BoxdApi/CreateVm

# What a bigger size would change, without changing anything
grpcurl \
  -H "authorization: Bearer $BOXD_JWT" \
  -d '{"vm": "mike-dev", "patch": "{\"size\": \"4x16\"}", "dry_run": true}' \
  boxd.sh:9443 boxd.api.v1.BoxdApi/UpdateMachineSpec

# Run the packages again from the one that failed
grpcurl \
  -H "authorization: Bearer $BOXD_JWT" \
  -d '{"vm": "mike-dev", "patch": "{}", "retry_packages": true}' \
  boxd.sh:9443 boxd.api.v1.BoxdApi/UpdateMachineSpec

• The patch is a JSON string. patch is a JSON Merge Patch on the spec’s JSON form, the one the SDKs print (camelCase, so assignTo), sent as a string so that null and [] survive. A field it leaves out is untouched, a scalar replaces, maps merge key by key with null removing a key, and a list replaces the whole list. expected_spec is the spec you read, in the same form: if the machine’s spec is no longer that one, nothing is applied.
• All or nothing. A change that can’t apply (base, isolated and assign_to after creation, packages on a fork, a size change on standby or hibernated) refuses the whole patch, and so does a size change for a running machine without reboot. A resize that fails after the rest of the patch applied still answers OK, with applied true, rebooted false and resize_error set.
• Status codes. INVALID_ARGUMENT: a bad patch, or a spec the rules refuse, naming the field (spec.size: ...). PERMISSION_DENIED: a secret you may not list, assign_to your role or credential doesn’t allow (an org key, a token from inside a machine), or a change a machine may not make to itself from inside (its own egress or secrets). FAILED_PRECONDITION: a refused change, a reboot without reboot, or a machine without a spec. ABORTED: the spec changed while your update ran, and nothing was applied. Read it again and retry.
• Egress. A new allowlist from a spec update is in force within about a second of the response.

​

Errors

​

Streaming RPCs

• Exec is bidirectional. The first message must contain vm_id and command. Subsequent client messages with stdin=true pipe stdin, or window_change=true with cols/rows resize a PTY. Server messages carry data, with is_stderr set for stderr chunks on non-PTY execs (PTY-mode execs merge stderr into stdout at the kernel). The final server message has exit_code set. Closing the client’s send half signals stdin EOF to the subprocess.
• UploadFileStream is client-streaming and lifts the 4 MiB single-message gRPC cap of UploadFile. The first UploadFileChunk carries vm_id, path, and total_size, and subsequent chunks carry bytes only. The server reads exactly total_size bytes and returns the confirmed byte count.

​

Calling from a browser or Cloudflare Worker

• Content type. application/grpc-web+proto. Each message is one frame: a 1-byte flag, a 4-byte big-endian length, then the protobuf payload. The response ends with a trailer frame (flag bit 0x80 set) carrying grpc-status and grpc-message as key: value\r\n text. grpc-message is percent-encoded, so decode it before displaying it.
• CORS. Enabled, so a browser can call directly with no server-side proxy.
• Exec and UploadFileStream run half-duplex. The whole request (every message you’d have sent on a native gRPC stream) has to finish before the response starts streaming back, since fetch can’t read a response body while still writing the request body. This is already how exec() (send the command, read the result) and a file upload (send the bytes, read the confirmation) behave in every boxd SDK. The only thing that doesn’t work over grpc-web is an interactive PTY session, which needs a connection that’s live in both directions at once.

​

Minimal example (no library)

const jwt = await fetch("https://app.boxd.sh/api/v1/auth/token", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ api_key: "bxd_..." }),
}).then((r) => r.json()).then((r) => r.token);

// One grpc-web frame: [flag:1][length:4 BE][protobuf payload]
function frame(payload: Uint8Array): Uint8Array {
  const f = new Uint8Array(5 + payload.length);
  new DataView(f.buffer).setUint32(1, payload.length, false);
  f.set(payload, 5);
  return f;
}

const body = frame(WhoamiRequest.encode({}).finish()); // encode with your protobuf lib of choice

const resp = await fetch("https://boxd.sh:9443/boxd.api.v1.BoxdApi/Whoami", {
  method: "POST",
  headers: {
    "content-type": "application/grpc-web+proto",
    "authorization": `Bearer ${jwt}`,
  },
  body,
});

// Parse the response the same way: read 5-byte-prefixed frames from resp.body
// until the TRAILER frame (flag & 0x80), which carries grpc-status/grpc-message
// instead of a protobuf payload.