gRPC API

The boxd CLI, the SDKs, and the console are all clients of one thing: the public gRPC API at boxd.sh:9443. If your language doesn’t have a boxd SDK yet, generate one from the proto file and talk to it directly.

Installation

There is nothing to install from boxd’s side. Point a gRPC client at the endpoint, and generate stubs from the proto if your toolchain wants them.

Endpoint

boxd.sh:9443

Transport: HTTP/2 cleartext (h2c). There is no TLS on this port, and auth is short-lived JWTs.
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. Reflection also lists boxd.api.v1.DeviceBridge, the internal transport behind the client utilities, which is not part of the public surface.

The proto

The full service definition lives on its own page: Proto. Copy it into a local api.proto and generate stubs with protoc, buf, grpc_tools, or @grpc/proto-loader. You often don’t need the file at all. Server reflection is on, so the schema can be inferred straight from the endpoint, and grpcurl -plaintext boxd.sh:9443 describe boxd.api.v1.BoxdApi prints it on demand.

Authentication

Two steps: a long-lived API key is exchanged for a short-lived JWT, and the JWT rides as a bearer token on every gRPC call.

1. Create an API key

API keys are issued from the boxd console. Sign in at boxd.sh, open the API keys page, and create one. The raw key is shown once, so copy it immediately. The format is bxd_ followed by 43 base62 characters. You can also create them via the CLI once you’re logged in:

boxd auth login
boxd auth keys create my-app

2. Exchange for a JWT

Send the API key to the exchange endpoint on the console host, over HTTPS:

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..."
}

The JWT from an API-key exchange lives for 1 hour, so re-exchange before expiry. The endpoint is rate-limited per source IP.

3. Send it on every gRPC call

authorization: Bearer eyJhbGciOi...

Standard gRPC metadata. Most generated clients expose this as a per-call interceptor or call option.

What an API-key session can do

An API key is fenced to one org. A member key (the default) covers the machine, snapshot, checkpoint, disk, port, proxy, domain, and env/secret surface. An org key is a userless service credential that reaches only the org’s shared machines, and env/secret operations reject it too. A handful of RPCs additionally require a JWT from an interactive login (the browser or CLI device flow) and answer PERMISSION_DENIED to API-key sessions: CreateApiKey, ListApiKeys, DeleteApiKey, CreateToken, RevokeToken, LinkSshKey, CreateNetwork, ListNetworks, GetBilling, GetOrgBilling, and the checkout/portal calls. The practical consequence is that an API key can never mint more keys.

Commands

The full RPC surface is the service BoxdApi block in the proto: machines, snapshots, checkpoints, disks, ports, proxies, domains, env vars and secrets, organizations, tokens, and billing. What a given RPC expects is documented on its request message, and grpcurl describe dumps any of it on demand.

Hello world

grpcurl
Go
Node / TypeScript
Python

Easiest way to verify auth and reachability, with no proto file needed since server reflection is on.

# 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 -plaintext \
  -H "authorization: Bearer $BOXD_JWT" \
  boxd.sh:9443 boxd.api.v1.BoxdApi/Whoami

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

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

Install: brew install grpcurl or github.com/fullstorydev/grpcurl.

Save the proto as gen/api.proto, then generate stubs:

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

Hello world (main.go):

package main

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

    boxdv1 "yourmodule/gen"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    "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(insecure.NewCredentials()))
    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: "hello-grpc",
    })
    if err != nil { log.Fatal(err) }
    fmt.Printf("created %s at %s (%dms)\n",
        vm.Name, vm.Url, vm.BootTimeMs)
}

Save the proto as ./api.proto, then install runtime deps:

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

Hello world (hello.ts), using dynamic loading with no codegen step:

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.createInsecure(),
  );

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

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

main();

Save the proto as ./api.proto, then:

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

Hello world (hello.py):

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.insecure_channel("boxd.sh:9443") as ch:
        client = rpc.BoxdApiStub(ch)

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

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

if __name__ == "__main__":
    main()

Errors

Standard gRPC status codes. The most common ones you’ll hit:

Code	When
`UNAUTHENTICATED`	Missing/malformed/expired JWT, or `authorization` metadata not set
`PERMISSION_DENIED`	Valid JWT, but the caller may not do this (for example an API-key session calling an interactive-only RPC)
`NOT_FOUND`	VM, disk, snapshot, or domain doesn’t exist
`RESOURCE_EXHAUSTED`	Per-org VM quota reached
`INVALID_ARGUMENT`	Bad request shape (e.g. invalid VM name, conflicting fields)
`INTERNAL`	Server-side error

The error message in Status.message() is human-readable and safe to surface to users.

Streaming RPCs

Two RPCs stream:

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.

Getting started

Guides

Use cases

References

Installation

Endpoint

The proto

Authentication

1. Create an API key

2. Exchange for a JWT

3. Send it on every gRPC call

What an API-key session can do

Commands

Hello world

Errors

Streaming RPCs

​Installation

​Endpoint

​The proto

​Authentication

​1. Create an API key

​2. Exchange for a JWT

​3. Send it on every gRPC call

​What an API-key session can do

​Commands

​Hello world

​Errors

​Streaming RPCs

Installation

Endpoint

The proto

Authentication

1. Create an API key

2. Exchange for a JWT

3. Send it on every gRPC call

What an API-key session can do

Commands

Hello world

Errors

Streaming RPCs