Client Sessions

Let browser clients operate existing Freestyle VMs with scoped access tokens.

Client sessions let a browser or end-user agent operate an existing VM without receiving your Freestyle API key. Your server creates an identity, grants VM permissions, creates a token, and sends that token to the client.

Issue A Client Token

import { freestyle } from "freestyle";

const { vm, vmId } = await freestyle.vms.create();

const { identity } = await freestyle.identities.create();
await identity.permissions.vms.grant({
  vmId,
});

const { token } = await identity.tokens.create();

return { token, vmId };

Use The Token In A Client

import { Freestyle } from "freestyle";

const freestyle = new Freestyle({
  accessToken: token,
});

const vm = freestyle.vms.ref({ vmId });
await vm.exec("pwd");

Scope Operations To A Linux User

By default, VM operations run as root. Use .user() when a client should operate as a specific Linux user.

const developerVm = vm.user({ username: "developer" });

await developerVm.fs.writeTextFile("/home/developer/notes.txt", "hello");

Grant identities only the users they should access:

await identity.permissions.vms.grant({
  vmId,
  allowedUsers: ["developer"],
});

Limits

Client session tokens are for operations on existing VMs. They should not be used as a replacement for your server-side API key or for letting users create arbitrary resources.

A client token can wake a suspended VM when it runs an operation, connects over SSH, or sends traffic to the VM.