---
title: "Client Sessions"
description: "Let browser clients operate existing Freestyle VMs with scoped access tokens."
url: "/docs/vms/client-sessions"
---

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

```ts title="server.ts"
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

```ts title="client.ts"
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.

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

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

Grant identities only the users they should access:

```ts
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.